in commit abc123 but the stored hashes were not re-hashed").
```markdown
## Root Cause Analysis
**Symptom**: {error message or wrong behavior}
**Proximate cause**: {file}:{line} — {what the code does wrong}
**Root cause**: {underlying defect — config, data, logic, or assumption}
**Introduced in**: {commit hash or version if known}
```
**Rules**:
- If you're fixing a symptom (e.g. adding a null check where the real bug is
that null should never reach that line), stop and go deeper.
- If you can't find the root cause after examining 3 levels of indirection,
pause and report findings. Do NOT apply a surface-level patch.
- **After Phase 2, evaluate the routing decision** (see Routing Decision table
above). If the fix qualifies for pipeline mode, pause and present the
escalation prompt before proceeding to Phase 3.
---
#### Phase 3 — Write a Regression Test
Before fixing, write a test that proves the bug exists:
1. Write a test that exercises the bug path with the failing inputs.
2. Run the test — it MUST fail with the bug's symptom.
3. The test must be specific: test the exact condition that was broken, not
a general "endpoint returns 200" test.
```markdown
## Regression Test
- **File**: {path to test file}
- **Test name**: {test function name}
- **What it verifies**: {the expected behavior that was broken}
- **Fails before fix**: ✅ (confirmed)
```
**Rules**:
- If you cannot write a test that fails (bug is non-deterministic, environment-
specific), write the most targeted test you can and mark it `[flaky]`.
- The test must fail NOW, before you apply the fix. If it passes already, the
test does not cover the bug.
---
#### Phase 4 — Fix
Apply the minimum change that resolves the root cause:
1. **One conceptual change per fix** — do not bundle a bugfix with refactoring,
style changes, or "while I'm here" improvements.
2. **Fix the root cause**, not the symptom. If the root cause is in a different
file than the symptom, fix it there.
3. **Update only what's necessary** — if fixing a null-safety bug requires
adding a null check in one place, add one null check, not a comprehensive
null-safety overhaul of the entire module.
4. Run the regression test — it MUST pass.
5. Run the relevant unit tests — all existing tests must still pass.
---
#### Phase 5 — Self-Check & Report
##### Self-Check
1. **Typecheck**: `bun typecheck` — zero errors.
2. **Lint**: `bun oxlint --deny-warnings` — zero errors.
3. **Full test suite**: `bun run test:parallel` — all tests pass (new + existing).
4. **Checklist**: verify every item in `core/checklists/bugfix.md`.
5. **Publish bugfix report**: write the bugfix report as a wiki page via `wiki 读写 API（见 TERMINOLOGY）` with page_name `{slug}/bugfix-report` (`_shared/gitea-write-patterns.md` Pattern 1).
##### Report
```markdown
## Bugfix Report
**Bug**: {one-line description}
**Root cause**: {file}:{line} — {explanation}
**Fix**: {file} — {single-sentence description of change}
In standalone-bugfix mode there are no skill-exit boundaries between commit,
PR, review, and CI — without explicit sync points the issue goes stale. Per
the `issue-checklist-sync` L1 rule, sync at each externally visible
transition (skip any step if no source issue exists):
| When | Sync action |
|------|-------------|
| After the fix commit | Check off fix-delivered ACs with `_(commit {sha}: file)_` |
| After PR creation | Ensure the `## 当前状态` section exists (the PR row is auto-written by the status-sync poller — see `issue-checklist-sync.md` § Automated sync) |
| After review convergence | Review-related ACs get `_(reviewed: round N PASS)_` (done by review-code Phase E 2.7) |
| On CI state transitions | Update process-AC progress (e.g. "N consecutive green") with run number |
| At verify PASS / close | Final sweep per `verify` Phase 5.6 |
Bugfix mode delegates the "after commit" step to the same mechanics as Phase
4.6 above (fetch issue body → map `- [ ]` items → `工单 API（见 TERMINOLOGY）update`), and
Bugfixes fail from **pressure and false confidence** far more than from
ignorance — "the bug is obvious" is the thought that precedes a symptom patch,
a bundled diff, or a regression that surfaces weeks later. These are the
excuses that precede every reopened bug. If you catch yourself thinking any
row's "Excuse", stop: the "Reality" column is the exact rule you are about to
break.
| Excuse | Reality (the rule being broken) |
|--------|---------------------------------|
| "Just add a null check where it crashes" | Symptom-patching. Phase 2: if you are fixing a symptom, stop and go deeper — the real defect is whatever let null reach that line. |
| "Can't reproduce, but I'm sure it's X" | Phase 1: if the bug cannot be reproduced, stop and report. Guess-patching a non-reproduced bug fixes nothing verifiable. |
| "3 levels deep, can't find it, patch the symptom" | Phase 2: after 3 levels of indirection with no root cause, pause and report — do NOT apply a surface patch. |
| "Bug's obvious, I'll fix then add the test" | Phase 3: the regression test MUST fail before the fix. Fix-first means you test your fix, not the bug. |
| "Test passed immediately, ship it" | Phase 3 Rules: a test that passes before the fix does not cover the bug — rewrite it until it fails. |
| "While I'm in this file, also clean up…" | Phase 4 rule 1: one conceptual change per fix. Bundling refactors/style/other-fixes pollutes the regression signal. |
| "Make the whole module null-safe while I'm here" | Phase 4 rule 3: update only what is necessary. Over-fixing turns a 3-line surgical fix into a high-risk diff. |
| "Fix is isolated, skip the full suite" | Phase 4 rule 5 + Phase 5: the full suite catches regressions your isolated view cannot. |
| "4 files but one module, standalone's fine" | Routing Decision: escalate when uncertain. A false-standalone call skips quality gates on a complex change. |
##### Incident Triage Carve-Out
When the bugfix occurs under **active production incident** pressure
(user-facing outage, on-call escalation), the Phase 2→3 ordering can be
**temporarily relaxed** — but never skipped:
1. A stop-gap (symptom patch) MAY ship first to restore service.
2. BUT the full root-cause trace + failing regression test + proper
root-cause fix MUST land in the **same incident window** — never deferred
to "tomorrow" or "a follow-up ticket".
3. If you defer, you have not fixed the bug — you have shipped a symptom patch
with a promise. Promises are not regression tests.
This carve-out exists because the rationalization table above cannot resolve a
*legitimate* priority conflict (service down vs process discipline). It
resolves it by permitting triage but forbidding deferral.
---
#### Pipeline Mode (bugfix)
> **Legacy path retired ([org-internal #3072] phase 3, 2026-08-21)**: the full
> plan-iterations → review-artifact(plan) front-end was archived
> (`<instance-root>/archive/skills/`). A big bug that needs a design-level decision
> now relabels `Kind/Feature` and enters the DAG route (see the big-bug
> relabel rule above) — repro + root-cause notes carry over as node input.
> The abort criteria below still apply to any multi-stage bug run before
> code is written.
When a bugfix escalates beyond standalone scope, the bug report becomes a
pipeline input; the original bugfix phases (reproduce, root cause, regression
test, fix) are embedded within the implement stage, and review-code + verify
remain mandatory gates.
##### Pipeline Abort Criteria
Before any code is written in pipeline mode, abort the pipeline if ANY of:
| # | Condition | Action |
|---|-----------|--------|
| 1 | Bug no longer reproduces after environment change (strace re-isolation returns 0 reproductions, user confirms symptom resolved) | Write ABORT to wiki page `{slug}/ABORT` (wiki 读写 API（见 TERMINOLOGY）), preserve all completed artifacts, run retrospective |
| 2 | Root cause hypothesis is falsified during re-isolation (e.g., strace shows suspected git spawn is NOT hanging) | Write ABORT.md, escalate to Architect for design revision OR abort pipeline |
| 3 | Bug is resolved by external change (new binary build, dependency update, OS/kernel patch) | Write ABORT.md with resolution evidence, close without code changes |
| 4 | Reproduction confidence < 3/5 after re-isolation attempt | Write ABORT.md if confidence cannot be improved within 1 re-isolation iteration |
**Abort procedure**:
1. Write ABORT to wiki page `{slug}/ABORT` (wiki 读写 API（见 TERMINOLOGY）) documenting the reason, evidence, and which artifacts are preserved.
2. Do NOT commit or merge the bugfix branch (no code was written).
3. Run retrospective to extract process improvements.
4. Archive artifacts to wiki page `_archive/{slug}/` (wiki 读写 API（见 TERMINOLOGY）) after retrospective.
**Scope**: these criteria apply before the implement stage. Once code is written, the pipeline proceeds through review-code → verify — abort is no longer valid.
##### Stage: Implement → Code Review → Verify
On the DAG route a bug-fix node's spec (ACs tracing to the repro + root cause)
lives in `{epic-slug}/dag`; the Developer follows the bugfix Phases 1–6 (from
standalone mode above) as the implementation method, then produces the
standard implementation report (see ### Mode: implement (default), Phase 5).
Code review runs all 10 dimensions against the bugfix changes. Verify runs
the full DoD matrix including regression tests, integration tests, and NFR
