Diagnose Failure - one entry for any failure evidence
One reported failure, four steps, the user holds the gate between them. This skill owns the
chain, the stops, the evidence accounting, and the fork at the end; the catalogues and the
seats do the specialist work. It is READ-ONLY from start to finish - no step here writes code,
so no approval stamp and no commit gate come into play. The measurements behind these rules live in
references/evidence.md - an audit appendix, not a run-time load.
Modes. Mode flags right after the command - --mode-auto-run-on, --mode-auto-run-off, --mode-output-scorer-on, --mode-output-scorer-off - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), -on holds for this run only: each stop takes its (Recommended) option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; --mode-output-scorer-on grades this run's output like a typed stack. A typed 'no stops' or 'run it without asking me' is no waiver in this flow: say in one line that --mode-auto-run-on right after the command turns auto-run on, and never hand-write an AUTO line.
When to use
- Evidence can be a pasted error-monitor event, one log file, several log sources at once, a red CI run, a stack trace, a screenshot, or nothing but a customer saying checkout is slow.
- Four gated steps: triage the evidence to a tier, gather (inline or evidence-gatherer seats), prove the root cause, then a user fork - write a report, plan the fix as contracted tasks, or add log points and re-run.
- Read-only throughout: it never writes the fix.
- Not the fix build (task-solve takes the tasks from here), not a signature lookup you already have the answer for.
Evidence tiers - name the tier, carry it as the confidence label
The tier is the first thing this skill establishes and the last thing its verdict is qualified
by - tier 1 a stack trace or failing test, 2 a log window / red CI run / monitoring event, 3
written repro steps, 4 a screenshot or a prose report. No source is a lower tier, never a
blocker. A tier-4 report is the DEFAULT case, not an edge case, and a conclusion drawn there is
labelled as such, never presented with tier-1 confidence.
references/evidence-tiers.md carries the table (what each tier buys, and the code-first path a
tier-4 report takes) plus what this skill can and cannot reach - files, logs, the repo history,
the app itself, gh and the error-monitoring tool when the start line's tool order ranks one, and never a LINK.
Read it at step 1, before the tier is named.
State - two layers, split by durability
- The findings file (
<docs-path>/work/diagnoses/<slug>.md) is the durable truth: the failure as
an observable, the evidence tier, every digest's key lines, the hypotheses with their verdicts,
the proven cause, and the stamps this run adds (Tier, Gathered, Cause, Outcome). On any
conflict with memory or the chat, the file wins.
- The handoff note (
<slug>/diagnosis/cursor on the handoff bus, node .claude/hooks/handoff.js put <slug>/diagnosis/cursor <<'EOF') is the working cursor: current
step, chosen mode, resume pointer, the error signature and its proven fix once found, never a dump of the log.
On invocation, resume before starting: node .claude/hooks/handoff.js list <slug>/diagnosis/cursor - the newest copy is the cursor - and read the findings file's stamps. A run
mid-flight resumes at its cursor - never re-run a step already stamped. A run between steps 2
and 3 looks like:
findings <docs-path>/work/diagnoses/orders-sync-disposed.md:
Observable: nightly order sync stops after the first batch; expected all batches
Tier: 1 (ObjectDisposedException, frame OrderSyncJob.ExecuteAsync) | Gathered: 2 sources agree
Cause: <pending>
note 'orders-sync-disposed/diagnosis': step 3 ROOT CAUSE - mode inline, 1 hypothesis open
Mode - ask at start
When dispatch is available, ask ONE question before the evidence pass - unless a calling flow
already picked the run's mode, which is inherited, never re-asked:
Gather the evidence <inline | through the seats>: <what settles it - one grep, or a big or many-source pull>.
- 'Gather inline in this session (Recommended)' - a single command or a bounded grep settles it
- 'Gather through evidence-gatherer seats' - big or many sources; the raw volume never lands here
The mark moves to the seats when the evidence is BIG or MANY (a multi-megabyte log, a CI dump,
three sources to correlate): the whole point of that seat is that the raw volume never lands in
this context. An interrupted or declined ask is answered by RE-ASKING, once any question in it is
answered, in the user's next turn, never by inference.
The stop contract
A stop IS one AskUserQuestion call: report one line of result and the artifact path, then put
the next move through the AskUserQuestion tool - EVERY stop, the plain step-done ones included.
A reply that ASKS is no pick: answer it and end the turn - the stop stays open. The options are
concrete - the next step named, the route-back where a step surfaced gaps, the fresh-session
resume on a long run - the recommendation marked per that stop's own rule, free text always
available via the built-in Other. Where the harness has no such tool, list the same options in
plain text and END THE TURN. The selected answer is the go; silence is not, and a stop that
only narrates is not a stop. Once the run has crossed the install's fresh-session trigger for its
context window (400,000 tokens on a window of 1M or more, 280,000 on one of 300k up to 1M, 180,000 on any other), the fresh-session resume IS one of the next ask's options - a CONSTRUCTION check before
emitting each stop, not a memory: resume needs only the findings file plus the note.
Every ask marks exactly one option (Recommended), listed first - the move this stop's rule
recommends, the reason in its description; an ask with no mark is malformed, rebuild it before
sending - an unmarked ask gets its first option taken whatever it says. A step-done stop:
<Step> done - <findings path>. Continue to <next step>: <the one reason it is next>.
- '<Next step> (Recommended)' - <what it does, in one line>
- 'Gather more evidence' - <the source still missing>
- 'Resume in a fresh session' - required past the fresh-session trigger above
The steps
Each step that names a catalogue INVOKES it via the Skill tool - and re-invokes it in a new
cycle in the same chat, even when an earlier cycle already loaded it.
TRIAGE - read the evidence in whatever form it arrived (Read opens a screenshot as
readily as a log), restate the failure as an OBSERVABLE - what happened, where, what should
have happened instead - and name the tier, per references/evidence-tiers.md. Read the project's
docs for the area too, scoped, never whole: <docs-path>/awareness/ARCHITECTURE-AWARENESS.md for the area,
PERSONAL-CODE-PREFERENCES.md, ARCHITECTURE-PREFERENCES.md and PROJECT-CODE-PREFERENCES.md under
<docs-path>/preferences/, and both assessments, <docs-path>/quality/CODE-ASSESSMENT.md and
<docs-path>/quality/ARCHITECTURE-ASSESSMENT.md - an assessment entry is a lead, never proof. Then load the signature
catalogue that matches the failure's origin, matched from YOUR skill list by what each skill
says it covers, never by a remembered name: the one covering runtime crash signatures
(null-reference, DI resolution, async deadlock, race, disposed lifecycle, config drift) for a
failure on your own machine or a production event's trace, the one covering red-pipeline signatures (compile/restore,
green-locally-red-on-the-runner, quality gate, signing, workflow drift, infra flake) for a
red CI run. Before writing 'none installed': re-read the skill list text once more end to end
for a description match - a catalogue present in that list and skipped is the measured failure
this line exists to catch. Only when that recheck comes back empty does this project have
no such catalogue - say so and proceed on the method alone. A red pipeline is the one route that leaves this skill: CI
needs the gh log pull and the CI-versus-local environment delta, which is
issue-diagnoser-ci's specialty - offer that dispatch as the recommended option at this
stop rather than re-deriving it here, the seat dispatched exactly as the roster spells it
(alfred-code:issue-diagnoser-ci where the core plugin carries it). Write the findings file with the observable and
Tier: <n>. Stop.
GATHER - per the mode: dispatch one evidence-gatherer per source (reproduce this path,
pull and grep that log window, capture that screen) exactly as the roster spells it (alfred-code:<seat> where the core plugin carries it), several in parallel, up to ALFRED_CODE_MAXIMUM_RUN_AGENTS at once (default 5), when several
hypotheses need confirming, and reason over the compact digests they return; or run the
bounded commands inline. Correlate multiple sources on a shared key - a correlation/trace id,
a timestamp window, a release version - and say which sources agreed and which did not. At
tier 4, with no source to pull, this step is code-first instead: locate the named behaviour
with the navigation tools per .claude/rules/alfred-navigation.md, read the paths that could produce the
symptom, and attempt a repro. Never slurp a large log into this context - grep to the signal
and quote a bounded window. If it cannot be reproduced, say so with what you tried, and work
from the evidence and the code. Append the digests' key lines to the findings file, stamp
Gathered:, then stop - put 'continue to root cause?' through the AskUserQuestion tool per
'The stop contract' above (the stop hook already enforces the call).
ROOT CAUSE - the FIRST action of this step is the habits-root-cause Skill call,
before the first hypothesis (skip it only when that skill is already in context): its
hypothesis-and-test loop runs the whole step - hypotheses first, each one confirmed or killed
against the code. Form the fewest hypotheses the evidence supports, then
confirm or kill each against the located code and the reproduction - root cause before
symptom, never a plausible guess. Match the evidence to the catalogue's signature and isolate
where the signature points, which is almost never the line that threw. Hard cap: 2
investigation passes. If the cause stays ambiguous after 2, stop guessing and record the
surviving hypotheses RANKED with what would decide between each. Where a scorer: on line
naming the root-cause verdict or a scorer: stacked line is in context, the FIRST action before
releasing the verdict - stamping it, or putting the fork below - is the mode-output-scorer
Skill call with output root-cause. Stamp Cause: with the file + symbol and the evidence that
proves it, or Cause: unproven - <n> hypotheses ranked, once the scorer released it where one
runs (Cause: <pending> until then).
Report a severity and an explicit P0-P3 priority when the ask was to level it rather than fix
it. This step ends at the fork below - it never continues into planning on its own.
THE FORK - the step-3 stop asks ONE question whose options are the three real outcomes,
each named concretely. The recommendation is set by whether step 3 actually proved a cause -
proven recommends 4b, unproven moves the mark to 4c - with the reason in the option's description:
The cause is <proven at file:symbol | unproven - N hypotheses ranked>. <Plan the fix | Instrument>: <why>.
- 'Plan the fix as tasks (Recommended)' - the cards go into the findings file for /task-solve
- 'Write a report on the issue' - a standalone document, no task cards
- 'Add log points and re-run' - one card of log points, so the next occurrence arrives a tier higher
- 4a. REPORT ('Write a report on the issue') - finish the findings file as a standalone
document: the observable, the evidence tier, the proven cause with its located symbol, the
blast radius and who it affects, severity + priority, and what a fix would have to change.
Where a
scorer: on line naming the root-cause verdict or a scorer: stacked line is in
context, the FIRST action before releasing the report is the mode-output-scorer
Skill call with output root-cause. No task cards. This is the outcome when the fix is someone else's, or not now.
- 4b. PLAN TASKS ('Plan the fix as tasks') - first load
habits-execution-strategy (the Skill
tool) over the minimal change: how the fix runs, not only what it changes. Its Execution: line sets the cards' split -
units it found parallel-safe become separate cards, units that share a file or need another's
output stay one card or are ordered - and rides the close ask's question as its Execution: line, never written into
the findings file (task-solve decides the build mode again on the gated plan).
Then decompose the minimal change per cause into tasks on that split, each with a contract: the files it owns, what it must not touch, its
acceptance criterion, and the log_points the fix must leave behind at the seam that
failed. Name the target stack per task. The cards go into the findings file under a
## Tasks heading - the file is the handoff, not the chat. The build is the user's next
step, never yours: the close-out names /task-solve with the findings path as its
input (it is slash-only - a model Skill call is refused - and its DESIGN step turns these
cards into the gated plan). If the real fix is a redesign rather than a targeted change,
say so and make that stack's solution-designer the option's route instead of planning it
here; if it would change a shared contract, mark it BLOCKED_CONTRACT_CHANGE rather than
planning a silent edit.
- 4c. INSTRUMENT ('Add log points and re-run') - the outcome that turns 'no evidence' into
work instead of a guess: ONE task card carrying only the log points to add at the suspect
seam - the exact symbols, the levels, and the identifiers each line must carry - so the next
occurrence arrives one tier higher. Name the hypothesis each line is there to decide.
Stamp
Outcome: with the branch taken. A proven cause is a CLOSING point, not a midpoint:
the findings file is durable and self-contained by construction, so whatever the fork picked,
the next phase - writing the report, building the tasks, reading the new logs - can start in a
FRESH session resumed from that path, and this stop offers it as an option in its own words
('resume from <findings path> in a fresh session'). Mark the fresh option only when a hook's fresh-session text in this session says a fresh session pays back, and then it goes first, the in-session option after it unmarked; on Claude Code the stop-contract hook drops it where one does not, and when that leaves one option it refuses the ask - then take the option it names.
Stop - after 4a or 4c, one ask:
<The report is written | The log points are in> - <findings path>. Next: <read the report | re-run until the next occurrence lands>.
- 'Stop here (Recommended)' - the findings file holds the cause and the next step
- 'Resume from <findings path> in a fresh session' - the next phase starts from the file alone
Stop - after 4b the close names the build as the user's own command:
The fix is planned in <findings path>. <the strategy's verdict line, which opens `Execution:`>. Build it from that file with your own /task-solve command.
- 'Build it here: /task-solve <findings path> (Recommended)' - type the command in this chat; the file is the whole input
- 'Build it in a fresh session: /task-solve <findings path>' - `/clear` first, then the command; the file is the whole input
- 'Stop here' - the findings file keeps the cause and the tasks
This close-out stop carries anything
pending: an unwritten task card, a source the user still has to paste, a sibling repo that
needs the same fix (that handoff is a FILE - a task card under <docs-path>/work/cross-project-tasks/,
printed as the docs-root rule's hand-off block - never chat-only prose). Purge this run's cursor (node .claude/hooks/handoff.js purge <slug>); when the cause was proven, first write the signature and its
fix into the findings file's Cause stamp - the reusable half, which a later diagnosis greps <docs-path>/work/diagnoses/ for.
Do not
- Never pass a stop without the user's explicit word, and never take the fork yourself - step 4
runs the branch the USER picked, and 'obviously they want the fix' is not an answer. Under
auto-run the hook's answer to a marked ask is that word; the build stays the user's own command.
- Never end a stop's turn without its AskUserQuestion (or the plain-text fallback's option list).
- Never write code, edit a file under test, or run a destructive repro - one that applies a
migration against a real database, seeds or deletes tracked files, or commits. If the only
repro is destructive, say so and stop.
- Never present a tier-3 or tier-4 conclusion with tier-1 confidence, and never report a cause
you did not prove as the answer - an honest 'unproven, here is what would decide it' with the
4c instrumentation card beats a plausible guess that sends the fix at the wrong symbol.
- Never state a source was checked that you could not reach - an unfetchable link, an absent
error-monitoring tool, and a log the project does not retain are each named, not silently skipped.
- Never keep run state only in chat: a stamp that is not in the findings file does not exist.
1---2name: issue-diagnoser3description: "Use when a failure needs investigating - an error event, logs, red CI, a stack trace, 'what is causing this'. Not for the fix, which /task-solve owns."4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/envoydev/issue-diagnoser7---89# Diagnose Failure - one entry for any failure evidence1011One reported failure, four steps, the user holds the gate between them. This skill owns the12chain, the stops, the evidence accounting, and the fork at the end; the catalogues and the13seats do the specialist work. It is READ-ONLY from start to finish - no step here writes code,14so no approval stamp and no commit gate come into play. The measurements behind these rules live in15`references/evidence.md` - an audit appendix, not a run-time load.1617**Modes.** Mode flags right after the command - `--mode-auto-run-on`, `--mode-auto-run-off`, `--mode-output-scorer-on`, `--mode-output-scorer-off` - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), `-on` holds for this run only: each stop takes its `(Recommended)` option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; `--mode-output-scorer-on` grades this run's output like a typed stack. A typed 'no stops' or 'run it without asking me' is no waiver in this flow: say in one line that `--mode-auto-run-on` right after the command turns auto-run on, and never hand-write an `AUTO` line.1819## When to use2021- Evidence can be a pasted error-monitor event, one log file, several log sources at once, a red CI run, a stack trace, a screenshot, or nothing but a customer saying checkout is slow.22- Four gated steps: triage the evidence to a tier, gather (inline or evidence-gatherer seats), prove the root cause, then a user fork - write a report, plan the fix as contracted tasks, or add log points and re-run.23- Read-only throughout: it never writes the fix.24- Not the fix build (task-solve takes the tasks from here), not a signature lookup you already have the answer for.2526## Evidence tiers - name the tier, carry it as the confidence label2728The tier is the first thing this skill establishes and the last thing its verdict is qualified29by - tier 1 a stack trace or failing test, 2 a log window / red CI run / monitoring event, 330written repro steps, 4 a screenshot or a prose report. No source is a lower tier, never a31blocker. A tier-4 report is the DEFAULT case, not an edge case, and a conclusion drawn there is32labelled as such, never presented with tier-1 confidence.3334`references/evidence-tiers.md` carries the table (what each tier buys, and the code-first path a35tier-4 report takes) plus what this skill can and cannot reach - files, logs, the repo history,36the app itself, `gh` and the error-monitoring tool when the start line's tool order ranks one, and never a LINK.37Read it at step 1, before the tier is named.3839## State - two layers, split by durability4041- **The findings file** (`<docs-path>/work/diagnoses/<slug>.md`) is the durable truth: the failure as42 an observable, the evidence tier, every digest's key lines, the hypotheses with their verdicts,43 the proven cause, and the stamps this run adds (`Tier`, `Gathered`, `Cause`, `Outcome`). On any44 conflict with memory or the chat, the file wins.45- **The handoff note** (`<slug>/diagnosis/cursor` on the handoff bus, `node .claude/hooks/handoff.js put <slug>/diagnosis/cursor <<'EOF'`) is the working cursor: current46 step, chosen mode, resume pointer, the error signature and its proven fix once found, never a dump of the log.4748**On invocation, resume before starting:** `node .claude/hooks/handoff.js list <slug>/diagnosis/cursor` - the newest copy is the cursor - and read the findings file's stamps. A run49mid-flight resumes at its cursor - never re-run a step already stamped. A run between steps 250and 3 looks like:5152```53findings <docs-path>/work/diagnoses/orders-sync-disposed.md:54 Observable: nightly order sync stops after the first batch; expected all batches55 Tier: 1 (ObjectDisposedException, frame OrderSyncJob.ExecuteAsync) | Gathered: 2 sources agree56 Cause: <pending>57note 'orders-sync-disposed/diagnosis': step 3 ROOT CAUSE - mode inline, 1 hypothesis open58```5960## Mode - ask at start6162When dispatch is available, ask ONE question before the evidence pass - unless a calling flow63already picked the run's mode, which is inherited, never re-asked:6465```ask66Gather the evidence <inline | through the seats>: <what settles it - one grep, or a big or many-source pull>.67- 'Gather inline in this session (Recommended)' - a single command or a bounded grep settles it68- 'Gather through evidence-gatherer seats' - big or many sources; the raw volume never lands here69```7071The mark moves to the seats when the evidence is BIG or MANY (a multi-megabyte log, a CI dump,72three sources to correlate): the whole point of that seat is that the raw volume never lands in73this context. An interrupted or declined ask is answered by RE-ASKING, once any question in it is74answered, in the user's next turn, never by inference.7576## The stop contract7778A stop IS one AskUserQuestion call: report one line of result and the artifact path, then put79the next move through the AskUserQuestion tool - EVERY stop, the plain step-done ones included.80A reply that ASKS is no pick: answer it and end the turn - the stop stays open. The options are81concrete - the next step named, the route-back where a step surfaced gaps, the fresh-session82resume on a long run - the recommendation marked per that stop's own rule, free text always83available via the built-in Other. Where the harness has no such tool, list the same options in84plain text and END THE TURN. The selected answer is the go; silence is not, and a stop that85only narrates is not a stop. Once the run has crossed the install's fresh-session trigger for its86context window (400,000 tokens on a window of 1M or more, 280,000 on one of 300k up to 1M, 180,000 on any other), the fresh-session resume IS one of the next ask's options - a CONSTRUCTION check before87emitting each stop, not a memory: resume needs only the findings file plus the note.8889**Every ask marks exactly one option `(Recommended)`, listed first** - the move this stop's rule90recommends, the reason in its description; an ask with no mark is malformed, rebuild it before91sending - an unmarked ask gets its first option taken whatever it says. A step-done stop:9293```ask94<Step> done - <findings path>. Continue to <next step>: <the one reason it is next>.95- '<Next step> (Recommended)' - <what it does, in one line>96- 'Gather more evidence' - <the source still missing>97- 'Resume in a fresh session' - required past the fresh-session trigger above98```99100## The steps101102Each step that names a catalogue INVOKES it via the Skill tool - and re-invokes it in a new103cycle in the same chat, even when an earlier cycle already loaded it.1041051. **TRIAGE** - read the evidence in whatever form it arrived (`Read` opens a screenshot as106 readily as a log), restate the failure as an OBSERVABLE - what happened, where, what should107 have happened instead - and name the tier, per `references/evidence-tiers.md`. Read the project's108 docs for the area too, scoped, never whole: `<docs-path>/awareness/ARCHITECTURE-AWARENESS.md` for the area,109 `PERSONAL-CODE-PREFERENCES.md`, `ARCHITECTURE-PREFERENCES.md` and `PROJECT-CODE-PREFERENCES.md` under110 `<docs-path>/preferences/`, and both assessments, `<docs-path>/quality/CODE-ASSESSMENT.md` and111 `<docs-path>/quality/ARCHITECTURE-ASSESSMENT.md` - an assessment entry is a lead, never proof. Then load the signature112 catalogue that matches the failure's origin, matched from YOUR skill list by what each skill113 says it covers, never by a remembered name: the one covering runtime crash signatures114 (null-reference, DI resolution, async deadlock, race, disposed lifecycle, config drift) for a115 failure on your own machine or a production event's trace, the one covering red-pipeline signatures (compile/restore,116 green-locally-red-on-the-runner, quality gate, signing, workflow drift, infra flake) for a117 red CI run. **Before writing 'none installed': re-read the skill list text once more end to end118 for a description match** - a catalogue present in that list and skipped is the measured failure119 this line exists to catch. Only when that recheck comes back empty does this project have120 no such catalogue - say so and proceed on the method alone. **A red pipeline is the one route that leaves this skill:** CI121 needs the `gh` log pull and the CI-versus-local environment delta, which is122 issue-diagnoser-ci's specialty - offer that dispatch as the recommended option at this123 stop rather than re-deriving it here, the seat dispatched exactly as the roster spells it124 (`alfred-code:issue-diagnoser-ci` where the core plugin carries it). Write the findings file with the observable and125 `Tier: <n>`. *Stop.*1262. **GATHER** - per the mode: dispatch one evidence-gatherer per source (reproduce this path,127 pull and grep that log window, capture that screen) exactly as the roster spells it (`alfred-code:<seat>` where the core plugin carries it), several in parallel, up to `ALFRED_CODE_MAXIMUM_RUN_AGENTS` at once (default 5), when several128 hypotheses need confirming, and reason over the compact digests they return; or run the129 bounded commands inline. Correlate multiple sources on a shared key - a correlation/trace id,130 a timestamp window, a release version - and say which sources agreed and which did not. At131 tier 4, with no source to pull, this step is code-first instead: locate the named behaviour132 with the navigation tools per `.claude/rules/alfred-navigation.md`, read the paths that could produce the133 symptom, and attempt a repro. Never slurp a large log into this context - grep to the signal134 and quote a bounded window. If it cannot be reproduced, say so with what you tried, and work135 from the evidence and the code. Append the digests' key lines to the findings file, stamp136 `Gathered:`, then stop - put 'continue to root cause?' through the AskUserQuestion tool per137 'The stop contract' above (the stop hook already enforces the call).1383. **ROOT CAUSE** - the FIRST action of this step is the `habits-root-cause` Skill call,139 before the first hypothesis (skip it only when that skill is already in context): its140 hypothesis-and-test loop runs the whole step - hypotheses first, each one confirmed or killed141 against the code. Form the fewest hypotheses the evidence supports, then142 confirm or kill each against the located code and the reproduction - root cause before143 symptom, never a plausible guess. Match the evidence to the catalogue's signature and isolate144 where the signature points, which is almost never the line that threw. **Hard cap: 2145 investigation passes.** If the cause stays ambiguous after 2, stop guessing and record the146 surviving hypotheses RANKED with what would decide between each. Where a `scorer: on` line147 naming the root-cause verdict or a `scorer: stacked` line is in context, the FIRST action before148 releasing the verdict - stamping it, or putting the fork below - is the `mode-output-scorer`149 Skill call with output `root-cause`. Stamp `Cause:` with the file + symbol and the evidence that150 proves it, or `Cause: unproven - <n> hypotheses ranked`, once the scorer released it where one151 runs (`Cause: <pending>` until then).152 Report a severity and an explicit P0-P3 priority when the ask was to level it rather than fix153 it. **This step ends at the fork below - it never continues into planning on its own.**1544. **THE FORK** - the step-3 stop asks ONE question whose options are the three real outcomes,155 each named concretely. The recommendation is set by whether step 3 actually proved a cause -156 proven recommends 4b, unproven moves the mark to 4c - with the reason in the option's description:157158 ```ask159 The cause is <proven at file:symbol | unproven - N hypotheses ranked>. <Plan the fix | Instrument>: <why>.160 - 'Plan the fix as tasks (Recommended)' - the cards go into the findings file for /task-solve161 - 'Write a report on the issue' - a standalone document, no task cards162 - 'Add log points and re-run' - one card of log points, so the next occurrence arrives a tier higher163 ```164165 - **4a. REPORT** ('Write a report on the issue') - finish the findings file as a standalone166 document: the observable, the evidence tier, the proven cause with its located symbol, the167 blast radius and who it affects, severity + priority, and what a fix would have to change.168 Where a `scorer: on` line naming the root-cause verdict or a `scorer: stacked` line is in169 context, the FIRST action before releasing the report is the `mode-output-scorer`170 Skill call with output `root-cause`. No task cards. This is the outcome when the fix is someone else's, or not now.171 - **4b. PLAN TASKS** ('Plan the fix as tasks') - first load `habits-execution-strategy` (the Skill172 tool) over the minimal change: how the fix runs, not only what it changes. Its `Execution:` line sets the cards' split -173 units it found parallel-safe become separate cards, units that share a file or need another's174 output stay one card or are ordered - and rides the close ask's question as its `Execution:` line, never written into175 the findings file (task-solve decides the build mode again on the gated plan).176 Then decompose the minimal change per cause into tasks on that split, each with a contract: the files it owns, what it must not touch, its177 acceptance criterion, and the `log_points` the fix must leave behind at the seam that178 failed. Name the target stack per task. The cards go into the findings file under a179 `## Tasks` heading - the file is the handoff, not the chat. The build is the user's next180 step, never yours: the close-out names `/task-solve` with the findings path as its181 input (it is slash-only - a model Skill call is refused - and its DESIGN step turns these182 cards into the gated plan). If the real fix is a redesign rather than a targeted change,183 say so and make that stack's solution-designer the option's route instead of planning it184 here; if it would change a shared contract, mark it BLOCKED_CONTRACT_CHANGE rather than185 planning a silent edit.186 - **4c. INSTRUMENT** ('Add log points and re-run') - the outcome that turns 'no evidence' into187 work instead of a guess: ONE task card carrying only the log points to add at the suspect188 seam - the exact symbols, the levels, and the identifiers each line must carry - so the next189 occurrence arrives one tier higher. Name the hypothesis each line is there to decide.190 Stamp `Outcome:` with the branch taken. **A proven cause is a CLOSING point, not a midpoint:**191 the findings file is durable and self-contained by construction, so whatever the fork picked,192 the next phase - writing the report, building the tasks, reading the new logs - can start in a193 FRESH session resumed from that path, and this stop offers it as an option in its own words194 ('resume from `<findings path>` in a fresh session'). Mark the fresh option only when a hook's fresh-session text in this session says a fresh session pays back, and then it goes first, the in-session option after it unmarked; on Claude Code the stop-contract hook drops it where one does not, and when that leaves one option it refuses the ask - then take the option it names.195 *Stop* - after 4a or 4c, one ask:196197 ```ask198 <The report is written | The log points are in> - <findings path>. Next: <read the report | re-run until the next occurrence lands>.199 - 'Stop here (Recommended)' - the findings file holds the cause and the next step200 - 'Resume from <findings path> in a fresh session' - the next phase starts from the file alone201 ```202203 *Stop* - after 4b the close names the build as the user's own command:204205 ```ask206 The fix is planned in <findings path>. <the strategy's verdict line, which opens `Execution:`>. Build it from that file with your own /task-solve command.207 - 'Build it here: /task-solve <findings path> (Recommended)' - type the command in this chat; the file is the whole input208 - 'Build it in a fresh session: /task-solve <findings path>' - `/clear` first, then the command; the file is the whole input209 - 'Stop here' - the findings file keeps the cause and the tasks210 ```211212 This close-out stop carries anything213 pending: an unwritten task card, a source the user still has to paste, a sibling repo that214 needs the same fix (that handoff is a FILE - a task card under `<docs-path>/work/cross-project-tasks/`,215 printed as the docs-root rule's hand-off block - never chat-only prose). Purge this run's cursor (`node .claude/hooks/handoff.js purge <slug>`); when the cause was proven, first write the signature and its216 fix into the findings file's `Cause` stamp - the reusable half, which a later diagnosis greps `<docs-path>/work/diagnoses/` for.217218## Do not219220- Never pass a stop without the user's explicit word, and never take the fork yourself - step 4221 runs the branch the USER picked, and 'obviously they want the fix' is not an answer. Under222 auto-run the hook's answer to a marked ask is that word; the build stays the user's own command.223- Never end a stop's turn without its AskUserQuestion (or the plain-text fallback's option list).224- Never write code, edit a file under test, or run a destructive repro - one that applies a225 migration against a real database, seeds or deletes tracked files, or commits. If the only226 repro is destructive, say so and stop.227- Never present a tier-3 or tier-4 conclusion with tier-1 confidence, and never report a cause228 you did not prove as the answer - an honest 'unproven, here is what would decide it' with the229 4c instrumentation card beats a plausible guess that sends the fix at the wrong symbol.230- Never state a source was checked that you could not reach - an unfetchable link, an absent231 error-monitoring tool, and a log the project does not retain are each named, not silently skipped.232- Never keep run state only in chat: a stamp that is not in the findings file does not exist.