Back to Details

fix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fix

缺陷修复

Overview

概述

Use this skill to resolve bugs through a structured flow:
  1. Intake a clear bug report
  2. Reproduce and isolate root cause
  3. Apply the smallest safe fix
  4. Verify with focused and project-wide checks
  5. Document what changed and why
Prefer correctness and safety over speed. Do not guess.
使用此技能通过结构化流程解决缺陷：
  1. 接收清晰的缺陷报告
  2. 复现并定位根本原因
  3. 应用最小化的安全修复方案
  4. 通过针对性检查和全项目检查进行验证
  5. 记录变更内容及原因
优先考虑正确性和安全性，而非速度。禁止主观猜测。

Workflow

工作流程

Step 1: Bug Report Intake

步骤1：缺陷报告接收

Collect or confirm the minimum required issue context before changing code.
Required intake fields:
  • Title: short bug summary
  • Expected behavior: what should happen
  • Actual behavior: what happens now
  • Reproduction steps: exact steps/inputs
  • Evidence: logs, stack trace, screenshots, failing test output
  • Environment: branch, OS/runtime, app version/commit (if available)
  • Impact: severity and affected users/areas
If key fields are missing, ask targeted follow-up questions first.
在修改代码前，收集或确认所需的最低限度问题上下文。
必填接收字段：
  • 标题： 简短的缺陷摘要
  • 预期行为： 应该出现的结果
  • 实际行为： 当前实际出现的结果
  • 复现步骤： 精确的步骤/输入信息
  • 证据： 日志、堆栈跟踪、截图、失败的测试输出
  • 环境： 分支、操作系统/运行时、应用版本/提交记录（如有）
  • 影响范围： 严重程度及受影响的用户/业务区域
若关键字段缺失，先提出针对性的跟进问题。

Step 2: Reproduce and Diagnose

步骤2：复现与诊断

  1. Reproduce the issue consistently.
  2. Locate the failure point (file, function, line range, or subsystem).
  3. Trace data/control flow to identify the root cause.
  4. Define a fix hypothesis and confirm it explains the observed behavior.
Guidelines:
  • Read surrounding code, not just the failing line.
  • Prefer root-cause fixes, not symptom patches.
  • Add temporary diagnostics/logging only if needed to isolate behavior.
  • Remove or clean up temporary diagnostics after verification.
  1. 持续稳定复现问题。
  2. 定位失败点（文件、函数、代码行范围或子系统）。
  3. 追踪数据/控制流以确定根本原因。
  4. 提出修复假设并确认其能解释观察到的行为。
指导原则：
  • 阅读故障代码周围的相关代码，而非仅关注报错行。
  • 优先修复根本原因，而非仅修补表面症状。
  • 仅在需要隔离行为时添加临时诊断/日志。
  • 验证完成后移除或清理临时诊断代码。

Step 3: Complexity Gate (Go / No-Go)

步骤3：复杂度校验（继续/终止）

Classify the fix before implementation:
在实施前对修复方案进行分类：

Simple Fix (proceed in this skill)

简单修复（继续使用此技能）

All or most are true:
  • Clear root cause
  • Localized change (small surface area)
  • Low architectural risk
  • Limited file impact
  • Verification path is straightforward
满足以下全部或大部分条件：
  • 根本原因明确
  • 变更局部化（影响范围小）
  • 架构风险低
  • 文件影响有限
  • 验证路径清晰直接

Complex/Risky Fix (stop and route to 
write-plan
)

复杂/高风险修复（终止并转至
write-plan
流程）

Any are true:
  • Root cause still unclear
  • Cross-cutting or architectural changes needed
  • Significant refactor or migration involved
  • High regression risk
  • Multi-phase rollout required
  • External dependency or infra uncertainty
If complex, stop and recommend creating a plan with 
write-plan
.
满足以下任一条件：
  • 根本原因仍不明确
  • 需要跨模块或架构层面的变更
  • 涉及重大重构或迁移
  • 回归风险高
  • 需要分阶段部署
  • 存在外部依赖或基础设施不确定性
