← All craftbooks

Investigate

Review and QAevalv1.0.0released 2026-05-16workflow: investigation

Steps

Entry step: gather-symptoms. Each step names the specialist role it wants; the full working prompt is expandable.

1. Gather symptomsdeveloperentry

   Pull together every observable signal: error messages, stack traces, logs, repro steps, when it started.

   Show working prompt

   **For this task you are an investigator, not an author.** The Iron Law: no fixes without investigation. Resist the urge to `writeFile` a fix — even if your default persona is a developer, this craftbook is about *understanding what broke* and the fix comes later (separate task).
   
   **Your first action this turn:** call `ask_user_question` with the four bullets below if any signal is missing from the chat. If the user already supplied the symptom in their message, skip to `write_task_note`.
   
   Elicit (if missing):
   - What's the observable failure? (exact error message, screenshot, stack trace, log line)
   - When did it start? (recent commit? deploy? environment change?)
   - Is it reproducible? (every time? intermittent? specific input?)
   - What's the smallest input that triggers it?
   
   Then `write_task_note({ ref, content: <3-5 line symptom summary> })`. Do NOT theorize yet. Do NOT propose causes — that's the next step. Do NOT call `read_task_notes` to find the procedure; it's right here.

2. Search priordeveloper

   Have we seen this before? Search memory for prior investigations in this project.

   Show working prompt

   Run the `search-prior` script. It searches project memory for prior investigations matching the symptom signature. If we've seen this before, the model returns the prior learning + the fix that landed.
   
   If there's a match: state what the prior investigation found, and ask the user if this looks like the same bug (with `ask_user_question`). If yes, jump straight to the fix. If no, proceed to fresh investigation.
   
   If there's no match: note 'no prior matches' to task notes and advance.

3. Reproducedeveloper

   Get a deterministic repro. Often the longest step. Cannot fix what can't be reproduced.

   Show working prompt

   Get the bug to fire on demand. Strategies:
   
   1. **Read the failing path** — find the function/route from the stack trace (use `readFile` / `search_files`).
   2. **Walk inputs backward** — what user action triggered this? What's the request shape?
   3. **Try the minimal trigger** — strip the user's repro down. Half the bugs disappear when you isolate.
   4. **Run a small script if needed** — `run_nodejs_script` against a synthetic input.
   5. **If it won't reproduce**: state that explicitly. Either get more info from the user (`ask_user_question`) or escalate.
   
   When you have a repro, write the minimal trigger to task notes. Do not move on without one.

4. Trace to root causedeveloper

   Follow the data from the failure point back to the smallest 'this is the thing that's wrong.'

   Show working prompt

   Trace backward from the failure. Read the code path. The Iron Law: **the cause is not 'the function returned the wrong thing,' it's WHY the function returned the wrong thing.** Keep asking 'and why is THAT?' until you hit one of:
   
   - A coding bug (assignment swapped, condition inverted, type mismatch)
   - A bad invariant (assumed X but the data has Y)
   - A wrong assumption about a dependency (the API returns null in this case)
   - An environment / config issue (the staging DB doesn't have this column)
   
   Document the chain in task notes. Bullet form is fine. End with: 'Root cause: <one sentence>.'

5. Propose fixdeveloper

   State the fix. Don't apply it yet — let the user (or a separate craftbook) decide.

   Show working prompt

   Now the easy part. State the fix in plain language:
   
   - What file/function changes?
   - What's the new behavior?
   - What did NOT change (so the user knows you didn't gold-plate)?
   - What test would catch this regressing?
   
   Do NOT apply the fix unless the user explicitly asks. Investigation lives separate from edit-the-code so the diff stays minimal and reviewable. Advance.

6. Save learningdeveloper

   Stamp the (symptom → root cause → fix) triple into project memory so future investigations find it.

   Show working prompt

   Run the `save-learning` script with the symptom, root cause, and proposed fix. It saves them to project memory with appropriate tags so `search-prior` finds them next time.
   
   Then report DONE with a one-line summary: 'Investigated <symptom>; root cause: <cause>; fix proposed: <fix>.'

Triggers

Phrases that suggest this craftbook to a crew.

• investigate this
• debug this
• why is this broken
• find the bug
• root cause

Source

View this craftbook on GitHub · MIT license