incu-way-bugs

Bug Fix Process

一个结构化、由关卡驱动的工作流，可在不靠猜测的情况下修复 Bug。从发现和接收问题开始，然后依次进行 Bug 文档编写、分析、复现、修复规划、实现、验证和 PR 审查。关键关卡仍是确认修复计划：用户批准计划之前，不编写任何修复代码。

---

仓库资格检查（优先执行）

在 Phase 0 之前，检查 ~/.ways/config.yaml 中的 blacklist（格式：incu-base 的 global-config 规则，始终启用）， 确认当前仓库是否匹配。如果匹配，请告知用户该仓库已被 incu-way 列入黑名单， 并询问是仍要继续（仅此一次例外）还是停止；在用户答复之前，不要运行任何阶段。 文件不存在或没有匹配项：正常继续。

---

Phase 0 — 发现和接收问题

开始处理之前：

1. 阅读 PRD.md 和 docs/ 中的相关文档，了解受影响的功能。
2. 检查 docs/bugs/，查看是否有相关的现有报告。如果此问题在 docs/requirements/{slug}/TICKET.md 中有经过完善的工单（由 incu-way-po 生成），请先阅读并核实其中的可行性说明和范围，而不是重新推导。
3. 澄清问题接收信息：
   • 报告的问题是什么
   • 实际应当发生什么
   • 受影响的对象是谁
   • 环境、严重程度和业务影响
   • 哪些细节仍然缺失或未经核实
4. 了解代码库背景：
   • 受影响的功能区域或工作流
   • 相关模块、函数、测试或集成
   • 可能引入回归问题的近期提交或发布
   • 定义预期行为的既往 Bug 报告、PRD 或决策
   • 同一产品中可能存在相同回归问题的其他仓库——检查中心仓库的 CLAUDE.md 是否有 repos: 部分（若存在则以此为准）；否则回退到 ~/.ways/config.yaml 中的 linkedRepos（格式：incu-base 的 global-config 规则，始终启用）
5. 根据具体情况调整发现工作的深度：
   • 对于范围较小且情况明确的 Bug，轻量检查即可
   • 对于含糊、严重程度高或影响生产环境的问题，应在分析和规划修复前深入调查
6. 如果 Bug 报告缺少关键细节，请先提出有针对性的澄清问题，再继续。

Phase 0 退出条件

进入 Phase 1 之前，Claude 应能够说明：

• 目前已知的问题和预期行为
• 受影响的对象或内容
• 可能涉及的文档、模块、提交或工作流
• 当前所作的假设
• 分析期间或与用户沟通时仍需确认的事项

不要仅仅因为 Bug 报告听起来合理，就假定预期行为、根本原因或修复方向。如果重要细节不明确，请明确指出其中的不确定性。

---

隔离设置（Phase 0 后立即执行）

创建任何文件之前，询问用户希望如何隔离这项工作：

你希望我在当前检出中创建一个新分支来处理，还是创建一个单独的 git worktree？

严格按照用户的回答操作： 询问后立即停止；在用户选择之前，不要创建分支或 worktree。

如果当前检出有未提交的更改，在切换分支或创建 worktree 之前停止并询问。

选项 A — 在当前检出中创建分支

git switch develop
git pull --ff-only
git switch -c fix/{slug}

所有工作——BUG.md、ANALYSIS.md、测试和修复代码——都在当前检出中的此分支上进行。绝不要直接向 develop 或 main 写入文件。

选项 B — 单独的 worktree

仅在 .worktrees/ 下创建 worktree。不要向用户询问路径。

git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/fix-{slug} -b fix/{slug} origin/develop

所有工作——BUG.md、ANALYSIS.md、测试和修复代码——都只能在此 worktree 中进行。

---

状态跟踪 — .ways/state.json

遵循 ways/v1alpha1 状态契约——规范的 .ways/state.json 格式（schemaVersion 2）。它以始终启用的 state-contract 规则形式提供，由 ways add 放入项目中，因此已在你的上下文中（无需指定路径）。此仓库中供维护者参考的源文件位于 ways/rulepacks/state-contract/。请勿在此技能中复制或臆造架构。

与流程相关的值：

• flow：bug
• way：incu/bugs · discipline：development（可选从 way 清单中获取 wayVersion）
• 分支模式：fix/{slug}
• 初始 phase：discovery
• isolationType：branch 或 worktree，取自 Phase 0 中的隔离方式选择
• 文档：docs/bugs/{slug}/BUG.md、docs/bugs/{slug}/ANALYSIS.md、docs/bugs/{slug}/FIX_PLAN.md
• 门禁：fix-plan、pr

会话开始时，如果 .ways/state.json 存在，则读取它。如果其 branch 与当前的 fix/{slug} 分支匹配，报告当前阶段、下一步和待处理的门禁，并从该状态恢复。如果文件不存在，或者存在但其 branch 不匹配（这是从已合并条目继承的过期文件），则从 Phase 0 开始，并在选定隔离设置后立即创建或覆盖 .ways/state.json。每次转换时，还要更新 lastPhase（即将离开的阶段）。