若属于复杂修复，请停止当前流程并建议使用
write-plan
创建修复计划。

Step 4: Implement the Fix (Simple Path)

步骤4：实施修复（简单路径）

  1. State a brief fix plan in 1-3 bullets.
  2. Apply minimal, targeted code changes.
  3. Keep behavior changes explicit and scoped.
  4. Add/adjust tests to prevent regression when applicable.
Implementation rules:
  • Avoid unrelated refactors.
  • Preserve existing conventions and project standards.
  • Keep changes idempotent and safe to re-run where relevant.
  1. 用1-3个要点简述修复计划。
  2. 应用最小化、针对性的代码变更。
  3. 明确且限定行为变更的范围。
  4. 适用时添加/调整测试以防止回归。
实施规则：
  • 避免无关的重构操作。
  • 遵循现有代码规范和项目标准。
  • 相关变更需保持幂等性，且可安全重新执行。

Step 5: Verify

步骤5：验证

Run verification in increasing scope:
  1. Focused checks for the affected module/feature
  2. Regression checks for nearby behavior
  3. Project checks as relevant (lint/typecheck/tests/build)
Bug is fixed only when:
  • Reproduction no longer fails
  • Expected behavior is confirmed
  • No critical regressions introduced
If verification fails unexpectedly, stop and reassess diagnosis.
按范围递增的顺序执行验证：
  1. 针对性检查：针对受影响的模块/功能
  2. 回归检查：针对周边相关行为
  3. 全项目检查：如相关的代码检查/类型检查/测试/构建
只有满足以下条件时，缺陷才算修复完成：
  • 复现步骤不再触发失败
  • 确认符合预期行为
  • 未引入严重回归问题
若验证意外失败，请停止并重新评估诊断结果。

Step 6: Complete and Report

步骤6：完成与报告

Provide a concise completion report:
  • Root cause
  • What changed
  • Why this fix works
  • Verification performed and results
  • Residual risks / follow-ups (if any)
If architecture, codebase structure, or product behavior changed materially, update documentation artifacts (typically 
docs/project-pdr.md
, 
docs/codebase.md
, 
docs/architecture.md
) via the 
docs
workflow.
提供简洁的完成报告：
  • 根本原因
  • 变更内容
  • 修复生效的原因
  • 执行的验证及结果
  • 剩余风险/后续工作（如有）
若架构、代码库结构或产品行为发生实质性变更，请通过
docs
工作流更新文档制品（通常为
docs/project-pdr.md
、
docs/codebase.md
、
docs/architecture.md
）。

Rules

规则

  • No guessing: ask when critical context is missing.
  • Root cause first: never ship symptom-only patches knowingly.
  • Smallest safe change: minimize blast radius.
  • Verify before done: no fix is complete without checks.
  • Escalate complexity: use 
    write-plan
    for risky/broad changes.
  • Follow project docs: align with 
    docs/
    guidance, especially 
    docs/code-standard.md
    .
  • 禁止猜测：关键上下文缺失时请提问。
  • 先找根本原因：切勿明知仅修复表面症状却仍发布。
  • 最小化安全变更：尽量缩小影响范围。
  • 验证后再完成：未经过检查的修复不算完成。
  • 升级复杂问题：对高风险/大范围变更使用
    write-plan
    流程。
  • 遵循项目文档：对齐
    docs/
    中的指导，尤其是
    docs/code-standard.md
    。

Optional Bug Report Template

可选缺陷报告模板

Use this template when the user provides an incomplete issue report:
  • Title:
  • Expected behavior:
  • Actual behavior:
  • Reproduction steps:
  • Error logs/stack trace:
  • Environment:
  • Impact/severity:
  • Additional context:
当用户提供的问题报告不完整时，使用此模板：
  • 标题：
  • 预期行为：
  • 实际行为：
  • 复现步骤：
  • 错误日志/堆栈跟踪：
  • 环境：
  • 影响范围/严重程度：
  • 额外上下文：