Back to Details

as-fix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fix

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.
使用本技能通过结构化流程解决bug：
  1. 接收清晰的bug报告
  2. 复现问题并定位根本原因
  3. 采用最小范围的安全修复方案
  4. 通过针对性检查和项目全量检查验证修复效果
  5. 记录变更内容及变更原因
优先保障正确性与安全性而非速度，请勿随意猜测。

Workflow

工作流程

Step 1: Bug Report Intake

步骤1：Bug报告接收

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.
修改代码前先收集或确认必填的问题上下文。
必填接收字段：
  • Title: 简短的bug摘要
  • Expected behavior: 预期运行表现
  • Actual behavior: 当前实际表现
  • Reproduction steps: 准确的复现步骤/输入
  • Evidence: 日志、stack trace、截图、失败的测试输出
  • Environment: 分支、OS/运行时、应用版本/commit（如有）
  • Impact: 严重程度及受影响的用户/功能范围
如果缺少关键字段，请先提出针对性的跟进问题。

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. 相关的项目级检查（lint/类型检查/测试/构建）
仅当满足以下条件时才算修复完成：
  • 复现步骤不再触发异常
  • 预期表现得到确认
  • 未引入严重回归
如果验证意外失败，请停止操作，重新评估诊断结果。

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: 
    Question Tool
    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.
  • 禁止猜测： 缺少关键上下文时使用
    Question Tool
  • 优先定位根本原因： 不得在知情的情况下上线仅修复表面症状的补丁
  • 最小安全变更： 尽可能缩小影响范围
  • 完成前必须验证： 未经过检查的修复不算完成
  • 复杂问题升级： 高风险/大范围变更使用
    write-plan

Optional Bug Report Template

可选Bug报告模板

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:
当用户提供的问题报告不完整时使用本模板：
  • Title:
  • Expected behavior:
  • Actual behavior:
  • Reproduction steps:
  • Error logs/stack trace:
  • Environment:
  • Impact/severity:
  • Additional context: