// Produces a structured post-incident analysis — timeline, root cause, and actionable follow-ups — while context is fresh.
| 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) |
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>$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.
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.
Based on the incident context, automatically collect evidence. Run these in parallel where possible:
Run these in parallel:
git log on affected files (last 2 weeks or user-specified range), git log --all --oneline for related commits, gh pr view for referenced PRsgh run list for recent failures, gh run view <id> for referenced runs. Skip if no CI context — do not block on missing data.git log --oneline <file>). Note files lacking tests or with high churn.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?"
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.
Before writing the debrief file, ensure the session is on a feature branch:
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).
Use the AskUserQuestion tool to present next steps:
Question: "Debrief complete! What would you like to do next?"
Options:
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.
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
DO NOT make code changes. This skill produces a document only. Action items become separate tickets.
Explores requirements and approaches through collaborative dialogue before planning implementation.
Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request.
Sets up a workspace branch or worktree before writing artifacts.
Propose and create conventional commit messages for staged changes. Follows Conventional Commits spec and VGV workflow.
Stage, commit, push, and open a pull request following project conventions and the Conventional Commits spec. Accepts optional skip-checks argument to bypass validation when called from /build.
Scaffolds a new project by routing to the right companion plugin's create skill.