agent-bober 0.12.0 → 0.15.0

package/skills/bober.incident/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: bober-incident
+description: Use when responding to a production incident or system-level failure — kicks off the incident pipeline (diagnose → propose actions → deploy with gates → verify resolution → postmortem). The top-level entry that routes between bober-diagnoser, bober-deployer, and bober-postmortemer based on incident phase.
+---
+
+# Top-Level Incident Response
+
+## Overview
+
+This skill governs the **full incident lifecycle** — from the first symptom report through root-cause diagnosis, remediation execution, resolution verification, and postmortem synthesis. It is the entry point that routes between all Tier 3 sub-disciplines.
+
+The lifecycle is **phased and deterministic**. Each phase transition is driven by the output of a sub-skill (diagnoser, deployer, verifier) and gated by the incident state machine. No phase can be skipped. No resolution can bypass verification. This is the architecture that prevents "I fixed it" from meaning "I changed something and it seems better now."
+
+Key architectural invariants:
+- Every incident has a timeline (`timeline.jsonl`) from creation to resolution.
+- Every destructive action passes through a checkpoint gate before execution.
+- Every resolution requires a verifiable artifact (metric evidence or an override token with an audit trail).
+- Every resolved incident triggers a postmortem automatically.
+
+This skill does **not** replace `bober.diagnose`, `bober.deploy`, `bober.runbook`, or `bober.postmortem`. It orchestrates them.
+
+## The Iron Law
+
+```
+NO INCIDENT WITHOUT TIMELINE; NO RESOLUTION WITHOUT VERIFICATION
+```
+
+Both clauses are unconditional. They do not have exceptions for urgency, familiarity, or pipeline mode.
+
+## When to Use
+
+Use this skill when:
+- A page fires (PagerDuty, OpsGenie, or any on-call alert)
+- An SLO breach is detected (error rate, latency, availability below threshold)
+- A user-reported outage is confirmed by at least one objective signal
+- A deployment causes observable regression (rollout watchdog fires)
+- Any system-level failure requires coordinated diagnosis + remediation
+
+Do NOT use this skill for:
+- Planned maintenance (no incident, no postmortem required)
+- Feature work that happens to touch infrastructure
+- Read-only investigation with no remediation intent (use `bober.diagnose` directly)
+
+## Workflow
+
+Execute each phase in order. Do not skip phases. Phase transitions are guarded by the incident state machine.
+
+### Phase 1: Start the Incident
+
+```bash
+bober incident start "<symptom>" [--severity S1|S2|S3|S4]
+# Returns: incidentId
+```
+
+This creates the incident artifact directory (`.bober/incidents/<id>/`) with all required files. The incident is immediately in status `investigating`. The incidentId anchors all subsequent artifacts.
+
+Severity semantics (informational — does NOT affect routing):
+- **S1** — Total outage; all users affected; no workaround.
+- **S2** — Major degradation; significant user impact; partial workaround available.
+- **S3** — Partial degradation; moderate impact; workaround available.
+- **S4** — Minor issue; limited impact; no immediate user harm.
+
+### Phase 2: Diagnose
+
+Invoke the `bober-diagnoser` agent with the incidentId and symptom. The diagnoser:
+1. Queries observability tools (`obs__*__*`).
+2. Writes a `diagnoses/<diagnosisId>.json` with hypotheses + nextActions.
+3. Each nextAction declares `blastRadius: safe | risky`.
+
+The incident state machine reads `nextActions`:
+- One or more `risky` actions → transition to `remediating`.
+- No risky actions (or no actions at all) → stay at `investigating`. Operator ends the incident with `bober incident end`.
+
+### Phase 3: Remediate (if nextActions include risky steps)
+
+Invoke the `bober-deployer` agent for each risky nextAction.
+
+Each action passes through the Sprint 20 gate:
+- Gate mechanism is resolved from `bober.config.json` → `pipeline.checkpointMechanism`.
+- In `careful` mode: operator must explicitly approve each risky action before execution.
+- In `autopilot` mode: gate fires and auto-approves but STILL writes an audit trail.
+
+No action is executed without a `ChangeEntry` (with `inverse.description`) written first.
+
+After execution, verify resolution:
+```bash
+bober incident end --verified   # if external verification confirms
+bober incident end --override "Investigation concluded; no metric available"  # operator override
+```
+
+### Phase 4: Verify Resolution
+
+Resolution requires one of:
+1. `opts.verifyResult.verified === true` — metric confirmation from `verifyResolution()`.
+2. `opts.overrideToken = 'SKIP_METRIC_VERIFY: <reason>'` — operator asserts resolution with documented reason.
+
+Neither path can be skipped. The gate is enforced in `setIncidentStatus` (Sprint 22).
+
+### Phase 5: Postmortem
+
+On transition to `resolved`, Sprint 23's auto-trigger fires:
+- `generatePostmortem(projectRoot, incidentId)` synthesizes `postmortem.md` from all artifacts.
+- The postmortemPath is written to `incident.json`.
+
+The postmortem is automatic. Operators can view or regenerate:
+```bash
+bober postmortem show <incidentId>
+bober postmortem generate <incidentId>  # re-synthesize
+```
+
+## Slash Command Flow (/bober-incident)
+
+When a user invokes `/bober-incident` from Claude Code:
+
+1. **If no symptom provided in the invocation:**
+   - Prompt: "What is the symptom or alert? (e.g., '500 errors on checkout endpoint', 'p99 latency >3s on API gateway')"
+   - Wait for a clear, specific symptom description before proceeding.
+   - Do NOT proceed with a vague symptom like "something is wrong".
+
+2. **If symptom is provided:**
+   - Run: `bober incident start "<symptom>" [--severity <S1|S2|S3|S4>]`
+   - Surface the incidentId to the user immediately.
+   - Transition to diagnosis phase.
+
+3. **At each phase transition:**
+   - Announce the transition clearly: "Phase transition: investigating → remediating"
+   - Display the incidentId so the operator can track state.
+   - Surface any gate approvals required before proceeding.
+
+4. **Output format:**
+   - Use markdown headers for phases.
+   - Use code blocks for commands.
+   - Use bold for incidentId and phase names.
+   - Show `bober incident status <id>` output at each transition.
+
+Example invocation flow:
+```
+/bober-incident 500 errors spiking on checkout endpoint
+
+→ Incident created: inc-20260524-500-errors-on
+→ Phase: investigating
+→ Severity: S2 (user-visible checkout failure)
+
+[Diagnoser output: connection pool exhausted after migration 042]
+
+→ Phase transition: investigating → remediating
+→ Risky actions proposed: 2
+
+  1. Scale deployment api 3→6 replicas (risky)
+  2. Disable flag new_checkout_flow (risky)
+
+[Gate approval required for each step]
+```
+
+## Phase Transition Diagram
+
+```
+                   ┌──────────────────────────────────────────────────────┐
+                   │                                                       │
+                   ▼                                                       │
+            ┌───────────────┐                                              │
+            │ investigating │                                              │
+            └───────┬───────┘                                              │
+                    │                                                      │
+       diagnoser produces                                                  │
+       nextActions with                                                    │
+       ≥1 risky                                                            │
+                    │                                                      │
+                    ▼                                                      │
+            ┌───────────────┐                                              │
+            │  remediating  │                                              │
+            └───────┬───────┘                                              │
+                    │                                                      │
+       all proposed actions executed                                       │
+       + postcondition passed                                              │
+                    │                                                      │
+                    ▼                                                      │
+            ┌───────────────┐ ──── verifyResolution fails ─────────────────┤
+            │   monitoring  │                                              │
+            └───────┬───────┘                                              │
+                    │                                                      │
+       verifyResolution.verified=true                                      │
+       for criteria.windowMinutes                                          │
+                    │                                                      │
+                    ▼                                                      │
+            ┌───────────────┐ ──── user re-opens (reason REQUIRED) ────────┘
+            │    resolved   │
+            └───────────────┘   (auto-postmortem triggered by setIncidentStatus)
+
+At any phase: user issues `bober incident abort <id> --reason <text> [--confirm-rollback]`
+              ──────────────────────────────────────► aborted (terminal)
+```
+
+State machine constraints enforced by `transitionPhase()` in `src/incident/orchestrator.ts`:
+- `aborted` is **terminal**: no transitions out.
+- `resolved → remediating` is **forbidden** (must re-open to `investigating` first).
+- `resolved → investigating` requires an explicit `reason` (re-open path).
+- All other transitions follow the table exactly; invalid transitions throw `InvalidTransitionError`.
+
+## Red Flags - STOP and Follow Process
+
+Encountering any of these signals means the incident is being handled incorrectly. STOP the current action and follow the documented path.
+
+- **About to mark resolved without a verifyResult or overrideToken.** Resolution without evidence is conjecture. Use `--verified` or `--override <reason>` — never skip the gate.
+- **About to execute a rollback without `--confirm-rollback`.** Silent rollback is a footgun. Rollback changes system state; it must be explicit. If you want rollback, use `bober incident abort <id> --reason <text> --confirm-rollback`.
+- **About to run a risky action directly in the shell, bypassing `executeAction`.** Any command that modifies system state MUST go through the deploy gate so an inverse is recorded. No exceptions for "trivial" changes.
+- **About to batch-approve multiple risky actions in a single gate invocation.** Each risky action requires its own checkpoint approval. Per-step gates exist to prevent "approve all" disasters.
+- **About to close an incident without a timeline event.** Every phase transition and every action MUST be recorded in `timeline.jsonl`. Closing an incident with an empty timeline means the postmortem will have no evidence to synthesize.
+- **About to re-open a resolved incident without a reason.** The re-open path (`resolved → investigating`) requires an explicit reason. A reason-less re-open erases the audit trail of why the incident was re-opened.
+- **About to skip the diagnoser and go straight to remediation.** "I know what's wrong" is the most dangerous statement in incident response. Run the diagnoser first to document hypotheses.
+
+## Common Rationalizations
+
+| Rationalization | Why It's Wrong |
+|----------------|---------------|
+| "I know what's wrong — skipping diagnosis to save time." | Without documented hypotheses, the postmortem will have no root cause. Skipping diagnosis means you cannot verify the fix addressed the actual cause. |
+| "The metric is unavailable but I know it's resolved." | Use `--override <reason>` with a documented reason. This creates an audit trail. Do NOT skip the gate entirely — the `resolved` gate exists to prevent wishful resolution. |
+| "It's a tiny change — the gate is overkill." | The gate's cost is one approval. The cost of an ungated risky change to production is a potential second incident. Classify risky when in doubt. |
+| "The rollback will fix the abort side-effects automatically." | Rollback must be explicitly confirmed with `--confirm-rollback`. Silent rollback could make the situation worse. Document the abort reason first; then decide on rollback separately. |
+| "I'll write the postmortem later when I have more time." | The postmortem auto-triggers on `resolved`. If you are deferring it, you are either not marking the incident resolved or suppressing auto-generation. Both are process violations. |
+| "We don't need a severity — it's obvious." | Severity is metadata that feeds into postmortem priority, SLO budgets, and escalation decisions. Set it at `bober incident start` so downstream tooling can use it. |
+
+## Quick Reference
+
+| Question | Answer |
+|---------|--------|
+| How do I start a Severity 1 incident? | `bober incident start "<symptom>" --severity S1` |
+| How do I check the current phase? | `bober incident status <id>` |
+| How do I end an incident after external verification? | `bober incident end <id> --verified` |
+| How do I end an incident when no metric is available? | `bober incident end <id> --override "reason here"` |
+| How do I abort without rolling back? | `bober incident abort <id> --reason "<text>"` |
+| How do I abort AND roll back? | `bober incident abort <id> --reason "<text>" --confirm-rollback` |
+| How do I re-open a resolved incident? | `bober incident start "<symptom>"` (new incident) OR `transitionPhase(..., 'investigating', { reason })` programmatically |
+| Where are the artifacts? | `.bober/incidents/<incidentId>/` |
+| What gates a risky action? | `resolveRiskyActionMechanismName()` → disk/cli/pr/noop per `bober.config.json` |
+| When is the postmortem generated? | Automatically when `setIncidentStatus(_, _, 'resolved', ...)` is called |
+
+## Related Skills
+
+| Skill | Use when |
+|-------|---------|
+| [`bober.diagnose`](../bober.diagnose/SKILL.md) | Running the 4-phase root-cause investigation. Invoked by `/bober-incident` after `start`. |
+| [`bober.deploy`](../bober.deploy/SKILL.md) | Executing a remediation action with gate discipline. Invoked for each risky nextAction. |
+| [`bober.runbook`](../bober.runbook/SKILL.md) | Executing a known remediation procedure step-by-step. Runbook steps delegate to `bober.deploy` for risky steps. |
+| [`bober.postmortem`](../bober.postmortem/SKILL.md) | Synthesizing the incident postmortem after resolution. Auto-triggered; also available manually via `bober postmortem generate <id>`. |

