gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/dist/resources/skills/create-workflow/SKILL.md

@@ -46,8 +46,32 @@ You are a workflow definition author. You help users create valid V1 YAML workfl
 
 **Output Location:**
 
-- Finished definitions go in `.gsd/workflow-defs/<name>.yaml`.
-- After writing, tell the user to validate with `/gsd workflow validate <name>`.
+- Project plugins: `.gsd/workflows/<name>.yaml` (preferred — checked into repo).
+- Global plugins: `~/.gsd/workflows/<name>.yaml` (private to the machine). Use
+  this when the user says "global" or "--global".
+- Legacy location `.gsd/workflow-defs/<name>.yaml` still works but is being
+  phased out — only write there if the user explicitly asks.
+- After writing, tell the user to validate with `/gsd workflow validate <name>`
+  and run with `/gsd workflow <name>`.
+
+**Execution mode:**
+
+Workflow plugins declare a `mode:` field in their top-level YAML (or
+`<template_meta>` block for markdown) that controls runtime behavior:
+
+- `oneshot` — prompt-only, no state, no artifact dir. For one-pass tasks
+  like reviews, reports, or one-off scripts. Default for YAML with a single
+  step when iteration isn't needed.
+- `yaml-step` — full engine with GRAPH.yaml, iterate, and verify. **Default
+  for YAML.** Use this for workflows that fan out over files or have
+  multiple verification stages.
+- `markdown-phase` — phased markdown-driven workflows with STATE.json and
+  phase-approval gates. For multi-session projects. Markdown-only.
+- `auto-milestone` — hooks into the full `/gsd auto` pipeline. Reserved
+  for the bundled `full-project` template; not normally authored by users.
+
+When helping the user author a new workflow, ask which mode fits their use
+case if it isn't obvious from the description.
 </essential_principles>
 
 <routing>
@@ -96,8 +120,11 @@ When assembling the final YAML:
 1. Use 2-space indentation consistently.
 2. Quote string values that contain special YAML characters (`:`, `{`, `}`, `[`, `]`, `#`).
 3. Always include `version: 1` as the first field.
-4. Order top-level fields: `version`, `name`, `description`, `params`, `steps`.
-5. Order step fields: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
-6. Write the file to `.gsd/workflow-defs/<name>.yaml`.
-7. After writing, tell the user: "Run `/gsd workflow validate <name>` to check the definition."
+4. Order top-level fields: `version`, `name`, `mode`, `description`, `params`, `steps`.
+5. Include a `mode:` field (`oneshot` or `yaml-step`). Default to `yaml-step`.
+6. Order step fields: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
+7. Write to `.gsd/workflows/<name>.yaml` by default, or `~/.gsd/workflows/<name>.yaml`
+   when the user says "global" or passes `--global`.
+8. After writing, tell the user: "Run `/gsd workflow validate <name>` to check the
+   definition, then `/gsd workflow <name>` to run it."
 </output_conventions>