更新节点（阶段 → 写入内容）：

时机	phase	文档 / 门禁 / 步骤
写入 BUG.md	document	BUG.md → approved
写入 ANALYSIS.md	analysis	ANALYSIS.md → approved
添加复现测试（失败）	reproduction	—
起草 FIX_PLAN.md	fix-plan	FIX_PLAN.md → in-review
门禁通过（修复计划）	implementation	FIX_PLAN.md → approved；门禁 fix-plan → passed；根据修复计划生成 steps——每项可执行的变更对应一条记录，全部标为 todo
实施期间	implementation	将每个步骤标记为 in-progress → done（或 blocked）——每完成一步就立即写入状态文件，切勿等到阶段结束后批量写入
验证	validation	—
打开 fix→develop PR	pr	门禁 pr → 仍为 pending；将其 url 设置为 PR 链接
PR 合并	done	门禁 pr → passed

请勿自行提交 .ways/state.json——只需写入即可。用户想要保存检查点时，建议调用 incu-way-prepare-pr，由它将该检查点与对应转换的文档和代码一起提交。

---

阶段 1 — 记录 Bug

保存位置：

docs/bugs/{bug-slug}/BUG.md

Slug 格式： {zero-padded-id}-{kebab-description} 示例：001-import-totals-zero、002-contact-dedup-missing

查找下一个 ID — 检查所有可能已占用该 ID 的位置，而不只是当前检出。 如果计数器只检查当前分支，一旦有两个 Bug 并行处理，或两个从同一基线创建的工作树／分支各自独立算出相同的“下一个”编号，就会发生冲突；实际上这种情况已经发生过（当时涉及 PRD；这里的计数器形式也会面临同样的问题）。仅扫描并不能解决这个问题：两个 Agent 可能在同一时刻扫描，都算出相同的编号，然后才创建各自的目录。在一台机器上，扫描和预留期间必须持有锁，才能避免这种情况：

0. 在扫描任何内容之前，获取一把同一机器上的锁：

   LOCK="$(git rev-parse --git-common-dir)/incu-way-bug-slug.lock"
   until mkdir "$LOCK" 2>/dev/null; do sleep 0.2; done
   trap 'rmdir "$LOCK"' EXIT
   

   mkdir 每次只会有一个进程成功；--git-common-dir 会从本仓库的每个工作树解析到相同的共享路径，因此锁对所有工作树可见。锁名要与 incu-way-development／incu-way-po 使用的锁名区分开来，因为 docs/bugs/ 有自己的 ID 空间，不与 docs/prds/／docs/requirements/ 共用。
1. 列出当前检出中 docs/bugs/ 已使用的 ID。
2. 列出此仓库的所有其他工作树（git worktree list），并检查它们的 docs/bugs/。相邻工作树中的 Bug 文档不会出现在此处的 git status 中，但它们就在磁盘上。
3. 获取默认分支（git fetch origin {default}），并列出该分支上已合并的内容（git ls-tree --name-only origin/{default} -- docs/bugs/）。其他人自此分支创建以来合并的 ID 尚不会出现在本地树中。

从以上三处找到的最高 ID 加 1，并在释放锁之前立即创建 docs/bugs/{id}-{slug}/（即使只创建一个空占位文件也能预留 ID）。只有这之后才能释放锁（上面的 trap 会自动处理，包括失败时）。真正避免同一机器上竞争的是持锁期间完成预留，而不是单纯扫描。

BUG.md 结构

# Bug — {Short Description}

## Status
Reported | Analyzing | Fix Planned | Fixing | Fixed

## Description
What is happening vs. what should happen.

## Steps to reproduce
1.
2.

## Expected behavior

## Actual behavior

## Context
- Environment: local / staging / production
- Affected commit / version:
- Affected users or records:
- Severity: Low / Medium / High / Critical

## Logs / stack trace

---

阶段 2 — 分析

保存位置：

docs/bugs/{bug-slug}/ANALYSIS.md

ANALYSIS.md 结构

# Analysis — {Bug Description}

## Root cause
What is the actual underlying cause.

## Affected code
Files, functions, or modules involved.

## Impact
How many users/records affected. Any data integrity risk.

## Reproduction path
How to reliably trigger the bug.

在分析和复现证据支持之前，不要将疑似根因视为已确认。

---

阶段 3 — 复现测试

编写任何修复代码之前，先编写一个因该 Bug 而失败的测试：

1. 编写一个用于验证该异常行为的单元测试或端到端测试。
2. 运行测试 — 在当前代码库中，它必须失败。
3. 建议调用 incu-way-prepare-pr 提交该测试（test(fix-{slug}): add reproduction test for {bug description}）——不要自行提交。

pnpm test  # Must FAIL — confirms the bug is reproduced

复现测试通过，即为“已修复”的判定标准。

如果无法通过测试复现该 Bug，请在 ANALYSIS.md 中说明原因，并在继续之前告知用户。

不要借复现阶段偷偷加入修复。此阶段的目的是证明当前行为存在问题。