package/skills/bober.onboard/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bober.onboard
+description: Generate onboarding documentation from the code graph — architecture overview, hotspots, knowledge gaps, and communities. Writes 5 markdown files to .bober/onboarding/.
+handoffs:
+  - label: "Analyse Impact"
+    command: /bober-impact
+    prompt: "Analyse the impact radius of a hotspot symbol"
+  - label: "Plan Feature"
+    command: /bober-plan
+    prompt: "Plan a feature using onboarding context"
+---
+
+# bober.onboard — Onboarding Documentation Skill
+
+You are running the **bober.onboard** skill. Your job is to generate a complete set of onboarding documents for this codebase using the code graph.
+
+## What This Skill Produces
+
+Five markdown files in `.bober/onboarding/`:
+
+1. **README.md** — entry point with links to all other documents
+2. **architecture-overview.md** — public API per module, sorted alphabetically
+3. **hotspots.md** — high-complexity symbols worth reviewing (table with score + reason)
+4. **knowledge-gaps.md** — potentially unused (dead code) + public APIs without internal callers
+5. **communities.md** — module groupings by community
+
+## Prerequisites
+
+- `graph.enabled: true` in `bober.config.json`
+- `tokensave` >= 6.0.0-beta.1 installed
+- Graph must be initialised (`agent-bober graph init`)
+
+## Running via CLI
+
+```bash
+agent-bober onboard
+```
+
+This command:
+1. Starts a short-lived tokensave engine
+2. Queries the graph for status, hotspots, dead code, circular deps, module APIs, and file inventory
+3. Passes results to the OnboardingComposer renderer
+4. Writes all 5 files to `.bober/onboarding/`
+5. Prints a summary table with file paths and sizes
+
+Expected output:
+```
+Starting graph engine...
+Querying code graph...
+Writing artifacts to .bober/onboarding/...
+
+Onboarding artifacts written:
+
+  .bober/onboarding/README.md                     <size> bytes
+  .bober/onboarding/architecture-overview.md      <size> bytes
+  .bober/onboarding/hotspots.md                   <size> bytes
+  .bober/onboarding/knowledge-gaps.md             <size> bytes
+  .bober/onboarding/communities.md                <size> bytes
+
+5 files written (<total> bytes total)
+```
+
+## Running via MCP Tools (Alternative)
+
+You can also produce equivalent onboarding content directly using the MCP tools:
+
+1. Get architecture overview: `get_architecture_overview`
+2. Find hotspots: `semantic_search_nodes` with query `"hotspots high complexity"`
+3. Find dead code: `semantic_search_nodes` with query `"dead code unused symbols"`
+4. Find communities: `list_communities` (if available) or `get_architecture_overview`
+
+Format the results using the same structure as the generated documents and write to `.bober/onboarding/`.
+
+## Re-running
+
+The command is safe to re-run. Files with the generation marker are updated in-place (preserving any content you wrote above the marker). Files without the marker are refused to prevent overwriting manual edits.
+
+To force a fresh generation, delete the files in `.bober/onboarding/` and re-run.
+
+## Error Handling
+
+- If graph.enabled=false: exits 1 with instructions to enable it
+- If tokensave missing: exits 1 with install hint
+- If a file lacks the generation marker: exits with an error explaining which file needs attention