package/dist/resources/skills/decompose-into-slices/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: decompose-into-slices
+description: Break a plan or milestone brief into independently-grabbable vertical slices (tracer bullets). Produces slices in `M###-ROADMAP.md` by default, or GitHub issues only with explicit user confirmation. Use when asked to "break this into slices", "decompose the plan", "vertical slices", "break into issues", or when a plan is ready but needs task-level decomposition. Prefers many thin slices over few thick ones; marks dependency order explicitly.
+---
+
+<objective>
+Decompose an approved plan into the smallest useful vertical slices that each cut end-to-end through every relevant layer. Primary output is the `Slices` section of `M###-ROADMAP.md` (matching the template at `src/resources/extensions/gsd/templates/roadmap.md`). Secondary output, only with explicit confirmation, is a set of GitHub issues with blocked-by relationships wired up.
+</objective>
+
+<context>
+This skill runs after the brief is stable — `M###-CONTEXT.md` exists and the user has signed off on scope. It's the bridge from "we know what we're building" to "we know in what order and chunks." The vertical-slice discipline (tracer bullets) is non-negotiable here — it's the core of what makes GSD slices demoable and parallel-safe.
+
+Typical invocation points:
+- After `write-milestone-brief` (or after a `discuss` phase that produced a brief)
+- When a roadmap exists but slices are too thick, too few, or poorly ordered
+- When exporting the plan for external collaborators (GitHub issues)
+</context>
+
+<core_principle>
+**VERTICAL, NOT HORIZONTAL.** A slice that adds "schema + API + UI + tests for feature X on one narrow path" is vertical. A slice that adds "all schemas for all features" is horizontal and is wrong. Horizontal slices destroy the demoability property that makes slice completion meaningful.
+
+**MANY THIN, NOT FEW THICK.** If a slice could be split into two demoable pieces, split it. Thin slices retire risk earlier, parallelize better, and give the user faster feedback on whether the direction is right.
+
+**DEPENDENCY GRAPH, NOT LINEAR LIST.** Slices that don't depend on each other should be marked that way — `depends:[]` means the slice can start immediately. The GSD engine uses this to parallelize.
+</core_principle>
+
+<process>
+
+## Step 1: Load context
+
+1. Read `M###-CONTEXT.md` for the active milestone — the brief is the source of truth for scope.
+2. Read `M###-ROADMAP.md` if one exists — you may be refining rather than creating from scratch.
+3. Read `src/resources/extensions/gsd/templates/roadmap.md` for the exact slice format. The parser depends on it.
+4. If the plan came from a GitHub issue (user passed a URL or number), fetch it with `mcp__github__issue_read`.
+
+## Step 2: Explore the codebase briefly
+
+If you haven't yet, spawn `Agent(subagent_type=Explore)` to map the modules the milestone touches. This is fast and prevents proposing slices that don't align with the codebase's seams.
+
+## Step 3: Draft vertical slices
+
+Produce a draft list of slices. For each slice, capture:
+
+- **ID:** `S01`, `S02`, ... — assigned in dependency order (earliest first).
+- **Title:** short, descriptive, says what the slice delivers.
+- **Risk:** `high` / `medium` / `low` — slices that retire the most uncertainty go first.
+- **Depends:** `[]` or `[S01]` or `[S01,S02]` — which slices must finish first.
+- **Demo line:** "After this: <what is observable when the slice is done>" — one sentence, concrete.
+- **HITL vs AFK** (optional): does this slice require human interaction (architectural decision, design review), or can an agent ship it alone? Default to AFK when unsure.
+
+### Vertical-slice rules
+
+- Each slice cuts through every relevant layer (schema, API, UI, tests, whatever applies).
+- A completed slice is demoable or verifiable on its own.
+- Early slices should prove the hardest thing works — build through the uncertain path.
+- If a slice doesn't produce something testable end-to-end, it's probably a layer — restructure.
+- If the milestone crosses runtime boundaries (daemon + API + UI; bot + subprocess + service; extension + RPC), include an explicit final integration slice that exercises the assembled system.
+
+## Step 4: Quiz the user
+
+Present the draft as a numbered list with ID, title, risk, depends, demo line. Then ask (one round, not many):
+
+1. Does the granularity feel right — too coarse or too fine?
+2. Are the dependency relationships correct?
+3. Should any slice be merged or split?
+4. Any slices misclassified as AFK when they need human input?
+
+Iterate on feedback until the user approves the breakdown. Do not proceed to Step 5 without explicit approval.
+
+## Step 5: Write the roadmap
+
+Once approved, write or update `M###-ROADMAP.md` matching the template exactly. Critical format (parsers depend on it):
+
+```markdown
+- [ ] **S01: Title** `risk:high` `depends:[]`
+  > After this: one sentence showing what's demoable
+- [ ] **S02: Title** `risk:medium` `depends:[S01]`
+  > After this: one sentence showing what's demoable
+```
+
+Fill the rest of the template: Vision, Success Criteria, Key Risks, Proof Strategy, Verification Classes, Definition of Done, Requirement Coverage, Horizontal Checklist (omit entirely for trivial milestones), and the Boundary Map (`S01 → S02` produces/consumes blocks — be specific, name real APIs/types/invariants).
+
+Use `write` to the path `.gsd/milestones/<MID>/<MID>-ROADMAP.md`. Do not edit checkboxes by hand during normal execution — the `gsd_*` tools own state.
+
+## Step 6: Optionally file as GitHub issues
+
+If the user explicitly asks (and only if — outward actions need confirmation), create one GitHub issue per slice with `mcp__github__issue_write`. Create in dependency order so "Blocked by" references can cite real issue numbers.
+
+### Issue body template
+
+```markdown
+## Parent
+
+#<parent-milestone-issue-number> (if applicable; otherwise omit)
+
+## What to build
+
+<concise description of this vertical slice — end-to-end behavior, not layer-by-layer>
+
+## Acceptance criteria
+
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+
+## Blocked by
+
+- Blocked by #<issue-number>
+<or "None - can start immediately">
+
+---
+From milestone brief at `.gsd/milestones/<MID>/<MID>-CONTEXT.md`.
+```
+
+Do NOT close or modify any parent issue.
+
+</process>
+
+<anti_patterns>
+
+- **Horizontal slices.** "S01: All schemas" / "S02: All APIs" / "S03: All UI" — destroys demoability.
+- **Research-only slices.** A slice whose deliverable is a document, not working code, is a spike. Use `/gsd start spike`.
+- **Foundation slices with no demo.** "Set up the base class for X" is a layer, not a slice.
+- **Auto-filing GitHub issues.** Requires explicit user confirmation every time.
+- **Editing roadmap checkboxes by hand later.** `gsd_*` tools own that state during execution.
+- **Vague demo lines.** "Feature X is implemented" is not a demo. "User can submit the form and see the result" is.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every slice is vertical — cuts end-to-end through the relevant layers.
+- [ ] Every slice has a concrete, observable demo line.
+- [ ] Dependency graph is explicit and correct — `depends:[]` on slices that can start immediately.
+- [ ] Risk ordering puts the hardest uncertainty-retiring slices first.
+- [ ] `M###-ROADMAP.md` matches the template format exactly (parsers depend on it).
+- [ ] If the milestone crosses runtime boundaries, a final integration slice exists.
+- [ ] GitHub issues, if filed, cite real issue numbers for blocked-by and reference the brief.
+
+</success_criteria>

