User Story

As an engineer or tech lead conducting a technical investigation (incident root-cause, bug archaeology, technology evaluation, competitive analysis, regression hunt), I want a structured investigation template + /investigation skill so that I produce a consistent, reusable artefact instead of a fresh ad-hoc doc every time. The template captures what I was investigating, how I went about it, what I found, and what I'm doing next — so future-me (or a teammate) can pick up the thread.

Acceptance Criteria

Template

• New templates/investigation.md shipped, with these sections:
  • ## Trigger — what kicked this off (incident link, customer report, "the bug from #N", etc.)
  • ## Hypothesis being tested — what you thought was happening before you started; what you needed to confirm or rule out
  • ## Method — what you actually did (logs grepped, code paths traced, env vars compared, repros built, etc.). Itemised so a reader can follow the path.
  • ## Findings — what you confirmed, ruled out, and what surprised you. Distinguish observations from conclusions.
  • ## Conclusion — one paragraph: the answer to the original question. Includes confidence level + remaining uncertainty.
  • ## Follow-up actions — what's next (file a bug, file an AgDR, ship a fix PR, write a runbook, share findings with team, escalate, do nothing). Each action linked to a tracker ticket if filed, or marked (no follow-up).
• Template is short (~50 lines), with placeholder examples in each section showing the expected shape

Skill

• New /investigation slash command at .claude/skills/investigation/SKILL.md
• Uses the override resolver from #A — checks custom-templates/investigation.md first, falls back to templates/investigation.md. Each section is filled in interactively (one section at a time, mirroring the per-section flow used by /decide, /feature, /spike)
• Persistence: writes to <projects_dir>/<project_name>/investigations/<YYYY-MM-DD>-<slug>.md (slug derived from the trigger). If invoked from outside a project (ops fork root), writes to <ops_root>/docs/investigations/<YYYY-MM-DD>-<slug>.md
• Argument: /investigation <short-trigger-summary> → pre-fills the Trigger section + slug; or no-arg → asks for the trigger interactively
• Confirmation step before writing: shows the assembled artefact, accepts yes/edit X/cancel
• On success: prints the file path + suggests follow-up commands (/bug, /decide, /spike per the Follow-up actions section)

Single-fork mode + no-override behaviour

• Adopters without a portfolio block fall straight through to templates/investigation.md. Skill works identically.

Tests

• Smoke test on /investigation with a synthetic trigger string: produces a valid markdown file at the expected path with all sections populated
• Override-resolution test: custom-templates/investigation.md present → skill output reflects the custom template

Docs

• templates/investigation.md itself documents when to use it (vs /spike for hypothesis-driven exploration, /bug for filing a bug, /decide for choosing between options)
• CLAUDE.md ## Templates table gains a row

Design Notes

/investigation vs /spike vs /debug. Three adjacent shapes:

• /spike — hypothesis-driven, time-boxed, throw-away exploration that produces the answer (and a memo or follow-up [Feature] via /spike-close). Outcome-focused.
• /debug — structured hypothesis-driven debugging session WHILE the bug is being chased. Process-focused.
• /investigation (new) — the written artefact of an investigation, produced AFTER (or alongside) the work. Documentation-focused.

These cooperate: a /debug session might surface a finding that warrants /investigation to write up, which might recommend /spike to test a fix hypothesis, which closes via /spike-close --promote into a /feature. The shapes don't compete.

Why investigation isn't just an AgDR. AgDRs document decisions (we picked X over Y). Investigations document findings (we observed X, here's the data, here's what we conclude). An AgDR can cite an investigation as input. Different shapes for different jobs.

Depends on #A. Ships after the custom-templates override layer. Without #A, the skill works fine but adopters can't override the template shape.

Out of Scope

• Auto-detection of when an investigation is warranted (operator's call)
• Investigation linking / cross-referencing UI (just plain markdown links between docs)
• Investigation-trend tracking across runs (this isn't an audit; investigations are one-off)
• A /investigation-close companion (the Follow-up actions section IS the close — no separate gate needed)

Effort Estimate

TBD — likely 0.5 day for template + skill + tests once #A's resolver exists.