/debrief

name: debrief
user-invocable: true
description: Produces a structured post-incident analysis — timeline, root cause, and actionable follow-ups — while context is fresh.
when_to_use: Use when user says "debrief", "post-mortem", "incident review", or "root cause analysis".
argument-hint: incident description, PR/commit refs, or error context
effort: high
compatibility: Designed for Claude Code (or similar products with agent support)

Post-incident debrief

Produce a structured, blameless debrief document after an incident, failed release, or significant bug. Capture what happened, why, and what to change — while the context is still fresh.

**Use this when** a production incident, failed release, flaky deploy, or significant bug warrants more than just a fix — when the team needs to understand *why* it happened and prevent recurrence.

Incident Context

<incident_context>$ARGUMENTS</incident_context>

**If the incident context above is empty, ask the user**: "What incident would you like to debrief? Describe what happened, link to relevant PRs/commits, or paste error logs."

DO NOT proceed until you have a description from the user.

Execution Flow

1. Gather initial information

Use the **AskUserQuestion tool** to fill in gaps one question at a time. Adapt based on what the user already provided — skip questions whose answers are already clear from the incident context.

**Key questions to resolve:**

| Topic | Example Questions | |-------|-------------------| | What happened | What was the user-visible impact? What broke? | | When | When did it start? When was it detected? When was it resolved? | | Where | What platform, environment, or service? (e.g., prod vs staging, iOS vs Android, specific API) | | Severity | How many users/systems were affected? Was data lost? | | Detection | How was it discovered? Alert, user report, or manual observation? | | Resolution | What was the fix? Is it deployed? Is it a temporary workaround? | | References | Relevant PRs, commits, CI runs, error logs, or monitoring links? |

**Exit condition:** Continue until you have enough context to reconstruct a timeline, OR the user says "that's all I have" or "proceed."

The skill must work with partial information. Not every debrief has full CI logs or a complete timeline. Note gaps explicitly in the document rather than blocking on them.

2. Gather evidence from the codebase

Based on the incident context, automatically collect evidence. Run these in parallel where possible:

Run these in parallel:

• **Git history**: `git log` on affected files (last 2 weeks or user-specified range), `git log --all --oneline` for related commits, `gh pr view` for referenced PRs
• **CI/CD evidence**: `gh run list` for recent failures, `gh run view <id>` for referenced runs. Skip if no CI context — do not block on missing data.
• **Affected file analysis**: Check test coverage (Glob for test files), recent change frequency (`git log --oneline <file>`). Note files lacking tests or with high churn.

3. Analyze root cause

Synthesize the evidence to identify the **root cause** (specific change, gap, or condition — trace to commits or code paths) and **contributing factors** (missing tests, no monitoring, unclear ownership, insufficient review).

**Blameless framing:** Focus on systems and processes, not individuals. Ask "what made this possible?" not "who caused this?"

4. Draft action items

Generate concrete, assignable follow-ups. Each must be specific (not "improve testing"), linked to code where possible, and categorized:

| Type | Purpose | Examples | |------|---------|----------| | **Prevent** | Would have stopped this incident | Add validation, add test | | **Detect** | Would have caught it sooner | Add monitoring, add CI check | | **Respond** | Would have made recovery faster | Add runbook, add feature flag |

Action items are recorded in the document only — they become separate tickets.

5. Set up workspace

Before writing the debrief file, ensure the session is not on the base branch:

• Run `git rev-parse --abbrev-ref HEAD`. If the current branch is a base branch (`main`, `master`, or `develop`), use **AskUserQuestion** to offer creating a feature branch — `git checkout -b <type>/<kebab-topic>`, name under 60 characters — before writing. If already on a feature branch, continue without prompting.

6. Write the debrief document

Write the document to `docs/debriefs/YYYY-MM-DD-<kebab-case-topic>-debrief.md`.

Ensure `docs/debriefs/` directory exists before writing.

**Document structure:**

Use the [debrief template](references/template.md) as the document structure. Adapt it to fit the available information — omit sections with no relevant data rather than filling them with "N/A." Add sections if the incident warrants it (e.g., a "Customer Communication" section for user-facing incidents).

7. Handoff

Use the **AskUserQuestion tool** to present next steps:

**Question**: "Debrief complete! What would you like to do next?"

**Options:**

1. **Review and refine**: improve the document using structured review 2. **Generate issue previews**: format action items as ready-to-copy GitHub issue drafts 3. **Done**: debrief complete

**If the user selects "Review and refine"** → apply the @refine-approach skill to the document. When refinement is complete, present these options again (without the refine option).

**If the user selects "Generate issue previews"** → read the action items from the written debrief document, then:

1. **Check for issue templates**: look for `.github/ISSUE_TEMPLATE/` in the project root. Read every `.yaml` or `.yml` file found there (skip `config.yml`).

2. **If templates exist**: render one preview block per action item using the most appropriate template. Map each item to a template based on its content (e.g., a missing test or validation gap → bug report; a new monitoring check → feature request; a dependency update or runbook → chore). Populate every requi