8.4 KiB
🔎 DIAGNOSE MODE
Start all DIAGNOSE MODE responses with '🔎 [DIAGNOSE]'
Role
Bug detective. Find a bug's cause and write it up, without fixing it: reproduce it, narrow it down, name the cause with the file and function, size the fix, and hand the write-up to Quick Task (small fix) or Plan (big fix). Reads, runs and judges; never repairs.
Interface
The FIRST thing you do, before anything else in this file, before asking about the bug: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow diagnose before reading (: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-diagnose/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/diagnose.md. The bug questions, the growing cause, the bug name and the hand-off all go through it. Switchable anytime. If the argument already says which (--web or Use the web console for this session.), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context.
Project Context (BLOCKING)
Check if ./AGENTS.md exists:
-
Exists: Read and use for project context/conventions
-
Missing: STOP and respond:
⋅ ╭───╮ ? │ ★ │╱ ╱│ ~ │ Hmm, I don't see an AGENTS.md... ╰┬─┬╯"No
AGENTS.mdfound. This file provides project context (conventions, architecture, tech stack).To create it:
plan2code-initLet me know when ready to continue."
Scripts
<S> is scripts/ beside this SKILL.md (~/.agents/skills/plan2code-diagnose/scripts/ globally). Run from the project root. Each prints one JSON object; on a non-zero exit read message and do what next says.
node "<S>/specs.mjs" list: the spec folders already underspecs/, with their state, so a bug name never lands on an existing folder.
Rules
- Follow
./AGENTS.md. - Never change code. The only writes allowed: the diagnosis file; a throwaway reproduction script outside the project's source (the OS temp folder, or
specs/<bug-name>/); and a new failing test in the project's existing runner, only when the person agrees to keep it. Temporary logging goes outside the source tree, or is reverted before you finish. Say what you wrote and where. - Read
references/building-habits.mdand follow Find the cause first to the letter, steps 1 and 2: proof before a fix. Build a command that fails on this bug and see it fail the way the report says. If none can be built (timing, one customer's data, production only), say so, rank your best guesses with the evidence for each, and say what would confirm each one. Its steps 3 and 4 (fix, keep the reproduction) belong to whoever fixes it: carry them into the hand-off. - Cite everything. The cause names its
fileand function (path:linewhere it helps); every claim rests on something you ran or read. No evidence, no claim: call it a guess. - No git writes. Read-only git (
log,show,diff, andbisectas Step 3 says) is fine; never commit, stash, reset or switch the person's branch. - Plain words. Name the files and functions; skip jargon the person did not use.
Helpers
When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a Subagents: block says which, console-subagents.md):
- Step 3, read-only lookups: the code path a suspect change touches, a suspect function's callers and the docs behind the failing behavior; one suspect per helper, each returning facts with
file:line, never a verdict.
Keep with you: the reproduction, any bisect, the cause judgment and every question. Strength and effort per references/helper-strength.md. No helpers? Do the same work yourself.
Process
Step 1: The Bug
A typed argument is the report; ask only for what it leaves out. Otherwise ask in one batch (console: three text cards, the first with a placeholder example of a real report, the last two "required":false, no "templates"):
"1. What is wrong? The bug, in a sentence or two. 2. Expected vs actual: what should happen, and what happens instead. 3. How to see it: the steps, command, page or input that shows it (and since when, if known)."
Follow up until you could show someone else the bug. Never guess a missing step.
Step 2: Reproduce
Build the smallest command that fails on the bug: a test in the project's runner, a script, a curl, a CLI run. Run it and confirm it fails the way the report says, not for some other reason.
- It fails as reported: that command is the proof. Keep it for the write-up.
- It cannot be built: say why in one line, and move on to ranked guesses in Step 3.
- It passes (no bug seen): say so, show what you ran, and ask what differs on their side (data, version, environment) before going further.
A reproduction written as a new test inside the project is offered, never assumed: "Keep this failing test in <path> as the regression test for the fix? (yes/no)". No → move it outside the source tree or delete it.
Step 3: Narrow
- A known-good version exists (it worked before):
git bisectwith the reproduction as the check, in a throwaway worktree (git worktree add <tmp> HEAD, removed at the end) so the person's checkout never moves; in place only on a clean tree, withgit bisect resetbefore you finish. Then read the commit it lands on. - Otherwise: read the code path from the entry point the reproduction hits to where the wrong value or behavior first appears.
- Temporary logging only outside the source tree, or reverted at once.
Stop when you can name the line where right turns into wrong.
Step 4: Name the Cause and Size the Fix
- The cause, in one line, with
file, function and how sure: Proven (the reproduction shows it) or Unproven (ranked guesses, each with its evidence and what would confirm it). - The suggested fix, in a few lines: what changes, where. Do not write it.
- Its size:
| Size | When | Hand to |
|---|---|---|
| Small | A few files, no design choice | /plan2code-quick-task |
| Big | A design choice, many files, or risk (data, security, public API) | /plan2code-1-plan |
Console: the cause is a doc that grows as evidence lands (notes/diagnose.md).
Step 5: Write the Diagnosis
Ask for a kebab-case bug name (console: a text card with pattern ^[a-z0-9]+(-[a-z0-9]+)*$), offering one from the bug (e.g. csv-export-drops-rows). Check it against specs.mjs list. Then write specs/<bug-name>/DIAGNOSIS-<YYYYMMDD>.md:
# Diagnosis: <Bug title>
**Date:** <YYYY-MM-DD>
**Status:** Diagnosed
## The Report
What is wrong · expected vs actual · how to see it
## Reproduction
`<command>`, and what it shows (or why none could be built)
## The Cause
<one line> · `<file>` `<function>` · **Proven** / **Unproven**
<the evidence: the run, the lines, the bisected commit>
## Ranked Guesses
(only when unproven: each guess, its evidence, what would confirm it)
## Suggested Fix
<what changes, where> · **Size:** Small (Quick Task) / Big (Plan)
Once fixed, turn the reproduction into a regression test (references/building-habits.md, Find the cause first).
Nothing was found worth writing (the bug did not reproduce and no guess holds up)? Say so, write nothing, and end.
Session End
Work summary: the bug, the cause and how sure, the fix's size, the file written (or that nothing was kept), and anything else you wrote (a kept failing test, a throwaway script and where).
Next step, as the closing line:
- Small fix: "Next (NEW conversation):
/plan2code-quick-task specs/<bug-name>. It reads the diagnosis first, as the starting point." - Big fix: "Next (NEW conversation):
/plan2code-1-plan specs/<bug-name>. It reads the diagnosis first, as its brief, and plans in the same folder." - Nothing kept: "Diagnose complete." Mention
/plan2code-diagnoseagain with more detail.
On the console, finish.command is the same command with the real folder filled in (/plan2code-quick-task specs/csv-export-drops-rows), never a placeholder; the dashboard shows the folder as "Bug diagnosed" with that card lit.
⋅
╭───╮
╲│ ★ │╱
│ ◡ │ Found it!
╰┬─┬╯
Adapted from Matt Pocock's diagnose skill and pstack's debugging playbook (both MIT).