| 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 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:
- Review and refine: improve the document using structured review
- Generate issue previews: format action items as ready-to-copy GitHub issue drafts
- 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:
-
Check for issue templates: look for .github/ISSUE_TEMPLATE/ in the project root. Read every .yaml or .yml file found there (skip config.yml).
-
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 required field defined in the template. Include a Template: line naming the chosen template file.
-
If no templates exist: fall back to the generic format:
---
Title: <specific, actionable title>
Label: prevent | detect | respond
Body:
## Context
Debrief: docs/debriefs/YYYY-MM-DD-<topic>-debrief.md
Root cause: <one-line summary from debrief>
## What happened
<relevant excerpt from the debrief timeline or root cause section>
## What to do
<the action item, specific and linked to code/files where possible>
---
Render all previews in a single fenced block so the user can copy them. Do not call gh, glab, or any external CLI — output is display only.
Output Summary
When complete, display:
Debrief complete!
Document: docs/debriefs/YYYY-MM-DD-<kebab-case-topic>-debrief.md
Severity: <severity>
Root cause: [one-line summary]
Action items: <N> prevent, <N> detect, <N> respond
Key Principles
- Blameless — Focus on systems and processes, never individuals
- Evidence-based — Link findings to commits, PRs, code paths, and logs
- Actionable — Every action item is specific and assignable
- Honest about gaps — Mark unknowns explicitly rather than guessing
- Tech-agnostic — No language or framework assumptions in the skill itself
Important
DO NOT make code changes. This skill produces a document only. Action items become separate tickets.
