forensics

name

forensics

description

Post-mortem a failed GSD auto-mode run. Traces symptom to root cause via `.gsd/` activity, journal, metrics, and lock artifacts, producing a filing-ready bug report with file:line refs and a fix suggestion. Use when asked to "forensics", "post-mortem", "why did auto-mode fail", "trace the stuck loop", "debug the crash", after `/gsd forensics`, or when a session ended in an unexpected terminal state. Reads artifacts only — re-runs nothing.

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. 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