---

阶段 4 — 修复计划

保存位置：

docs/bugs/{bug-slug}/FIX_PLAN.md

FIX_PLAN.md 结构

# Fix Plan — {Bug Description}

## Branch / worktree
Branch: fix/{slug}
Isolation mode: current checkout branch | separate worktree

## Root cause (one line)

## Fix approach
What will be changed and why.

## Files affected

## Risks / side effects
Could this fix break anything else?

## Rollback
How to revert if the fix introduces a regression.

检查关卡 — 确认修复计划

写好修复计划后：

• 说："修复计划已准备好，位于 docs/bugs/{slug}/FIX_PLAN.md。请先审核，然后我再开始编写代码。"
• 停止。用户表示 OK 之前，不要编写任何修复代码。

---

阶段 5 — 实施

用户批准修复计划后：

规则

• 只修复修复计划中描述的内容 — 不做额外清理。
• 在每个检查点运行 pnpm typecheck && pnpm lint && pnpm test，然后建议调用 incu-way-prepare-pr 提交 — 不要自行提交。
• 修复后，阶段 3 中的复现测试必须通过。
• 现有测试不得出现回归。

建议的提交格式（供 incu-way-prepare-pr 使用）

fix({slug}): {short description}

- Root cause: {one line}
- Tests: {what covers the fix}

---

阶段 6 — 验证

创建 PR 前的检查清单：

• 阶段 3 中的复现测试通过
• 所有现有测试均通过（pnpm test、pnpm test:e2e）
• pnpm typecheck 以状态码 0 退出
• pnpm lint 以状态码 0 退出
• pnpm build 成功
• 现有测试中没有回归问题
• BUG.md 状态已更新为 Fixed
• Snyk 代码扫描无问题（没有新问题）
• Snyk 依赖扫描无问题（没有新问题）
• SonarQube 扫描无问题（没有新问题）

安全扫描

流程与开发技能相同。针对选定的工作位置运行全部三项扫描。修复由此次修复提交引入的所有问题。

Snyk SAST：

snyk_code_scan: path=<absolute path to the selected working location>, severity_threshold=low

Snyk SCA：

snyk_sca_scan: path=<absolute path to the selected working location>, severity_threshold=low, all_projects=true

SonarQube：

bash run-sonar.sh

如果 snyk_code_scan、snyk_sca_scan 或 run-sonar.sh 不可用，请在 docs/bugs/{slug}/ANALYSIS.md 中记录缺失的工具，注明失败的确切命令或工具名称，并询问用户是要安装或配置该工具，还是仅使用可用的验证方式继续。扫描未运行时，不要报告扫描结果无问题。

修复循环：处理问题 → pnpm typecheck && pnpm lint && pnpm test → 建议调用 incu-way-prepare-pr 进行提交 → 重新扫描 → 重复以上步骤，直到扫描无问题。

---

阶段 7 — PR

验证通过后，建议调用 incu-way-prepare-pr 推送 fix/{slug} 并创建 PR。不要自行推送或运行 gh pr create。

供 incu-way-prepare-pr 使用的 PR 标题和正文建议：

Title: fix({slug}): {short description}

PR 正文必须包含：

• Bug： 链接到 docs/bugs/{slug}/BUG.md
• 根本原因： 一行说明
• 修复： 简要说明更改了什么以及原因
• 测试： 复现测试名称及添加的其他覆盖
• 检查清单： 类型检查 ✅ lint ✅ 测试 ✅ 构建 ✅ snyk-code ✅ snyk-deps ✅ sonarqube ✅

PR 创建后，将 PR URL 分享给用户。停止操作。在用户批准前不要合并。

---

每个 Bug 的文件布局

docs/bugs/{bug-slug}/
  BUG.md          # Bug report (Phase 1)
  ANALYSIS.md     # Root cause analysis (Phase 2)
  FIX_PLAN.md     # Fix approach + gate (Phase 4)

---

快速参考 — 检查关卡

关卡	触发条件	需要说什么	阻塞至
1	修复计划已编写	“修复计划已准备好，位于 docs/bugs/{slug}/FIX_PLAN.md。请审核。”	用户表示 OK
2	验证通过	建议调用 incu-way-prepare-pr 创建 PR（fix→develop）；用户运行后分享 URL	用户批准 PR

---

不要做的事

• 用户批准修复计划前，不要编写修复代码。
• 不要修复计划以外的问题——额外改进应放在功能分支中。
• 不要跳过复现测试——如果无法复现 Bug，请在 ANALYSIS.md 中说明并询问用户。
• 不要在没有文档、分析、测试或用户澄清作为依据时，擅自认定预期行为、根本原因或正确的修复方案。
• 不要把不完整的 Bug 报告转化为确定的修复计划——先指出缺少的信息。
• 宣布完成前，不要跳过 pnpm typecheck && pnpm lint && pnpm test。
• 绝不要直接合并——始终通过 PR 合并。
• 绝不要直接操作 develop 或 main——使用用户选择的隔离模式。