gsd-build/gsd-2/forensics

<objective> Turn scattered GSD runtime artifacts into one coherent cause chain. The deliverable is a GitHub-issue-ready report that names the file and line where the bug lives, cites the evidence, and proposes a fix. Forensics is archaeology, not re-run — no modifying state, no triggering commands, just reading the paper trail. </objective>

<context> GSD persists a lot of runtime evidence under .gsd/:

• activity/{seq}-{unitType}-{unitId}.jsonl — full tool-call and message stream per unit
• journal/YYYY-MM-DD.jsonl — iteration-level events. Orchestrator path emits orchestrator-* events (orchestrator-dispatch-match, orchestrator-guard-block, orchestrator-terminal, etc.); legacy loop events (dispatch-match, stuck-detected, guard-block, unit-start/end, terminal) can still appear on non-orchestrator paths.
• metrics.json — token/cost ledger; duplicate type/id entries indicate a stuck loop
• auto.lock — JSON snapshot of the currently-owning PID; stale lock = crash mid-unit
• forensics/ — saved prior reports
• debug/ — debug logs if enabled
• runtime/paused-session.json — serialized session when auto-mode paused
• doctor-history.jsonl — doctor check history

The /gsd forensics command pre-computes a forensic report with anomalies flagged. This skill is the manual investigation that goes deeper, or runs when the automated report isn't enough.

Invocation points:

• /gsd forensics has been run and user wants deeper analysis
• Auto-mode exited unexpectedly, no obvious cause
• Same unit dispatched multiple times (stuck loop suspected)
• A session crashed and auto.lock is stale
• User reports "it just stopped" or "it did the wrong thing"

</context>

<core_principle> READ-ONLY. Forensics touches no live state. Non-mutating inspection commands (e.g., ps, top -b, cat /proc/*) are allowed for checking process status or reading system files. Strictly prohibited: gsd_* writes, commands that modify state, executing binaries that produce side effects, writing to files (outside the final report), or re-running the failed unit. The evidence must stay pristine for future investigations.

SYMPTOM → ROOT CAUSE, WITH CITATIONS. Every claim in the report is backed by an artifact path and either a line number or a JSONL field. "The loop got stuck because of a race" is not useful; ".gsd/journal/2026-04-19.jsonl:142 shows stuck-detected with flowId X, caused by dispatch-guard.ts:87 returning the same unit after unit-end" is.

PRE-PARSED LEADS, NOT CONCLUSIONS. If /gsd forensics has surfaced anomalies, treat them as hypotheses to verify, not answers. </core_principle>

<process>

Step 1: Locate the evidence

Read what's in .gsd/:

1. auto.lock — is it stale? Check PID against ps (read-only inspection, allowed). Stale = crash.
2. Most recent .gsd/activity/*.jsonl — sort by mtime, newest first. That's the last unit that ran.
3. Today's .gsd/journal/YYYY-MM-DD.jsonl — the iteration-level view.
4. .gsd/metrics.json — does any type/id appear more than once? (stuck loop signal)
5. .gsd/runtime/paused-session.json — if present, what was the pause reason?

Step 2: Reconstruct the failure from the activity log

Activity JSONL format:

• Each line is {type: "message", message: {...}}.
• message.role: "assistant" → content[] with type: "text" reasoning and type: "toolCall" invocations.
• message.role: "toolResult" → {toolCallId, toolName, isError, content}.
• usage on assistant messages tracks tokens and cost.

To trace a failure:

1. Search for isError: true tool results in the last activity log. That's usually the proximate symptom.
2. Walk backwards to the assistant message that made the call. Read the text content — that's the agent's reasoning at the moment of failure.
3. Keep walking back. Find where the agent's model of the state diverged from reality.

Step 3: Cross-reference the journal

For each symptom from the activity log, find the matching journal events:

• stuck-detected + same flowId → the loop detected repetition. data.reason says why.
• guard-block → a dispatch guard refused to run a unit. Check data.reason and trace to dispatch-guard.ts logic.
• unit-end followed by another unit-start for the same unitId → re-dispatch. If tied to stuck-detected, the artifact verification failed after the unit succeeded.
• terminal → auto-mode decided to stop. data.reason tells you why.

Use flowId to reconstruct one iteration; use causedBy to follow causal chains across iterations.

Step 4: Name the root cause

A good root cause is:

• Specific: a function, a state transition, a missing guard.
• Falsifiable: if we changed X, would the failure go away?
• Sourced: cites a file and (where applicable) a line number.

Bad root cause: "Auto-mode got stuck in a loop." Good root cause: "After slice completion, auto-unit-closeout.ts emits unit-end before auto-post-unit.ts updates the roadmap checkbox. The next iteration-start finds the same unit [ ] and re-dispatches — dispatch-guard.ts:42 has no check against the freshly-ended unitId."

Consult the source map in src/resources/extensions/gsd/prompts/forensics.md to map symptoms to the likely domain files.

Step 5: Propose a fix

For the root cause:

• Which file and function holds the bug?
• What minimal change would eliminate it?
• What test would have caught it? Can one be added?
• Is this a regression from a recent commit? (Run git log -- path/to/file.ts mentally; do NOT run git commands that could modify state.)

Step 6: Write the report

Format the output as a GitHub-issue-ready report:

## Symptom
 
<what the user saw — quote the error or describe the observed behavior>
 
## Evidence Trail
 
1.`.gsd/auto.lock` — <state: stale / fresh>
2.`.gsd/activity/042-slice-S02.jsonl:128` — <isError: true from `gsd_task_complete`>
3.`.gsd/journal/2026-04-19.jsonl:87` — <stuck-detected flowId 7a3c…>
4.`.gsd/metrics.json` — <unit type/id "slice/S02" appears 3 times>
 
## Root Cause
 
<specific named cause — file, function, state transition>
 
`src/resources/extensions/gsd/auto-unit-closeout.ts:<line>`: <exactly what goes wrong>
 
## Proposed Fix
 
<minimal change — file, function, what to change>
 
## Test
 
<what test would have caught this; whether one should be added>
 
## Confidence
 
<high / medium / low> — <what would change this confidence>

Offer to file this as a GitHub issue via mcp__github__issue_write — explicit confirmation required per the outward-action rule. Also save a copy to .gsd/forensics/<slug>.md for future reference.

</process>

<anti_patterns>

• Running any `gsd_*` write tool during forensics. Evidence stays pristine.
• Re-running the auto-mode loop to "reproduce." That overwrites the activity log. Read the existing one.
• Vague root cause. "There's a race" is not a root cause. Name the race.
• No citations. Every claim gets an artifact path.
• Skipping the journal. The journal is the only view that shows dispatch-level decisions.
• Auto-filing the GitHub issue. Outward actions need confirmation.

</anti_patterns>

<success_criteria>

• [ ] The symptom is quoted, not paraphrased.
• [ ] Every claim in the evidence trail cites a file and a line or field.
• [ ] The root cause names a specific file, function, or state transition.
• [ ] The proposed fix is minimal and falsifiable.
• [ ] Confidence is stated honestly.
• [ ] Report is saved under .gsd/forensics/ even if not filed as an issue.

</success_criteria>