SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbug-autopsy

bug-autopsy

General & other

View repository

Updated 10-15 21:09

About this skill

bug-autopsy

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in this skill are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

feynman-walkthrough's sibling for failures. Where that skill walks a learner through a healthy system, this one walks a failure that already happened — trigger → propagation → detection → fix — and leaves behind a blameless post-mortem the next engineer can audit link by link. The failure is treated as material to learn from, not a fire to fight: if the incident is still burning, triage first and come back.

Locating this skill's helpers (do this first). The steps below run bundled scripts. You execute from the target repo, not from this skill's directory, so a path written relative to this skill will not resolve. Resolve the base directory once and use it everywhere — including in any subagent prompt, which MUST receive the literal absolute path:

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'bug-autopsy' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

Ground rules

  • Evidence or inference, labeled. Every timeline entry and every "why" MUST cite its evidence — file:line, commit sha, CI run, log timestamp, issue comment. Where the record is silent, reconstruct by judgment, but the entry MUST be marked (inference); a labeled guess is useful, an unlabeled one poisons the document. evidence: none, n/a, TBD, or an unfilled <...> template placeholder is not evidence — it is a label wearing the shape of a citation with nothing behind it; with no record, mark the entry (inference) instead. A lint PASS means a basis was stated, not that it is true.
  • Blameless, structurally. Root causes SHOULD be systemic — a missing guardrail, an absent test, a process or design gap — and SHOULD NOT be a person. When a chain lands on "someone made a mistake", it is unfinished: ask why the system let that mistake reach users (the translation table is in references/five-whys.md).
  • Boundaries. This skill explains failures that already happened. Live debugging and on-call triage are out of scope; understanding a healthy system is feynman-walkthrough; verifying a codebase's claims against authoritative sources is base-in-reality.

Workflow

Python interpreter. Most commands in this skill and its references are written with python3. Find the interpreter once, before the first of them. If $SKILL_PYTHON is set, use it. Otherwise, on macOS, if command -v python3 prints /usr/bin/python3 and xcode-select -p fails, that python3 is the install stub: skip it without running it. Use the first of python3, python and py -3 that is not skipped and for which <interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' exits 0. Write the interpreter you found in place of python3 in every command, and in any Bash(...) permission rule you suggest. Commands that start with uv run or {python} keep their own form. In a session resumed under a Bash(...) allowlist, skip this lookup and use the interpreter that the allowlist names. If none passes, follow this skill's own fallback for running without Python where it gives one; otherwise stop and tell the user that this skill needs Python 3.10 or newer.

  1. Scope. One light round: what failed (the user-visible symptom), the blast radius (who/what was affected, for how long), and what the learner will do with the understanding — fix a recurrence, prevent the class, or teach the team. The answer sets how deep the whys chain and the prevention items need to go. Skip anything the conversation already answered.
  2. Reconstruct the timeline from evidence. Work the records: git log/git blame around the suspect area, CI runs, logs, issue and PR threads, alert history. Produce ordered entries — trigger, propagation, detection, mitigation, fix — each carrying a timestamp and an evidence citation; label unbacked reconstruction (inference). Where records conflict, prefer the machine-generated one and note the conflict.
  3. Chase root cause with a 5-Whys chain. Per references/five-whys.md: start from the user-visible failure, evidence every level, go at least three deep, branch when the chain forks, and stop at the first systemic cause — the gap that, once closed, prevents the whole class. Side branches that don't bottom out become contributing factors.
  4. Write the post-mortem from references/postmortem-template.md. Required sections: Summary; Impact; Timeline; Root cause (the whys chain); Contributing factors; Fix, naming the verifying commit/test/CI run; Prevention, as checkbox items each with an owner and a completion check; Links.
  5. Lint and repair. Run python3 "$SKILL_DIR/assets/postmortem_lint.py" <file> and fix findings until it prints POSTMORTEM_LINT: PASS. Structural failures (missing/empty sections, untimestamped timeline entries, a shallow whys chain, non-checkbox prevention items) are hard; blame-phrasing WARN lines are prompts to reframe — resolve them unless the flagged text is a direct quote you're preserving as evidence.
  6. Persist into the OKF bundle and re-pin. Write the document as <subject>/postmortem.md (concept type: Postmortem — the frontmatter ships at the top of the template) in the knowledge bundle feynman-walkthrough maintains, e.g. docs/knowledge/; create the bundle there if none exists. Link it from the subject's index.md, append a dated entry to the bundle's log.md, and re-pin source fingerprints — via the sibling tool (feynman-walkthrough/assets/okf.py pin) when installed, or by hand following the bundle's existing layout.

Deliverable

A lint-clean, evidence-cited, blameless post-mortem living in the knowledge bundle: every timeline entry timestamped and sourced, a whys chain at least three levels deep ending at a systemic cause, a fix tied to its verifying commit or test, and prevention items someone can actually tick off — plus the updated bundle index, log entry, and re-pinned fingerprints. The chat walkthrough of the failure is the tour; the persisted post-mortem is the artifact that outlives it.

Output style. Write reports and explanations for the user in about 80% ASD-STE100 Simplified Technical English. Use short sentences, common words, active voice and one action per step.

Revisit across sessions

The post-mortem is a living record, not a filing. When a session opens on a subject with an existing post-mortem, check bundle freshness first (feynman-walkthrough/assets/okf.py status <subject> where available):

  • Prevention audit. If the same defect class recurs, the old post-mortem's Prevention checkboxes are the first evidence to read — an unchecked box is itself a finding, and usually the first "why" of the new chain.
  • STALE bundle → the code moved since the autopsy; say so before citing the post-mortem's file:line references, and refresh them if the learner will act on them.
  • New autopsy, old subject → append, don't overwrite: a second postmortem-*.md concept in the same subject, cross-linked from the first, keeps the failure history auditable.