nacl-postmortem

Contract

Inputs this skill consumes:

• A project built end-to-end through nacl-* skills, with a git dev→fix boundary (feature/FR commits stopped, a wave of fix/bugfix/test-debt commits started).
• The project's .tl/tasks/* specs (frozen at build time), its code, and git log.
• nacl-tl-core/references/gate-fire-catalog.md (G1–G11) + project-gap-closure.md (the ten GAP categories) — the mapping authority (read-only).

Output this skill produces:

• A single retrospective at docs/retrospectives/<project>-postmortem.md, sections in this exact order (so the workflow and the prose-recipe outputs are structurally interchangeable):
  1. TL;DR — headline finding + bucket percentages.
  2. Table, one row per fix case: SHA · description · bucket · owning skill · why missed.
  3. Per-case sections with verbatim spec quotes (no paraphrase).
  4. Per-skill diagnosis — which cases hit it, the systemic gap, a recommendation (no skill edits in this deliverable — that is a separate user decision).
  5. Cross-cutting patterns.
  6. Recommended next steps — one bullet per proposed skill PR.

Two producers, one deliverable

This skill has two interchangeable producers. Pick by environment; the artifact structure is identical either way.

A. Workflow (preferred when available) — .claude/workflows/nacl-postmortem-panel.js

Five parallel auditors → an evidence verify stage → a deterministic GAP→owning-skill synthesis → one writer agent. Matches every condition that justifies a workflow's cost: rare, read-only, high-stakes, genuinely helped by independent specialist perspectives.

• Requirements: Claude Code ≥ 2.1.154 (dynamic workflows). Spawns ~8–12 agents and costs meaningfully more tokens than the prose recipe — that is the trade for breadth + adversarial verification on a once-per-project audit. Watch /workflows for per-phase totals.

• Invoke (the project path is the only required arg):

  Run the nacl-postmortem-panel workflow with args:
  { "projectPath": "/abs/path/to/project", "project": "<name>",
    "boundaryHint": { "sha": "<sha>", "subject": "<subj>" },   // optional; else auto-resolved
    "artifactOut": "docs/retrospectives/<project>-postmortem.md",
    "modelOverrides": { "specdrill": "opus", "qaskip": "haiku" } }  // optional (A5 cost tiering)
  

• The five auditors (parallel barrier — synthesis needs all five):

  1. Project shape — stack, .tl/ tasks done/skipped, BA/SA artifact location (graph vs prose).
  2. Fix-commit categorization — every fix-wave commit → buckets, counts + verbatim examples.
  3. Spec-artifact drill — locate the governing spec, quote it verbatim, classify each case with the load-bearing trichotomy SPEC_WRONG / SPEC_MISSING / SPEC_RIGHT_DEV_DRIFTED.
  4. Cross-UC connectivity — "UC-X declares an entry but UC-Y has no button to reach it" (invisible to per-UC review).
  5. nacl-tl-qa SKIPs — missing-provider-key skips are almost always a top-3 root cause.

• Three fixes baked in (from the workflows experiment): (1) repo access — auditors read .tl/, code, and git freely; (2) evidence, not paraphrase — a verify stage re-reads each quoted span and drops a case only on high-confidence positive counter-evidence, else keeps it and flags needs_context; (3) requirements traceability — each fixed defect maps to a requirement that should have been specified/reachable (whyMissed).

• Deterministic synthesis — the GAP_TO_SKILL JS table maps each finding's GAP category to its owning skill(s) + gate IDs (G1–G11). No agent decides the mapping; an unmappable fix is reported as unmapped (an honest "no NaCl gate would have caught this"), not force-attributed.

B. Prose recipe (portable fallback) — memory skill-postmortem-algorithm

When workflows are unavailable, run the recipe by hand: three (→ five) sequential/parallel Explore agents (same auditor responsibilities), then synthesis, then write the same artifact. nacl-migrate's canary retrospective gate runs the 3-auditor core. The recipe is canonical; the workflow is an opt-in alternative producer of the same deliverable.

Guardrails

• Verify quotes by reading actual files, not agent output — agents paraphrase. The workflow's verify stage enforces this; in the prose recipe, re-open the file.
• No skill edits in this deliverable. Recommendations only; editing a skill is a separate, user-approved step.
• no-private-info-in-public-repo — the artifact lives in this framework repo only when the audited project is the user's own (e.g. family-cinema); otherwise keep it in the project repo. Never include local /Users/ paths or dump metadata in the artifact body.

References

• .claude/workflows/nacl-postmortem-panel.js — the workflow producer.
• .claude/workflows/README.md — workflow runtime requirements + the args/scriptPath note.
• nacl-tl-core/references/gate-fire-catalog.md, project-gap-closure.md — G1–G11 + ten GAP categories (mapping authority, read-only).