package/dist/resources/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: dependency-upgrade
+description: Plan, batch, and verify dependency upgrades safely. Triages outdated packages into risk tiers, upgrades in order (dev/minor/patch first, runtime majors last), verifies each batch before moving on, and produces an auditable commit sequence. Use when asked to "upgrade deps", "bump packages", "update node_modules", "fix vulnerabilities", "upgrade React/Node/TypeScript", or after `/gsd start dep-upgrade`. Complements the dep-upgrade workflow template with execution-level rigor.
+---
+
+<objective>
+Turn a pile of outdated packages into a series of small, verifiable upgrades with clean commits. The deliverable is an ordered upgrade plan, executed with verification between batches, and a summary that flags anything risky for follow-up. No big-bang upgrades.
+</objective>
+
+<context>
+GSD-2 ships a `/gsd start dep-upgrade` workflow template (`src/resources/extensions/gsd/workflow-templates/dep-upgrade.md`) that structures the phases: assess → upgrade → fix breaks → verify. This skill is the execution-level detail inside the upgrade phase — how to batch, how to verify, how to recover from a breaking upgrade without losing the good ones.
+
+Invocation points:
+- `/gsd start dep-upgrade` workflow is running
+- Ad-hoc "bump the deps" request
+- Security advisory response (CVE in a direct dep)
+- Framework major-version update (React 18 → 19, Node LTS bump)
+- Monthly hygiene pass
+</context>
+
+<core_principle>
+**BATCH BY RISK, NOT BY LAZINESS.** `npm update` is a shortcut that blends safe and risky changes into one commit. When something breaks, you can't tell which dep caused it. Always separate: patches and dev-deps first, minors next, majors individually.
+
+**VERIFY BETWEEN BATCHES.** Run the test suite after every batch. Don't stack five batches and hope. If a batch breaks something, you need to know which one.
+
+**ONE MAJOR PER COMMIT.** Major version bumps are where real breakage lives. Keep them isolated so the commit history tells the truth.
+</core_principle>
+
+<process>
+
+## Step 1: Take inventory
+
+Run the ecosystem's outdated check. Capture output, don't act on it yet:
+- Node: `npm outdated` or `pnpm outdated` or `yarn outdated`
+- Python: `pip list --outdated` or `uv pip list --outdated`
+- Rust: `cargo outdated`
+- Ruby: `bundle outdated`
+- Go: `go list -m -u all`
+
+Also capture:
+- `npm audit` (or equivalent) — security advisories
+- Current versions of language runtime, build tool, test runner
+
+## Step 2: Classify each outdated package
+
+For each outdated package, note:
+
+- **Type:** direct dep / dev-dep / transitive
+- **Kind of bump:** patch (1.2.3 → 1.2.4), minor (1.2.3 → 1.3.0), major (1.2.3 → 2.0.0)
+- **Risk:** Low (dev-dep, patch), Medium (runtime minor, dev-dep major), High (runtime major, framework, TypeScript compiler)
+- **Blast radius:** How many files in the repo import it? (Rough count via `rg`.)
+- **Has known breaking changes:** Check the CHANGELOG or release notes for any major bumps — do NOT skip this, and do NOT infer "probably fine."
+
+## Step 3: Build the batch plan
+
+Order:
+
+1. **Batch 1 — Dev dep patches and minors.** Lowest risk, fastest feedback. Includes linters, formatters, type definitions, test runners.
+2. **Batch 2 — Runtime patches.** All patch bumps to runtime deps together.
+3. **Batch 3 — Runtime minors.** One batch per semantic group if any minor carries risk notes; otherwise one batch for the rest.
+4. **Batch 4+ — Each major, individually.** One commit per major. Framework bumps (React, Next.js, Vue, TypeScript) each get their own commit.
+5. **Batch N — Language runtime.** If bumping Node/Python/Rust, last — it changes the compile/run env for everything.
+
+Skip (for now):
+- Anything with "unreleased", "pre", "beta", "rc" tags unless the user explicitly wants pre-release tracking
+- Deps you know are blocked by another dep (e.g., can't bump X until Y supports it)
+
+Present the plan to the user. One round of adjustment. Then execute.
+
+## Step 4: Execute a batch
+
+For each batch:
+
+1. **Start from a clean working tree.** `git status` — no uncommitted changes.
+2. **Apply the upgrades** using the ecosystem command (`npm install package@version ...`, `uv add …`, `cargo update -p …`).
+3. **Regenerate the lockfile** fully if necessary.
+4. **Build.** Run the project's real build — not just typecheck.
+5. **Test.** Run the full suite. Not a scoped subset.
+6. **Lint.** `lsp diagnostics` on changed files + the project linter.
+7. **Smoke-test the app** if it has a running surface (dev server, CLI command).
+
+If any step fails:
+- Investigate before moving on. Don't skip the batch.
+- If the failure is trivial (a rename, a deprecated import), fix it in the same commit — the upgrade broke it, the upgrade commit fixes it.
+- If the failure is non-trivial (an API you heavily depend on was removed), either pin back or split: upgrade the other deps in the batch in this commit, and handle the problem dep separately in Step 5.
+
+**Commit with a precise message:**
+
+```
+deps: bump <scope> — <what changed in one line>
+
+- package-a: 1.2.3 → 1.2.9 (patch)
+- package-b: 2.1.0 → 2.4.0 (minor — no breaking changes in CHANGELOG)
+- package-c: 3.0.1 → 3.0.2 (patch)
+
+Verified: npm test (84/84 pass), npm run build exit 0, lsp diagnostics clean.
+```
+
+## Step 5: Handle stuck majors
+
+For each major that breaks something:
+
+1. **Read the migration guide** — do not guess at the API changes.
+2. **Scope the blast radius** — `rg` for the symbols that changed.
+3. **Decide: upgrade now or defer?** If the migration is a weekend's work and not urgent, file a `/gsd start refactor` follow-up and pin the current major for now.
+4. **If upgrading now:** branch the work as its own slice (`S##`). The dep upgrade is only one task; the migration is the rest of the slice.
+5. **Verify end-to-end after migration.** The test suite alone may miss behavior changes.
+
+## Step 6: Summary
+
+After all batches, produce a rollup:
+
+```markdown
+## Dependency Upgrade — <date>
+
+### Completed
+- Batch 1 (dev patches): 12 packages — commit abc1234
+- Batch 2 (runtime patches): 5 packages — commit def5678
+- Batch 3 (runtime minors): 3 packages — commit ...
+- Batch 4 (React 18 → 19): commit ... — required refactors in <files>
+
+### Deferred
+- typescript 5.3 → 5.7 — requires updating 40+ decorator usages. Filed as M005.
+- vite 4 → 5 — config shape changed. Owner assigned: <user>.
+
+### Still outdated (intentional)
+- <package> — pinned because <reason>
+
+### Security advisories
+- <CVE> resolved by <package upgrade>
+- <CVE> still open — not exploitable in our usage (see comment in package.json)
+```
+
+Append to `.gsd/KNOWLEDGE.md` any non-obvious gotcha from the upgrade (API changes that tripped you up, migration rituals for this codebase).
+
+</process>
+
+<anti_patterns>
+
+- **`npm update` blindly.** Mixes safe and risky in one undiagnosable commit.
+- **Multiple majors in one commit.** When it breaks, you don't know which.
+- **No verification between batches.** You stack failures until nothing works.
+- **Skipping the CHANGELOG.** "It's just a minor" — until it isn't.
+- **Force-merging a failing batch with `--force`.** Leave it broken or roll back; don't lie to git.
+- **Ignoring `--legacy-peer-deps` warnings.** They're telling you the dep graph is incoherent.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Each batch is in its own commit with a precise message.
+- [ ] Majors are one-per-commit.
+- [ ] Test suite, build, and lint passed after every batch (per `verify-before-complete`).
+- [ ] Stuck upgrades are documented with a concrete next step (filed as slice/milestone, or pinned with a reason).
+- [ ] Security advisories are addressed or explicitly triaged.
+- [ ] Summary report exists for the user to review.
+
+</success_criteria>

package/dist/resources/skills/design-an-interface/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: design-an-interface
+description: Produce 3+ radically different designs for a module, API, or interface, compare them in prose, and synthesize a recommendation. Use when asked to "design an interface", "shape this API", "design it twice", "explore module boundaries", or when planning a new deep module and the first idea is unlikely to be the best. Based on "Design It Twice" from A Philosophy of Software Design — the value is the contrast, not the first draft.
+---
+
+<objective>
+Generate at least three radically different interface designs for a single module or API, present them sequentially, compare them honestly, and recommend one (or a hybrid). The goal is to surface the design space — not to pick fast. A small interface hiding significant complexity is a deep module; a large interface with thin implementation is a shallow one. Optimize for the former.
+</objective>
+
+<context>
+This skill runs during planning — before `S##-PLAN.md` task decomposition, or mid-slice when a seam turns out to be more load-bearing than the roadmap assumed. It is not for picking between two libraries. It is for shaping the interface your own code will expose.
+
+Typical invocation points:
+- A slice plan says "add module X" and the shape of X is not obvious.
+- Two callers are about to grow coupled to an interface that has not been designed on purpose.
+- A refactor surfaces a seam that needs to be re-cut deliberately.
+</context>
+
+<core_principle>
+**RADICALLY DIFFERENT, NOT VARIANTS.** Three designs with different method names are one design. Three designs that hide different things, expose different axes of control, or invert the caller/callee relationship are three designs. Enforce real divergence by assigning each sub-agent a constraint that would force a different shape.
+
+**INTERFACE, NOT IMPLEMENTATION.** Do not estimate effort. Do not argue about how hard it is to build. Argue about how the interface behaves from the caller's side and what it hides internally.
+</core_principle>
+
+<process>
+
+## Step 1: Gather requirements
+
+Before spawning anything, answer in the conversation:
+
+- What problem does the module solve?
+- Who calls it? (other modules, external users, tests)
+- What are the key operations?
+- What constraints exist? (performance, compatibility, existing patterns)
+- What should stay hidden inside vs be exposed?
+
+If the user did not supply all of these, ask — one round, 1–3 questions max, per the ask-vs-infer rule.
+
+## Step 2: Spawn parallel design agents
+
+Use `Agent(subagent_type=general-purpose)` for 3–4 agents in one message so they run concurrently. Each agent gets the same requirements brief plus one divergent constraint:
+
+- Agent 1: "Minimize method count — 1 to 3 entry points max."
+- Agent 2: "Maximize flexibility — support many extension points and composition."
+- Agent 3: "Optimize for the single most common caller — make the default case trivial and the advanced case possible."
+- Agent 4 (optional): "Design around a ports-and-adapters boundary — interface is the port, concrete implementations are adapters."
+
+Each agent returns:
+
+1. Interface signature (types, methods, params)
+2. One worked usage example showing a real caller
+3. What complexity this design keeps internal
+4. Trade-offs — what it's bad at
+
+## Step 3: Present sequentially
+
+Show the three designs one after another. Let the user read each before the next. Do not lead with the comparison — the value is in feeling the shape of each option first.
+
+## Step 4: Compare in prose
+
+After all three are on the page, compare them on:
+
+- **Simplicity** — fewer methods and simpler params are easier to learn and harder to misuse
+- **Depth** — small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Generality vs specialization** — does it cover the real use case without overfitting?
+- **Efficiency of the shape** — does the interface let the implementation be efficient, or force awkward internals?
+- **Misuse surface** — what can a caller do wrong?
+
+Prose, not a table. Highlight where the designs diverge most sharply — that is where the interesting trade-off lives.
+
+## Step 5: Recommend
+
+Be opinionated. Pick one, or propose a hybrid that takes specific elements from multiple designs. State the reason in one paragraph. The user wants a strong read, not a menu.
+
+## Step 6: Capture the decision
+
+Once the user picks:
+
+- Append to `.gsd/DECISIONS.md` with the chosen shape and the reason.
+- If a slice is active, update `S##-CONTEXT.md` with the interface sketch.
+- Do not write the implementation — that happens during execute.
+
+</process>
+
+<anti_patterns>
+
+- **Three-variants-of-the-same-idea:** all three use a builder, all three return the same object, etc. Kill and re-spawn.
+- **Implementation creep:** proposing file paths, call graphs, or internal data structures. Keep it at interface shape.
+- **Skipping comparison:** presenting three designs and asking "which do you like?" The comparison is the whole skill.
+- **Effort-based ranking:** "#2 is easiest to build" is not an interface argument. Rank by what the caller experiences.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] 3+ genuinely different interface shapes were produced.
+- [ ] Each design shows a real usage example, not a type signature in isolation.
+- [ ] Trade-offs are named per design.
+- [ ] A specific recommendation (or hybrid) is on the page with a reason.
+- [ ] The decision is captured in `.gsd/DECISIONS.md` or the active `S##-CONTEXT.md`.
+
+</success_criteria>

package/dist/resources/skills/forensics/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: forensics
+description: Post-mortem a failed GSD auto-mode run. Traces from symptom to root cause using `.gsd/activity/*.jsonl`, `.gsd/journal/YYYY-MM-DD.jsonl`, `.gsd/metrics.json`, and `.gsd/auto.lock`. Produces a filing-ready bug report with file:line references and a concrete fix suggestion. Use when asked to "forensics", "post-mortem", "why did auto-mode fail", "trace the stuck loop", "debug the crash", after `/gsd forensics` is invoked, or when a session ended in an unexpected terminal state. Reads existing artifacts — does NOT re-run anything.
+---
+
+<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 (dispatch-match, stuck-detected, guard-block, unit-start/end, terminal)
+- `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:
+
+```markdown
+## 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>