Differs from the feature-building loop at two hard gates: no repro, no fix, and no red→green, no close. This skill coordinates existing tooling (impact-check, safe-change, verify-before-commit, failure-flywheel) — it does not redo them.
WHAT
Purpose and context
- Purpose: take an incident (bug/regression/incident) from symptom to a fix with red→green evidence and distilled knowledge, through 5 sequential gates with no skipping.
- Trigger (when to use):
- Bug, runtime error, regression, behavior wrong versus expectation, production incident.
- User says: "it's broken", "got a bug", "runs wrong", "it worked yesterday", "trace this error", "/orca-issue".
- Non-goals: DO NOT use when: feature request/new change →
propose/orca-workflow. Do not redo available tooling (impact-check, safe-change, verify-before-commit, failure-flywheel) — only coordinate. Do not clean up neighboring code within the incident loop.
Mental model
triệu chứng → repro ĐỎ (bằng chứng) → root cause ("nằm ở X vì Y") → fix surgical → repro XANH + verify → commit → distill kép (wiki incident + flywheel + problem-tree). Two hard gates: gate 2 (repro) and gate 4 (red→green).
Input and output contract
| Field | Required? | Meaning | |
|---|---|---|---|
| In | symptom | yes | what is wrong, where it is seen, since when; if unclear → ask user |
| In | log / screenshot / context | no | collected at triage; verbatim error message if any |
| Out | repro | yes | script/test + RED output saved as evidence |
| Out | fix + GREEN repro + verify pass | yes (except the cannot-reproduce branch) | commit via verify-before-commit |
| Out | incident wiki page | yes | llmwiki/wiki/sources/ — symptom, root cause, fix, ## Origin pointing to commit + repro |
| Out | failure-flywheel record + problem-tree node | yes (problem-tree if the project has one) | barrier for next time |
"Done" = repro green + verify pass + commit + distill (wiki + flywheel).
Rules and capabilities
- RULE-01 (MUST): No repro, no fix — every fix must trace back to a saved red evidence. A fix without repro is a guess-fix and gets sent back.
- RULE-02 (MUST): No green, no close — the agent's word is not evidence; only a repro turning green + verify pass may close it.
- RULE-03 (MUST): Surgical — only touch the area circled in step 3; if you see neighboring code that "wants to be cleaned up", note it, do not clean it during the incident.
- RULE-04 (MUST): Distill is mandatory, not a courtesy — the loop is not finished until the wiki + flywheel are written; this is how today's bug becomes tomorrow's guardrail.
- RULE-05 (SHOULD): A severe incident needing many people/agents → escalate to
orca-workflowfor dispatch, but gates 2 and 4 remain unchanged. - RULE-06 (MUST): Read the error message VERBATIM before guessing (superpowers systematic-debugging) — the error message + stack trace are the cheapest evidence; triaging without quoting the error verbatim means you are guessing.
- RULE-07 (MUST): One hypothesis at a time — each round change only ONE thing then re-run the repro; if you change many things at once (shotgun-fix), even if it goes green you won't know why it went green.
- RULE-08 (MUST): 3 consecutive failed fixes → stop, suspect the ARCHITECTURAL level — do not try a 4th fix of the same size; return to step 3 with a bigger hypothesis (wrong layer, wrong component, wrong underlying assumption).
- Capabilities: read logs/code, locate (code-graph, impact-map, VCS history), run local tests, write code via the safe-change flow, write wiki + failure ledger. No deploy.
Failure boundaries
- Symptoms not yet clear → clarify (ask the user), do not guess.
- Cannot reproduce (flaky/heisenbug) → blocked for the fix: record the conditions tried, drop down to monitoring mode (add logs/probes).
- Repro still red after the fix → not done, return to step 3.
- 3 consecutive failed fixes → stop, suspect the architectural level, do not try a 4th fix of the same size.
- A severe incident needing many people/agents → escalate
orca-workflow(gates 2 and 4 remain unchanged).
HOW
Main workflow
| Step | Type | Inputs | Action | Outputs/exit | Failure/next |
|---|---|---|---|---|---|
| W01 | judgment | symptoms, logs | Triage: write down the symptoms in 1–2 sentences, quote the error verbatim, classify the severity | symptoms + severity | not clear → ask the user |
| W02 | deterministic | symptoms | Repro-first GATE: write a script/test, run it to RED, save it | red repro saved | cannot reproduce → B01 |
| W03 | judgment | repro, code-graph, impact-check, git | Localize | "root cause lies in X because Y" | — |
| W04 | effect | root cause | Fix via safe-change, re-run repro + project tests + verify-before-commit |
repro GREEN, commit | still red → W03; 3 failures → B02 |
| W05 | effect | commit, repro | Dual distill: wiki incident + failure-flywheel + problem-tree | wiki page, record, node | not distilled = not done |
Details for each step (source of truth for W01–W05) — 5 sequential checkpoints, no skipping:
- Triage — rewrite the symptom in 1–2 sentences (what's wrong, where it's seen, since when); collect logs/screenshots/context; classify severity (blocking / annoying / cosmetic). If the symptom is unclear → ask the user, don't guess.
- Repro-first GATE (hard checkpoint #1) — write a script/test that reproduces the bug, get a RED result (fail) and save it as evidence (test file or script + output). No red repro means STOP here — don't discuss the cause, don't fix. If the bug can't be reproduced (flaky/heisenbug) → note the conditions tried, downgrade to monitoring mode (add logs/probes), don't fix blindly.
- Narrow down — use localization tools instead of blind grep: code-graph (
get_callers/get_symbol_context),impact-checkto map who depends on the suspect area,git bisect/git logwhen suspecting a regression over time. Result: 1 sentence "root cause is at X because Y". - Fix red→green (hard checkpoint #2) — fix via
safe-change(if shared code, map callers first), surgically within the narrowed area. Re-run the repro from step 2: it must go RED → GREEN; also run the project's existing tests/verification; finalize withverify-before-commit. Repro still red = not done, go back to step 3 — no "it's probably fine now". - Dual distill — after committing: (a) wiki incident page into
llmwiki/wiki/sources/(symptom, root cause, fix, with## Originpointing to commit + repro); (b) record intofailure-flywheelso repeated bugs meeting the threshold auto-suggest rules/skills; (c) if the project has a problem-tree (llmwiki/html/problem-tree.htmlorfdk-problem-tree.html) → add/flip the corresponding node.
Branches
| ID | Kind | Guard | Behavior | Skip / failure | Rejoin |
|---|---|---|---|---|---|
| B01 | recovery | bug cannot be reproduced (flaky/heisenbug) | note the conditions tried, downgrade to monitoring mode (add logs/probes), don't fix blindly | no red repro → do not proceed to W03/W04 | W02 when the bug reappears with new facts |
| B02 | recovery | 3 consecutive failed fixes | stop, suspect ARCHITECTURE level; go back to scoping with a bigger hypothesis (wrong layer, wrong component, wrong underlying assumption) | do not try a 4th fix of the same size | W03 |
| B03 | conditional_required | severe incident requiring many people/agents | escalate to orca-workflow for dispatch |
checkpoints 2 and 4 still hold | W04 |
| B04 | capability_optional | project has a problem-tree (llmwiki/html/problem-tree.html or fdk-problem-tree.html) |
add/flip the corresponding node at W05 | none → skip | W05 |
Validation and stopping
Checkpoints 2 and 4 are verified by actually running: repro must come out RED before the fix and GREEN after the fix, plus existing test/verify. The agent's word is not evidence. Stop when distillation is done; ceiling: 3 consecutive failed fixes → B02.
Examples
- Positive: "approve hanging since yesterday" → triage extracts the timeout error verbatim → repro test RED →
git bisectonly commits the lock change → fix via safe-change → repro GREEN +verify-before-commit→ incident page inllmwiki/wiki/sources/+ record failure-flywheel. - Boundary/failure: error occurs only 1/50 times, cannot repro → do not fix, record the conditions tried, add log/probe (B01).
- Boundary: user asks to "add an export button" → not an incident, forward to
propose/orca-workflow.
Origin
- Absorb 2026-07-17 (adapt_mode: dissolve, T-260717-02): the last 3 checkpoints (read the error verbatim · one hypothesis at a time · 3-fail-suspect-architecture) distilled from
obra/superpowers(systematic-debugging— Iron Law + Four Phases). Checkpoints that duplicate an existing loop (repro-first, root-cause, red→green) are NOT absorbed again. Clone already in scratchpad/superpowers.