Structured scratch tracking document for investigation state during bug hunts - prevents re-reading code, losing context, and rabbit holes; maintains external memory so you don't re-derive conclusions
During bug investigations, maintain a lightweight scratch document as external memory. This prevents re-reading code you've already analyzed, losing track of which hypothesis you're testing, and silently drifting into rabbit holes.
Core principle: Write it down once, refer to it later. Re-reading your one-line note is faster than re-reading 200 lines of source.
Always keep the document up to date with your current focus, hypotheses, and learnings from code reads and tests.
Always refer to the document before re-reading code or forming a new hypothesis. If the information is there, use it. If it's not sufficient, read the code, then write a better note.
The document never takes priority over writing or running a test. If you're choosing between updating notes and writing a test, write the test. Update the notes after.
Create ~/tmp/investigate-<short-name>.md during orientation (step 2 of /investigate).
The short name should be descriptive enough to identify the investigation (e.g., , ).
investigate-concurrent-write.mdinvestigate-pipe-zombie-state.mdOnce created, notify the user and provide the file path so they can open it in their editor.
# Investigation: <one-line bug description>
## Error
<assertion/crash message, file:line — written once, never changes>
## Current Focus
<single sentence: what you are doing RIGHT NOW>
## Hypotheses
1. [TESTING] <one sentence> — test: <test name or "not yet written">
2. [REJECTED] <one sentence> — disproved by: <one sentence>
3. [CONFIRMED] <one sentence> — evidence: <test name + result>
## Code Read
- `file:line-range` — <what you learned, short paragraph or bullet>
## Tests
- `file:line` "test name" — <result + what it means, one sentence>
## Ruled Out
- <thing you investigated and eliminated, one sentence why>
## Next
1. <concrete next action>
2. <fallback>
Create the document when:
When created, populate Error, Current Focus, your current hypotheses, and anything you've already learned (backfill "Code Read" and "Tests" from what you've done so far).
file:line.[TESTING] at a time. Commit to one, test it, resolve it, then move on.Valid statuses:
[UNTESTED] — formed but not yet tested. Must become [TESTING] or [REJECTED] soon.[TESTING] — actively being tested. Only one at a time.[CONFIRMED] — test reproduced the bug as predicted.[REJECTED] — test disproved it, or evidence rules it out. Include why.[SUPERSEDED] — replaced by a more specific hypothesis. Reference the replacement.