package/skills/bober.plan/SKILL.md

@@ -152,6 +152,16 @@ After receiving the user's answers, generate a complete PlanSpec. Follow the sch
 7. **Non-functional requirements:** Performance, security, accessibility, reliability considerations
 8. **Tech notes:** Integration points, data model overview, security considerations
 
+<HARD-GATE>
+Do NOT write any .bober/contracts/*.json file until one of the following has happened:
+
+1. INTERACTIVE protocol — the user has explicitly approved the assumptions and outOfScope sections above. Record approval as a resolvedClarifications entry with questionId='gate-design-approval' and the user's verbatim approval in the answer field.
+
+2. AUTONOMOUS protocol — every assumption in the spec is backed by cited evidence (minimum: a file path; preferred: file:line). Record self-approval as resolvedClarifications entry with questionId='gate-design-approval', answer='Autonomous self-approval', resolvedBy='planner', and metadata.approvalEvidence field listing the cited file paths.
+
+Violating this gate produces orphan contracts that diverge from the spec. Discovered violations result in contracts being deleted and spec status reverted to 'needs-clarification'.
+</HARD-GATE>
+
 ## Step 6: Decompose into Sprint Contracts
 
 Decompose the PlanSpec into ordered sprints. This is the most critical step.

package/skills/bober.postmortem/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: bober-postmortem
+description: Use after an incident is resolved to synthesize an evidence-cited postmortem from .bober/incidents/<id>/ artifacts — chronological timeline, 5-Whys from diagnoses, contributing factors from runbook execution, action items from gaps in process. Pure offline synthesis; no live observability access.
+---
+
+# Postmortem Synthesis Discipline
+
+## Overview
+
+A postmortem is a document of record. It is read by people who weren't in the room — sometimes months later, sometimes by auditors. Postmortems that contain opinion without evidence become political artifacts; postmortems that cite every claim become institutional memory.
+
+**Core principle:** Every postmortem sentence traces to a specific artifact in `.bober/incidents/<id>/`. Citations are mandatory. Speculation is forbidden.
+
+**Violating the letter of this discipline is violating the spirit of incident learning.**
+
+## The Iron Law
+
+```
+NO POSTMORTEM SECTION WITHOUT EVIDENCE FROM INCIDENT ARTIFACTS
+```
+
+Every non-template claim cites an artifact path (and line number where applicable). A section with no citations is a section that should not exist — or a section whose contents were fabricated. Either way: failure.
+
+## When to Use
+
+Use this skill when:
+- An incident transitions to `status: 'resolved'` (Sprint 22 gate)
+- A human runs `bober postmortem generate <incidentId>` to (re)synthesize a postmortem
+- An auditor needs to reconstruct the incident from artifact records
+
+Do NOT use this skill for:
+- Active incident response (use `bober.diagnose`)
+- Remediation execution (use `bober.deploy`)
+- Runbook authoring (use `bober.runbook`)
+
+## Synthesis Order
+
+Read the following artifacts in EXACTLY this order. Earlier files seed later sections.
+
+1. **`incident.json`** — metadata: incidentId, symptom, createdAt, resolvedAt, status, resolutionCriteria, resolutionEvidence. The header block of the postmortem comes entirely from this file.
+2. **`timeline.jsonl`** — chronological master log. Walk linearly to construct the Timeline table. Each row carries `(timeline.jsonl#L<n>)` as its citation.
+3. **`observations.jsonl`** — verified facts. `phase: 1-2 + verified: true` rows seed the Impact section. `phase: 4` rows confirm Resolution.
+4. **`diagnoses/*.json`** — DiagnosisResult records (Sprint 15 schema). Sort by mtime descending; the most-recent diagnosis's highest-confidence hypothesis is the root-cause candidate for Why-2.
+5. **`changelog.jsonl`** — ChangeEntry records (with required inverse field, Sprint 21). Each entry within 30 minutes before incident `createdAt` is a Why-4/Why-5 candidate.
+6. **`runbook-execution.jsonl`** — RunbookExecutionEntry records. Failed steps populate Contributing Factors; successful steps populate What Went Well.
+7. **`actions.jsonl`** — ActionEntry records (safe + risky). Risky actions without preceding precondition pass become What Went Wrong entries.
+8. **`resolution-evidence/*.json`** — Sprint 22 metric verification samples. `allSamplesPassed: true` is the strongest possible Resolution citation.
+9. **`hypotheses.md`** — narrative. Lines starting "Disproved:" go to What Went Well; lines starting "Open:" go to Action Items.
+
+Missing or empty artifacts are NOT failures of the synthesizer — they are facts about the incident. Cite the absence: `(diagnoses/ is empty)`.
+
+## 5-Whys Construction Heuristic
+
+The 5-Whys section is the hardest part. The diagnoser's top hypothesis is usually Why-2 or Why-3, not Why-1. The synthesizer works backwards (symptom → root) AND forwards (changelog → symptom) to fill all five levels.
+
+**Heuristic (deterministic; pseudocode for implementers):**
+
+```
+why1 = "Why did <incident.symptom> happen?"
+  citation = "(incident.json)"
+
+let diagnosis = mostRecentDiagnosis(diagnoses/)
+let topHypothesis = diagnosis.hypotheses.sortBy(confidence: desc, supportingEvidence.length: desc)[0]
+why2 = "Because " + topHypothesis.statement
+  citation = "(diagnoses/<diagnosisId>.json#" + topHypothesis.id + ")"
+
+let strongestEvidence = topHypothesis.supportingEvidence.sortBy(specificity)[0]
+why3 = "Because " + strongestEvidence.snippet
+  citation = "(" + strongestEvidence.path + ")"
+
+let preIncidentChanges = changelog.jsonl.filter(c =>
+  c.executedAt < incident.createdAt &&
+  Date.parse(incident.createdAt) - Date.parse(c.executedAt) < 30 * 60 * 1000
+).sortBy(executedAt: desc)
+why4 = preIncidentChanges[0]
+  ? "Because " + preIncidentChanges[0].description + " shipped " + minutesBetween + "m before symptom onset"
+  : null
+  citation = "(changelog.jsonl#L<n>)"
+
+why5 = preIncidentChanges[1]
+  ? similar to why4 with the next-older change
+  : null
+
+if (renderedWhys.length < 3) {
+  emitShallowWarning("5-Whys synthesis was shallow (only " + n + " level(s) derivable from artifacts). " +
+                     "Missing evidence in <named-file>. Human review required to deepen this chain.")
+}
+```
+
+**Cite every level.** A 5-Whys section with 5 levels and 5 citations is the bar. 3 levels with citations + a shallow-warning is acceptable. Fewer than 3 with no warning is a synthesis failure.
+
+## Postmortem Template
+
+Generated postmortems MUST match this structure. Section headings are template; everything else MUST cite.
+
+```markdown
+# Postmortem: <incident.symptom truncated 80 chars>
+
+**Incident ID:** <incidentId> (incident.json)
+**Status:** Resolved
+**Severity:** <S1|S2|S3|S4>  *(derive from observation count + impact magnitude; default S3 if undeterminable)*
+**Date:** <incident.createdAt> → <incident.resolvedAt> (incident.json)
+**Duration:** <hh:mm computed from createdAt → resolvedAt>
+
+## TL;DR
+
+<2-3 sentence summary: symptom from `incident.json.symptom` + root cause from top hypothesis + resolving action from changelog.jsonl last ChangeEntry.> Each clause carries an inline citation.
+
+## Impact
+
+- <verified observation 1> (observations.jsonl#L<n>)
+- <verified observation 2> (observations.jsonl#L<n>)
+- Resolution sample: observed <resolution-evidence[*].observedValue> against threshold <criteria.threshold> (resolution-evidence/<file>.json)
+
+## Timeline
+
+| Time (UTC) | Event | Source |
+|------------|-------|--------|
+| <hh:mm> | <event.summary truncated 80> | <event.source> (timeline.jsonl#L<n>) |
+| <hh:mm> | … | … |
+
+## Root Cause (5-Whys)
+
+1. Why did <symptom> happen? (incident.json)
+2. Because <topHypothesis.statement>. (diagnoses/<diagnosisId>.json#<hyp-id>)
+3. Because <strongestEvidence.snippet>. (<evidence.path>)
+4. Because <preIncidentChange.description> shipped <m>m prior. (changelog.jsonl#L<n>)
+5. Because <olderPreIncidentChange.description>. (changelog.jsonl#L<n>)
+
+*(If fewer than 3 Whys derivable: emit the shallow-warning paragraph below the partial chain.)*
+
+## Contributing Factors
+
+- <runbook step failure 1>: <stepDescription> (runbook-execution.jsonl#L<n>)
+- <unverified observation that nevertheless steered the response>: (observations.jsonl#L<n>)
+
+## What Went Well
+
+- <successful runbook step or disproved hypothesis> (runbook-execution.jsonl#L<n>) or (hypotheses.md#L<n>)
+- Resolution metric verified: <criteria.metricName> < <threshold> for <windowMinutes>m sustained (resolution-evidence/<file>.json)
+
+## What Went Wrong
+
+- <runbook execution failure> (runbook-execution.jsonl#L<n>)
+- <risky action without precondition pass> (actions.jsonl#L<n>)
+
+## Action Items
+
+| Item | Owner | Due | Source |
+|------|-------|-----|--------|
+| <derived from a What Went Wrong row> | TBD | TBD | (<artifact>#L<n>) |
+| Add monitoring for the root-cause signal (5-Whys Level 3) | TBD | TBD | (5-whys-3) |
+
+---
+*<Redactions footer if applicable: "**Redactions:** N secret-like strings redacted from artifacts.">*
+*Generated by `bober postmortem generate <incidentId>` (Sprint 23).*
+```
+
+## Citation Format
+
+Citations are parenthesized inline references at the end of a sentence:
+
+| Style | When to use | Example |
+|-------|------------|---------|
+| `(file)` | Single-record JSON files | `(incident.json)` |
+| `(file#L<n>)` | JSONL files where line maps to record | `(timeline.jsonl#L7)` |
+| `(file#<event-id>)` | Records with explicit ids | `(diagnoses/diagnosis-inc-x-2026-05-24T14:30:00Z.json#h1)` |
+| `(file1#L<n>, file2#L<m>)` | Multi-source corroboration in one claim | `(observations.jsonl#L3, changelog.jsonl#L1)` |
+
+Every Impact bullet, every Timeline row, every 5-Whys level, every Action Item — all cite. The synthesizer enforces a minimum-5-citation floor; below that, it emits a synthesis-failure warning.
+
+## Redaction Discipline
+
+Postmortems are widely shared. Apply these regexes to EVERY quoted artifact snippet BEFORE composing the markdown:
+
+```regex
+/AKIA[0-9A-Z]{16}/g
+/aws_secret_access_key\s*[=:]\s*\S+/gi
+/(?:Bearer|Token|token|apikey|api_key|api-key)[\s=:]+["']?[A-Za-z0-9._\-]{16,}["']?/gi
+/sk-[A-Za-z0-9]{20,}/g
+/sk_(?:live|test)_[A-Za-z0-9]{10,}/g
+/ghp_[A-Za-z0-9]{20,}/g
+/secret_[A-Za-z0-9_\-]+/gi
+/password\s*[=:]\s*\S+/gi
+/Authorization:\s*Bearer\s+\S+/gi
+/-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]+?-----END [A-Z ]+PRIVATE KEY-----/g
+```
+
+Replace each match with `[REDACTED]`. Increment a counter. If counter > 0, append the footer "**Redactions:** <N> secret-like strings redacted from artifacts." The redaction patterns themselves are listed here in SKILL.md as the canonical reference — they must NOT be quoted differently by the implementation. The implementing TypeScript module (`src/incident/postmortem.ts`) must use these exact regexes.
+
+## Red Flags - STOP
+
+- A postmortem with fewer than 5 inline citations
+- A 5-Whys section with fewer than 3 levels and NO shallow-warning paragraph
+- An Impact section that lists symptoms not present in observations.jsonl
+- A Timeline row whose timestamp does not appear in timeline.jsonl
+- A quoted artifact snippet containing what looks like an API key, token, or password
+- "Action Items: None" — there is always at least the monitoring action item
+- Section headings present but section bodies empty — empty sections must be explicit ("No <X> recorded for this incident — (artifact is empty).")
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll skip the line number, the file is short" | Line numbers are how auditors reproduce the synthesis. Always include them for JSONL artifacts. |
+| "The 5-Whys narrative reads better if I fill in Why-4 from intuition" | Intuition is fabrication. Either derive Why-4 from changelog.jsonl or stop at Why-3 with the shallow-warning. |
+| "Generic 'TBD' owners are fine for Action Items, they're not actionable anyway" | Owner: TBD is explicit and acceptable. "Owner: the team" or "Owner: someone" is generic prose disguised as data. |
+| "The secret is in a closed system, no redaction needed" | Redact ALL secret-pattern matches unconditionally. Closed today is open tomorrow. |
+| "There were no contributing factors, the response was clean" | Every incident has factors visible in runbook-execution.jsonl or hypotheses.md. An empty section is failure. |
+| "I'll add one citation per section to satisfy the floor" | Per-sentence citations, not per-section. The floor is 5 INLINE citations across the document. |
+
+## Quick Reference
+
+| Section | Source | Citation format |
+|---------|--------|-----------------|
+| Header (ID/Status/Severity/Date/Duration) | `incident.json` | `(incident.json)` |
+| TL;DR | symptom + top hypothesis + last change | 2-3 citations inline |
+| Impact | `observations.jsonl` (`verified: true`) + `resolution-evidence/` | `(observations.jsonl#L<n>)` |
+| Timeline | `timeline.jsonl` (every row) | `(timeline.jsonl#L<n>)` per row |
+| Root Cause | `diagnoses/*.json` + `changelog.jsonl` | per-Why citation |
+| Contributing Factors | `runbook-execution.jsonl` (failed steps) | `(runbook-execution.jsonl#L<n>)` |
+| What Went Well | successful runbook + disproved hypotheses + verified resolution | mixed |
+| What Went Wrong | failed runbook + risky actions without precondition | mixed |
+| Action Items | derived from What Went Wrong + monitoring | one citation per row |
+
+## Related Skills
+
+- **`bober.diagnose`** — Phase 4 resolution-criteria verification produces `resolution-evidence/*.json` that this skill's Impact and What-Went-Well sections cite.
+- **`bober.deploy`** — every ChangeEntry in `changelog.jsonl` was written under bober.deploy with a required inverse. The postmortem cites these for Root Cause (Why-4/Why-5) and as Action Item source rows.
+- **`bober.runbook`** — every `runbook-execution.jsonl` entry was written under bober.runbook; failed steps populate Contributing Factors.
+- **`agents/bober-postmortemer.md`** — the (offline, read-only) agent prompt companion to this skill. The TypeScript implementation in `src/incident/postmortem.ts` synthesizes deterministically; the agent prompt documents the discipline that any human or future LLM author must follow.