@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/skills-codex/mitigate-incident/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: wr-itil:mitigate-incident
+description: Record a mitigation attempt against an incident — transitions an investigating incident to mitigating on the first attempt, appends subsequent attempts to the Mitigation attempts timeline. Evidence-first gate enforced per the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input, Skill
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Mitigate Incident
+
+Record a mitigation attempt against an active incident and transition its lifecycle. The first mitigation attempt moves the file from `.investigating.md` to `.mitigating.md`; subsequent attempts append to the existing `.mitigating.md` without re-transitioning. Every attempt (successful or not) is recorded so the post-incident audit trail is complete (the "Restore Service Fast with an Audit Trail" user outcome).
+
+This skill is the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem phased-landing split of `/wr-itil:manage-incident <I> mitigate <action>` per the "Rename `wr-problem` Plugin to `wr-itil`" architecture rule amended Skill Granularity rule: one skill per distinct user intent. The arguments `<I>` (incident ID) and `<action>` (mitigation description) are data parameters, permitted under the amendment — only word-verb-arguments must be split out. The original `/wr-itil:manage-incident <I> mitigate <action>` subcommand route remains as a thin-router forwarder during the deprecation window but is scheduled for removal in `@windyroad/itil`'s next major version.
+
+## Arguments
+
+`/wr-itil:mitigate-incident <I###> <action>` — both positional:
+
+- `<I###>` — the incident ID (e.g. `I007` or bare `007`). Resolves to `docs/incidents/<I###>-*.{investigating,mitigating}.md`.
+- `<action>` — free-text description of the mitigation being applied (e.g. `rollback checkout service to 1.2.4`, `feature flag checkout.fast-path off`, `restart ingest worker pool`). Prefer **reversible** actions — see "Reversible preference" below.
+
+If `$ARGUMENTS` is empty or malformed, fail-fast with a usage message and exit (per the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule Framework-Mediated Surface; matches the `transition-problem` / `work-problem` precedent). Argument malformation is a typo-class signal, not a decision — the slash command is the input contract; re-typing is faster than a multi-turn `request_user_input` dialogue, and the user-memory direction `feedback_act_on_obvious_decisions.md` pins this. The exact usage block is in Step 1.
+
+## Reversible preference (the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule)
+
+Prefer **reversible** mitigations over forward fixes:
+
+1. Rollback to a known-good version
+2. Feature flag off
+3. Restart / cycle the affected component
+4. Route traffic away
+5. Scale up
+6. Only after reversibles are exhausted: forward fix
+
+Record every attempt, successful or not. Failed mitigations are as important to the audit trail as successful ones — they narrow hypothesis space for future investigation.
+
+**Mitigation SELECTION is agent-owned — do NOT defer "which mitigation" to the user (the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule framework-mediated surface; category-4 silent-framework family).** Choosing *which* mitigation to attempt — traversing the reversible-preference ladder above, backed by cited evidence, within risk appetite — is the agent's call. The framework has already resolved it: the ladder IS the selection mechanism, the evidence-first gate (below) is the quality bar, and RISK-POLICY appetite is the bound. Do NOT surface "which mitigation should I attempt?" as a user-authority decision via `request_user_input` **or** a prose-ask ("I'll wait for your direction on which mitigation to attempt", "let me know which option you'd prefer"). That deferral re-asks a decision the framework mediated and adds latency to the very job this skill exists to accelerate. Authority: the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 5 (policy-authorised silent proceed for within-appetite reversible actions); the "Restore Service Fast with an Audit Trail" user outcome ("Reversible mitigations [...] are preferred"); user direction 2026-05-10 — *"mitigations don't belong to me. You are empowered."* (the "Agent defers mitigation selection to user during active incident — surfaces mitigation choice as user-authority when SKILL contract empowers agent-driven reversible mitigations" problem). The genuine user-authority surfaces are unchanged and remain interactive: the evidence-first gate bypass (the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule category-2 deviation-approval, Step 3) and the risk-above-appetite commit (category-3 one-time-override, Step 8). Select-and-act; the audit trail (every attempt recorded) is the oversight surface, not a pre-action consent gate.
+
+## Evidence-first gate (the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule; the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule category-2 deviation-approval)
+
+**Pre-flight check before the first mitigation attempt**: the incident file must contain at least one hypothesis with cited evidence in the `## Hypotheses` section. If not, block the transition and ask via `request_user_input`. This is the **the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule category-2 (deviation-approval)** surface: the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule's evidence-first rule is the existing decision; "Record anyway" is the user-approved deviation in this specific case (the rule isn't being amended; this case is being excepted with audit trail). The user IS the right authority for the bypass shape.
+
+The 3-option prompt:
+
+> "Incident `<I###>` has no hypothesis with cited evidence. Per the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule, mitigation requires at least one ranked hypothesis backed by a log, repro, diff, or metric reference. (a) Add a hypothesis + evidence now and retry, (b) Record the mitigation anyway with an evidence-skipped justification (requires audit-trail note), (c) Cancel."
+
+This gate is the **cool-headed commitment**: it blocks "try this and see" actions during the high-adrenaline phase of an incident unless evidence is cited. The gate runs only on the first mitigation (the `.investigating.md → .mitigating.md` transition); subsequent mitigations on an already-`.mitigating.md` file append directly without re-gating.
+
+## Steps
+
+### 1. Parse arguments (fail-fast on typos — the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule Surface 1)
+
+Extract `<I###>` and `<action>` from `$ARGUMENTS`. Normalise `<I###>`:
+
+- Accept `I007`, `i007`, `007`, `7` → canonicalise to `I007` (uppercase I + zero-padded 3 digits).
+- If missing, malformed, or unrecognisable, emit the usage block below and exit. **Do not** fire `request_user_input` for argument backfill — argument shape is a typo-class signal, not a decision. The framework-mediated answer per the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule is fail-fast + exit; the user re-types in 1 second. Matches the `transition-problem` Step 1 + `work-problem` singular precedent for consistency across the suite (the "Extend the Suite with New Plugins" user outcome — clear patterns).
+
+Extract `<action>` as everything after the incident ID. If missing or trivially short (< 8 chars), apply the same fail-fast pattern: emit the usage block below and exit; the user re-invokes with a complete action.
+
+**Usage block** (emitted on any malformed-argument case; copy verbatim so adopters get a consistent shape):
+
+```
+Usage: /wr-itil:mitigate-incident <I###> <action>
+  <I###>    — incident ID (e.g. I007 or bare 007); must resolve to docs/incidents/<I###>-*.{investigating,mitigating}.md
+  <action>  — descriptive mitigation (8+ chars), e.g. "rollback checkout service to 1.2.4", "feature flag checkout.fast-path off", "restart ingest worker pool"
+
+Prefer reversible mitigations (see "Reversible preference" in this skill). Run /wr-itil:list-incidents to see active incidents if you don't know the ID.
+```
+
+### 2. Locate the incident file
+
+```bash
+ls docs/incidents/<I###>-*.investigating.md docs/incidents/<I###>-*.mitigating.md 2>/dev/null
+```
+
+- If neither exists, report "No active incident `<I###>` found. Check `/wr-itil:list-incidents` for the active backlog or `/wr-itil:manage-incident` to declare a new one." and exit.
+- If exactly one file matches, record its current suffix (`investigating` or `mitigating`) — this drives the transition decision in Step 4.
+- If multiple files match (should not happen under the `<ID>-<title>.<status>.md` naming convention), report the ambiguity and exit.
+
+### 3. Pre-flight: evidence gate (first mitigation only) — the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule category-2 deviation-approval
+
+If the file suffix is `.investigating.md` (i.e. this is the first mitigation), read the `## Hypotheses` section and check for at least one line containing `Evidence:` followed by a non-empty reference. The shape per the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule:
+
+```
+- [ranked] <hypothesis> — Evidence: <log/repro/diff/metric reference>. Confidence: <low|med|high>.
+```
+
+- If at least one hypothesis has a cited evidence reference, proceed to Step 4.
+- If no hypothesis carries evidence, invoke `request_user_input` with the three-option prompt from "Evidence-first gate" above. This is the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule **category-2 (deviation-approval)** surface — the user is the right authority for the bypass; the gate's behaviour is preserved verbatim post-the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule because deviation-approval is a kept-request_user_input category in the 6-class taxonomy. Branch:
+  - (a) User adds a hypothesis + evidence now — re-read the file and re-check; if satisfied, proceed. If still missing, report the gate failure and exit.
+  - (b) User records anyway (deviation approved) — append an `## Audit trail` note to the file: `[<timestamp> UTC] Evidence-gate bypassed by user — reason: <justification>`. Then proceed to Step 4.
+  - (c) User cancels — exit without change.
+
+If the file suffix is already `.mitigating.md`, skip the gate (it only runs on the transition).
+
+### 4. Record the mitigation and transition if needed
+
+Compute a UTC timestamp (e.g. `2026-04-21T14:37Z`). Then:
+
+**Case A — first mitigation (`.investigating.md` → `.mitigating.md`)**:
+
+1. `git mv docs/incidents/<I###>-<title>.investigating.md docs/incidents/<I###>-<title>.mitigating.md`
+2. Update the `**Status**:` field from `Investigating` to `Mitigating` via `Edit`.
+3. Append to the `## Mitigation attempts` section:
+
+   ```markdown
+   - [<timestamp> UTC] <action> → pending verification
+   ```
+
+   If the `## Mitigation attempts` section contains `*(none yet)*`, replace that placeholder with the first attempt row. Otherwise append below the last attempt.
+
+4. Append to the `## Timeline` section:
+
+   ```markdown
+   - [<timestamp> UTC] Mitigation attempt: <action>
+   ```
+
+**Case B — subsequent mitigation (`.mitigating.md` stays `.mitigating.md`)**:
+
+1. No `git mv` needed.
+2. Do not touch the `**Status**:` field.
+3. Append to the `## Mitigation attempts` section:
+
+   ```markdown
+   - [<timestamp> UTC] <action> → pending verification
+   ```
+
+4. Append to the `## Timeline` section:
+
+   ```markdown
+   - [<timestamp> UTC] Mitigation attempt: <action>
+   ```
+
+The outcome text starts at `pending verification` because verification signals (error-rate recovery, synthetic-probe passing, user report) usually arrive after the mitigation. The `/wr-itil:manage-incident <I###> restored` flow updates the outcome to the final verification signal when service is restored. Failed mitigations should be updated in place (via a subsequent `/wr-itil:manage-incident <I###>` update call or a future `/wr-itil:mitigate-incident` re-record) with the observed outcome — do not delete the original row.
+
+### 5. Low-severity lightweight path (the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule Step 12 edge case)
+
+For **Sev 4-5** incidents, the Hypotheses section may be skipped if the user confirmed no investigation was needed at declare time. In that case:
+
+- The evidence-first gate in Step 3 does not apply (there are no hypotheses to check).
+- The Mitigation attempts append in Step 4 remains mandatory — Timeline, Observations, and at least one mitigation attempt are always required per the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule.
+- Do not upgrade a skipped-hypotheses incident's severity silently; if the user decides mid-incident that investigation IS needed, they should update the incident via `/wr-itil:manage-incident <I###>` and add the hypothesis explicitly.
+
+Detect "lightweight path" by reading the Severity label from the incident frontmatter: if Impact × Likelihood resolves to Sev 4 or Sev 5, the gate defaults to bypass with an audit-trail note unless the user has populated Hypotheses explicitly.
+
+### 6. Quality checks
+
+After any mitigation record, verify:
+
+- **Status consistency**: `**Status**:` field matches the filename suffix (Investigating + `.investigating.md` OR Mitigating + `.mitigating.md`).
+- **Timeline monotonicity**: the new timeline entry's timestamp is ≥ the last existing timeline entry's timestamp.
+- **Mitigation attempts section exists**: if somehow missing from an older incident file, create it before appending.
+- **No evidence-gate silent bypass**: if the gate was bypassed in Step 3, the `## Audit trail` note must be present.
+
+### 7. Report
+
+Report:
+
+- The file path created/modified.
+- The incident ID and title.
+- The transition (Investigating → Mitigating, or Mitigating → Mitigating).
+- The recorded action and the `pending verification` outcome.
+- Any quality-check warnings.
+- A pointer: "Run `/wr-itil:manage-incident <I###> restored` when the verification signal confirms service is restored, or re-invoke `/wr-itil:mitigate-incident <I###> <next-action>` to record another mitigation attempt."
+
+### 8. Commit the completed work (the "Governance Skills Commit Their Own Completed Work" architecture rule; risk-above-appetite is the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule category-3 one-time-override)
+
+Per the "Governance Skills Commit Their Own Completed Work" architecture rule, governance skills commit their own work.
+
+1. `git add` the renamed / modified incident file.
+2. Delegate to `wr-risk-scorer:pipeline` (subagent_type: `wr-risk-scorer:pipeline`) to assess the staged changes and create a bypass marker. If the subagent type is not available (spawned subagent surface), invoke `/wr-risk-scorer:assess-release` via the installed skill invocation instead — per the "On-Demand Assessment Skills for Governance Plugins" architecture rule it wraps the same pipeline subagent.
+3. `git commit -m "docs(incidents): I<NNN> mitigated — <action summary>"`.
+4. If commit risk is above appetite: this is **framework-mediated, NOT a category-3 one-time-override ask** (the "Skills, agents, and hooks override RISK-POLICY appetite instead of applying it" problem/the ": Apply RISK-POLICY appetite faithfully across all surfaces" release design — no incident carve-out). Per **the "Auto-apply scorer remediations to reach within appetite — open action-class vocabulary" architecture rule Rule 1b (incident-context scoring)**: an active incident is a risk being realised (Likelihood already 5); score the mitigation against that live realised-risk baseline — P(increases impact) vs P(reduces impact & likelihood / restores service) + P(introduces a new incident). Net risk-reducing → it takes the risk-reducing path (`RISK_BYPASS: reducing`) and proceeds, no ask — exactly the restore-service-fast (the "Restore Service Fast with an Audit Trail" user outcome) case, cleared via scoring not a consent gate. Not net-reducing → auto-remediate (the "Auto-apply scorer remediations to reach within appetite — open action-class vocabulary" architecture rule Rule 1) or halt (Rule 5). **MUST NOT commit above appetite; MUST NOT `request_user_input` "commit anyway".** If `request_user_input` is unavailable, the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6 fail-safe — skip + report.
+
+### 9. Auto-release when changesets are queued (the "Governance skills auto-release when changesets are queued" architecture rule)
+
+**Skip this step if the skill is running inside an AFK orchestrator.** Orchestrators handle release cadence themselves per the "Inter-iteration release cadence for AFK loops" architecture rule (Step 6.5). When in doubt, defer to the orchestrator by skipping this step.
+
+Otherwise, after the commit in step 8 lands, drain the release queue so the fix actually lands on npm without requiring manual user action.
+
+**Mechanism — delegate, do not re-implement scoring (per the "On-Demand Assessment Skills for Governance Plugins" architecture rule):**
+
+1. Invoke the release scorer. Two paths are valid:
+   - **Primary**: delegate to subagent type `wr-risk-scorer:pipeline` via the native Codex subagent tool.
+   - **Fallback**: if that subagent type is not available, invoke skill `/wr-risk-scorer:assess-release` via the installed skill invocation.
+2. Read the returned `RISK_SCORES: commit=X push=Y release=Z` line.
+3. **Drain condition**: if `push` and `release` are both within appetite (≤ 4/25, "Low" band per `RISK-POLICY.md`), AND `.changeset/` is non-empty, proceed to the drain action. Otherwise, skip the drain and report the unreleased state.
+
+**Drain action (non-interactive, policy-authorised per the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6):**
+
+1. Run `npm run push:watch` (push + wait for CI to pass).
+2. If `.changeset/` remains non-empty after push (i.e. a release PR is pending), run `npm run release:watch` (merge the release PR + wait for npm publish).
+3. Report the release: "Released <package>@<version>. Mitigation record is now live on npm."
+
+**Failure handling**: if `release:watch` fails (CI failure, publish failure), stop and report the failure clearly. Do not retry non-interactively — the user must intervene.
+
+**Above-appetite branch**: if push/release risk is above appetite, skip the drain and report: "Release skipped — risk above appetite. Run `npm run push:watch` and `npm run release:watch` manually when ready."
+
+## Ownership boundary
+
+`mitigate-incident` writes the Mitigation attempts timeline, the Status field, and the file rename on the first-attempt transition. It does NOT:
+
+- Restore the incident to `.restored.md` (that is `/wr-itil:manage-incident <I###> restored` — slice 6b of the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem phased plan will split this out).
+- Close the incident (that is `/wr-itil:manage-incident <I###> close` — slice 6c).
+- Create or link problems (that is the restore handoff; mitigate-incident does not touch problem state).
+- Add or edit Hypotheses or Observations. Those belong to `/wr-itil:manage-incident <I###>` update flow.
+
+If the user wants any of the above, the skill reports the appropriate sibling and exits.
+
+## Related
+
+- **the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem** (`docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md`) — originating ticket. This skill is slice 6a of the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem phased-landing plan.
+- **the "alignment audit — sweep all unaudited skills/hooks/agents/ADRs/JTBDs/READMEs against the framework-resolution boundary (master ticket)" problem** (`docs/problems/136-adr-044-alignment-audit-master.open.md`) — the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule alignment audit master. This skill is the second high-ask SKILL audited under Phase 2 (after work-problem singular).
+- **the "Rename `wr-problem` Plugin to `wr-itil`" architecture rule amended** (`docs/decisions/010-rename-wr-problem-to-wr-itil.proposed.md` — Skill Granularity section) — canonical skill-split naming + forwarder contract + `deprecated-arguments: true` frontmatter flag.
+- **the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule** (`docs/decisions/011-manage-incident-skill-wrapping.proposed.md`) — incident lifecycle file-suffix conventions (`.investigating.md` / `.mitigating.md` / `.restored.md` / `.closed.md`) + evidence-first rule + reversible-mitigation preference + Sev 4-5 lightweight path.
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule amended Rule 1** — structured user interaction; narrowed in the "Decision-delegation contract — agents over-apply Rule 1's interactive default to framework-resolved decisions; codify the framework-resolution boundary + AFK loop's batched-questions-as-deliverable + lazy-request_user_input measurement" problem to defer to the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule for framework-resolution boundary. Surface 1 (argument-backfill) no longer fires `request_user_input` (framework-mediated); Surfaces 2 + 3 retain it under the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule categories 2 + 3.
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule** Rule 6 — policy-within-appetite non-interactive actions (release drain). Step 9 unchanged.
+- **the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule** (`docs/decisions/044-decision-delegation-contract.proposed.md`) — Decision-Delegation Contract. Surface 1 (argument-backfill) is framework-mediated per the ADR; Surface 2 (evidence-first gate) is category-2 (deviation-approval); Surface 3 (risk-above-appetite commit) is category-3 (one-time-override); **Surface 4 (mitigation SELECTION within the reversible-preference ladder) is framework-mediated / category-4 silent-framework family — agent-owned, no request_user_input and no prose-ask (the "Agent defers mitigation selection to user during active incident — surfaces mitigation choice as user-authority when SKILL contract empowers agent-driven reversible mitigations" problem; see "Reversible preference").**
+- **the "Agent defers mitigation selection to user during active incident — surfaces mitigation choice as user-authority when SKILL contract empowers agent-driven reversible mitigations" problem** (`docs/problems/.../180-agent-defers-mitigation-selection-to-user-during-active-incident.md`) — agent deferred mitigation selection to the user during I002 ("I'll wait for your direction on which mitigation to attempt"); user correction "mitigations don't belong to me. You are empowered." The "Reversible preference" empowerment annotation is the declarative-layer fix (sibling of the "Agents over-ask in interactive sessions — conflating mechanical-stages with user-interactive-stages of multi-stage skill contracts (inverse-)" problem's closed inverse-the "Problem 078: Assistant does not offer to capture a problem ticket when the user delivers strong-signal correction" problem over-ask class on the mitigation-selection surface).
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — governance skills commit their own work.
+- **the "On-Demand Assessment Skills for Governance Plugins" architecture rule** — release scorer delegation pattern.
+- **the "Governance skills auto-release when changesets are queued" architecture rule** — auto-release when changesets are queued.
+- **the "Skill testing strategy — contract-assertion bats companion to" architecture rule** (`docs/decisions/037-skill-testing-strategy.proposed.md`) — contract-assertion bats pattern applied to this skill.
+- **the ": Enforce Governance Without Slowing Down" user outcome** (`docs/jtbd/developer/the ": Enforce Governance Without Slowing Down" user outcome-enforce-governance.proposed.md`) — discoverable surface via `/wr-itil:` autocomplete.
+- **the "Extend the Suite with New Plugins" user outcome** (`docs/jtbd/plugin-developer/the "Extend the Suite with New Plugins" user outcome-extend-suite.proposed.md`) — one skill per distinct user intent.
+- **the "Restore Service Fast with an Audit Trail" user outcome** (`docs/jtbd/tech-lead/the "Restore Service Fast with an Audit Trail" user outcome-restore-service-fast.proposed.md`) — evidence-first audit trail preserved post-split.
+- `<itil-plugin-root>/skills/manage-incident/SKILL.md` — hosts the thin-router forwarder for the deprecated `manage-incident <I###> mitigate <action>` form.
+- `<itil-plugin-root>/skills/list-incidents/SKILL.md` — slice 5 precedent; the split-skill shape this slice mirrors.
+
+$ARGUMENTS

package/skills-codex/mitigate-incident/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Mitigate Incident"
+  short_description: "Record mitigation and transition an incident."

package/skills-codex/reconcile-readme/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: wr-itil:reconcile-readme
+description: Detect and correct drift between docs/problems/README.md and the on-disk ticket inventory. Wraps the diagnose-only `<itil-plugin-root>/scripts/reconcile-readme.sh` script with an agent-applied-edits pattern that preserves narrative content (the "Last reviewed" prose paragraph and Closed-section closure-via free text). Use when README WSJF Rankings, Verification Queue, or Closed sections drift from filesystem state — typically detected by manage-problem Step 0 preflight or work-problems Step 0 preflight.
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Reconcile Problem Backlog README
+
+Reconcile `docs/problems/README.md` against on-disk ticket state when drift is detected. This is the cross-session robustness layer ON TOP of the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem (refresh-on-create) and the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem (refresh-on-transition). Both per-operation contracts hold their per-session evidence — but if any past session committed a ticket change without staging the README refresh, the next session inherits a stale README that no per-operation contract retroactively fixes.
+
+This skill closes that gap. It runs the diagnose-only mechanical drift detector, then applies the corrections to the README in a way that preserves human-curated narrative content.
+
+## Scope
+
+Reconcile drift between `docs/problems/README.md` and these on-disk ticket states:
+
+| File suffix | Belongs in README section | Drift class |
+|------------|---------------------------|-------------|
+| `*.open.md` / `*.known-error.md` | WSJF Rankings | MISSING (file exists, row absent) or DRIFT (row claims wrong status) |
+| `*.verifying.md` | Verification Queue | MISSING (file exists, row absent) or DRIFT (WSJF Rankings row stale) |
+| `*.closed.md` | Closed (curated, not exhaustive) | MISMATCH (Closed row points to wrong-status file) or STALE (still in WSJF / VQ) |
+| `*.parked.md` | Parked (own section) | not enforced — Parked is its own narrative table |
+
+Out of scope:
+- Re-rating WSJF or Effort. The script trusts each ticket file's stored values; re-ranking happens in `/wr-itil:review-problems`.
+- Editing ticket file bodies. Reconciliation is README-only.
+- Migrating between status suffixes. That belongs in `/wr-itil:transition-problem`.
+
+## When invoked
+
+Three invocation surfaces, all routed through this skill so the agent-applied-edits logic stays single-sourced:
+
+1. **Direct user invocation**: `/wr-itil:reconcile-readme` — interactive when the user spots drift in the README.
+2. **Manage-problem Step 0 preflight halt**: when `/wr-itil:manage-problem` Step 0 detects drift via the script, it halts with a directive to invoke this skill (interactive) or auto-applies via this skill in non-interactive mode (AFK orchestrator per the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6).
+3. **Work-problems Step 0 preflight halt**: when `/wr-itil:work-problems` Step 0 detects drift via the script, the same halt-with-directive / auto-apply behaviour applies.
+
+## Steps
+
+### Step 1. Run the diagnose-only script
+
+Invoke the mechanical drift detector:
+
+```bash
+<itil-plugin-root>/bin/wr-itil-reconcile-readme docs/problems
+```
+
+The `<itil-plugin-root>/bin/wr-itil-reconcile-readme` command is a `$PATH`-resolved shim shipped in `<itil-plugin-root>/bin/` that dispatches the canonical `<itil-plugin-root>/scripts/reconcile-readme.sh` body. the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule — never invoke the canonical script via repo-relative path; the path does not resolve in adopter trees.
+
+Exit codes:
+- `0` — clean. No drift; nothing to do. Report "Reconciliation: clean (0 drift entries)" and exit.
+- `1` — drift detected. The script prints one structured row per drift entry to stdout (each ≤ 150 bytes per the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule progressive-disclosure budget). Continue to Step 2.
+- `2` — parse error. README is missing, malformed, or section headers are absent. Halt with the parse-error message; this is a deeper repair that needs investigation, not mechanical reconciliation. In AFK mode (the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6), halt-with-report; do not attempt edits.
+
+### Step 2. Bucket the drift entries by section
+
+Each drift line is one of four shapes:
+
+| Marker | Meaning | Required edit |
+|--------|---------|---------------|
+| `DRIFT    P<NNN> wsjf-rankings: claims=open actual=<X>` | README WSJF Rankings row claims Open but file is `<X>` | REMOVE the row from WSJF Rankings; if `<X>=verifying`, ADD to Verification Queue; if `<X>=closed`, optionally ADD to Closed |
+| `MISSING  P<NNN> wsjf-rankings: actual=<X>` | File exists as `.open.md` / `.known-error.md`; row absent from WSJF Rankings | ADD a row to WSJF Rankings, sourced from the ticket file's `**WSJF**`, `**Priority**`, `**Effort**`, `**Status**`, and `# Problem <NNN>: <title>` line |
+| `MISSING  P<NNN> verification-queue: actual=verifying` | File exists as `.verifying.md`; row absent from Verification Queue | ADD a row to Verification Queue, sourced from the ticket file's `## Fix Released` marker (release marker + date) and title |
+| `STALE    P<NNN> verification-queue: actual=<X>` | Row in Verification Queue but file is `<X>` (typically `closed`) | REMOVE the row from Verification Queue |
+| `MISMATCH P<NNN> closed: actual=<X>` | Row in Closed section names a non-`.closed.md` file | REMOVE the row from Closed (or fix the ID — investigate) |
+
+### Step 3. Read the affected ticket files for ADD edits
+
+For each `MISSING` entry, read the ticket file to extract the row data:
+
+```bash
+# For WSJF Rankings ADD:
+grep -E '^\*\*(Status|Priority|Effort|WSJF)\*\*:' docs/problems/open/<NNN>-*.md
+grep -E '^# Problem <NNN>:' docs/problems/open/<NNN>-*.md
+```
+
+Render the WSJF Rankings row in the existing format:
+
+```
+| <WSJF> | P<NNN> | <title> | <severity> | <status> | <effort> |
+```
+
+For each `MISSING` Verification Queue entry, read the `## Fix Released` block:
+
+```bash
+sed -n '/^## Fix Released/,/^## /p' docs/problems/verifying/<NNN>-*.md
+```
+
+Render the Verification Queue row in the existing format. The `Likely verified?` cell carries an **evidence-first** value per the "VQ `Likely verified?` column uses age-based heuristic (≥14 days = yes) instead of session-observed evidence — sibling proxy-for-evidence anti-pattern to" problem (supersedes the original the "Problem 048: manage-problem does not surface Fix Released problems as verification candidates when the fix path has been exercised" problem Candidate 4 14-day heuristic). <!-- LIKELY-VERIFIED-CELL-SHAPE: evidence-based per the "VQ `Likely verified?` column uses age-based heuristic (≥14 days = yes) instead of session-observed evidence — sibling proxy-for-evidence anti-pattern to" problem --> When reconcile-readme synthesises a missing row, default the cell to `no — not observed` — the row is being added because some prior session committed the `.verifying.md` transition without staging the README refresh; reconcile-readme has no session-observed evidence to cite. Subsequent `/wr-itil:review-problems` Step 4 or `run-retro` Step 4a passes populate `yes — observed: <evidence>` when the user verifies. Drift on the cell shape re-opens the "VQ `Likely verified?` column uses age-based heuristic (≥14 days = yes) instead of session-observed evidence — sibling proxy-for-evidence anti-pattern to" problem.
+
+```
+| P<NNN> | <title> | <release marker> | no — not observed |
+```
+
+### Step 4. Apply edits via Edit tool — preserve narrative
+
+This is the load-bearing step. Use the `Edit` tool to apply each row-level change. DO NOT regenerate the entire README from scratch — the per-Closed-row free-text closure-via column is human-curated narrative that a full regeneration would destroy. (The "Last reviewed:" line is now subject to the **Last-reviewed line discipline (the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem)** described in Step 5 below — it carries only the most-recent fragment, not an ever-growing prose paragraph; the displaced history lives in `docs/problems/README-history.md`. Step 5 owns the line-3 update; Step 4 leaves it untouched.)
+
+For each REMOVE: `Edit` with the existing row as `old_string`, and remove it (replace with empty string) or replace with a re-positioned row in another section (REMOVE-from-WSJF-Rankings + ADD-to-Verification-Queue is two Edit operations: one to delete the WSJF row, one to insert the VQ row).
+
+For each ADD to WSJF Rankings: locate the correct WSJF position by descending order. Use `Edit` to insert the new row immediately above the next-lower-WSJF row (or append at the bottom of the table if the new row's WSJF is the lowest). The Edit's `old_string` is the line that the new row inserts above; the `new_string` is the new row + the same line below.
+
+For each ADD to Verification Queue: insert the new row in `Released date ASC` position (oldest at row 1; same-day releases tiebreak by ID ASC) per the canonical VQ sort direction. <!-- VQ-SORT-DIRECTION: oldest-first per the "Problem lifecycle — add a Verification Pending status between Known Error and Closed" architecture rule --> Recent releases land at the bottom; oldest-pending verifications surface at the top so the user lands on actionable closure candidates first per the "Problem 048: manage-problem does not surface Fix Released problems as verification candidates when the fix path has been exercised" problem user-task semantics. Drift here re-opens the "docs/problems/README.md Verification Queue rendered newest-first contradicts section header "Ranked by release age, oldest first"" problem. The synthesised cell defaults to `no — not observed` per the "VQ `Likely verified?` column uses age-based heuristic (≥14 days = yes) instead of session-observed evidence — sibling proxy-for-evidence anti-pattern to" problem evidence-first cell shape — see the "Render the Verification Queue row" block above. <!-- LIKELY-VERIFIED-CELL-SHAPE: evidence-based per the "VQ `Likely verified?` column uses age-based heuristic (≥14 days = yes) instead of session-observed evidence — sibling proxy-for-evidence anti-pattern to" problem -->
+
+After all edits, re-run `<itil-plugin-root>/scripts/reconcile-readme.sh docs/problems` to confirm exit 0. If the second run still reports drift, investigate the residual edits — do NOT re-run reconciliation in a loop, as that hides systematic edit failures.
+
+### Step 5. Update the "Last reviewed" annotation per the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem truncation discipline
+
+Apply the **Last-reviewed line discipline (the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem)** contract documented in `manage-problem` SKILL.md Step 5 — line 3 carries ONE most-recent fragment naming this reconciliation; the prior content rotates to `docs/problems/README-history.md` (forward-chronology archive, soft cap ≤ 1024 bytes per fragment, hard ceiling 5120 bytes per the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule Tier 3 envelope, surfaced advisory-only by `<itil-plugin-root>/scripts/check-problems-readme-budget.sh`).
+
+**Mechanism**:
+
+1. Read the current line 3 of `docs/problems/README.md` (e.g. `awk 'NR==3' docs/problems/README.md`).
+2. If the current line 3 is non-empty and not a same-day reconciliation duplicate, append it to `docs/problems/README-history.md` under a `## YYYY-MM-DD` heading (creating the heading on first append for that date).
+3. Replace line 3 of README.md with the new fragment of the form:
+
+> Last reviewed: 2026-MM-DD **README reconciled** — (N) drift entries corrected: <comma-separated ID list>. Reconciliation contract per the "`docs/problems/README.md` drifts from filesystem truth across sessions despite (refresh-on-create) and (refresh-on-transition) both Closed" problem + the "Governance Skills Commit Their Own Completed Work" architecture rule amended ("Reconciliation as preflight robustness layer").
+
+Keep the new fragment ≤ 1024 bytes (soft cap) and certainly ≤ 5120 bytes (hard ceiling). Do NOT prepend `Prior:` segments. Do NOT re-write the existing prose inline — the displaced content lives in `README-history.md` going forward; truncation is the contract, not a side effect.
+
+**Rationale (the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem)**: this skill previously documented the line as "an ever-growing prose paragraph". That convention is what produced the 76-KB line-3 that broke the Read tool entirely. The reconcile path was a load-bearing site of the bloat — every reconcile that happened under the old convention re-wrote line 3 unbounded. The new discipline closes the surface for reconcile parity with `manage-problem` Step 5 the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem, Step 6 the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem, Step 7 the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem, and the sibling `transition-problem`, `transition-problems`, `review-problems` skills.
+
+### Step 6. Commit
+
+Commit the reconciled README in a dedicated single-purpose commit — unconditionally, regardless of interactive vs AFK invocation mode, per the "Governance Skills Commit Their Own Completed Work" architecture rule ("governance skills commit their own work"):
+
+```bash
+git add docs/problems/README.md
+git commit -m "chore(problems): reconcile README against filesystem (the "`docs/problems/README.md` drifts from filesystem truth across sessions despite (refresh-on-create) and (refresh-on-transition) both Closed" problem)"
+```
+
+The reconciled state should always be staged together (no partial reconciliation) — when the agent has applied N edits in Step 4, all N belong in the same commit. Interactive and AFK invocations behave identically: the commit decision is **framework-mediated** per the "Governance Skills Commit Their Own Completed Work" architecture rule (the policy already decided governance skills commit their own work), NOT user direction-setting per the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule's authority taxonomy. A per-invocation consent surface here would re-ask a decision the framework has already resolved (the "Skill contract "interactive vs AFK" commit-gating anti-pattern contradicts" problem + lazy-request_user_input under the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule).
+
+The "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6 fail-safe is **risk-gated** (above-appetite + `request_user_input` unavailable → skip commit), not **mode-gated** (interactive vs AFK). Reconciliation is pure mechanical README refresh with no risk-above-appetite branch, so Rule 6 simply does not fire here.
+
+## ADR alignment
+
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** (governance skills commit their own work) — amended to add "Reconciliation as preflight robustness layer" sub-rule. the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem and the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem cover per-operation refresh; this skill covers cross-session drift detection + correction.
+- **the "Problem lifecycle — add a Verification Pending status between Known Error and Closed" architecture rule** (Verification Pending lifecycle status conventions) — Confirmation criterion 3 extended to "and matches the Verification Queue table in `README.md` modulo narrative content".
+- **the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule** (Progressive disclosure for governance tooling context) — script output is per-row terse (≤150 bytes per drift entry); the agent expands narrative-aware edits on demand.
+- **the "Plugin Testing Strategy" architecture rule** (Plugin testing strategy) — script-level bats lives at `<itil-plugin-root>/scripts/test/reconcile-readme.bats`; the "Skill testing strategy — contract-assertion bats companion to" architecture rule (skill testing) governs this skill's own contract bats.
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule** (Structured interaction) — Rule 6 (non-interactive fail-safe) governs the parse-error halt in Step 1 (exit code 2). Rule 6 is risk-gated, not mode-gated; reconciliation's Step 6 commit fires unconditionally per the "Governance Skills Commit Their Own Completed Work" architecture rule (the "Skill contract "interactive vs AFK" commit-gating anti-pattern contradicts" problem). Rule 6 does NOT carve out the Step 6 commit on mode grounds.
+
+## Confirmation
+
+This skill's contract holds when:
+1. The script `<itil-plugin-root>/scripts/reconcile-readme.sh` is read-only — no live README mutation in the script layer (mutation only in this skill's Step 4, via the Edit tool).
+2. Each agent-applied edit preserves the README's narrative content (prose paragraph at top, Closed section free text).
+3. After Step 4 + Step 5, a re-run of the script reports exit 0 (clean).
+4. The reconciled README rides a single commit (Step 6 single-purpose commit) regardless of invocation mode — interactive and AFK behave identically per the "Governance Skills Commit Their Own Completed Work" architecture rule governance-skill commit contract (the "Skill contract "interactive vs AFK" commit-gating anti-pattern contradicts" problem).
+5. The skill is invoked from `/wr-itil:manage-problem` Step 0, `/wr-itil:work-problems` Step 0, AND direct user invocation — no other invocation surface (e.g., `/wr-itil:transition-problem` does NOT call this skill; per architect verdict the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem already covers transition-time refresh inside the same commit, redundant preflight here would pay the cost on every transition).
+
+## Related
+
+- `<itil-plugin-root>/scripts/reconcile-readme.sh` — the diagnose-only mechanical drift detector.
+- `<itil-plugin-root>/scripts/test/reconcile-readme.bats` — script-level bats per the "Plugin Testing Strategy" architecture rule.
+- `<itil-plugin-root>/skills/manage-problem/SKILL.md` — invokes this skill from Step 0 preflight.
+- `<itil-plugin-root>/skills/work-problems/SKILL.md` — invokes the script (not the skill) from Step 0 preflight; halts with directive on drift.
+- `docs/problems/118-readme-drifts-from-filesystem-truth-despite-refresh-contracts-closed.open.md` — the originating problem ticket.
+- `docs/decisions/014-governance-skills-commit-their-own-work.proposed.md` — amended Reconciliation sub-rule.
+- `docs/decisions/022-problem-lifecycle-verification-pending-status.proposed.md` — Confirmation criterion 3 extension.
+- **the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem** (`docs/problems/094-...closed.md`) — refresh-on-create. Composes; this skill is robustness on top, not supersession.
+- **the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem** (`docs/problems/062-...closed.md`) — refresh-on-transition. Composes; same.
+- **the "Skill contract "interactive vs AFK" commit-gating anti-pattern contradicts" problem** (`docs/problems/open/172-skill-contract-interactive-vs-afk-commit-gating-anti-pattern-contradicts-adr-014.md`) — removed the Step 6 interactive-vs-AFK commit-gating carve-out 2026-06-09. The carve-out contradicted the "Governance Skills Commit Their Own Completed Work" architecture rule and produced uncommitted reconciliations across months of AFK-equivalent sessions before the FFS-grade correction surfaced it.
+- `docs/decisions/044-decision-delegation-contract.proposed.md` — framework-resolution boundary; the commit decision is framework-mediated (the "Governance Skills Commit Their Own Completed Work" architecture rule), not user direction-setting.

package/skills-codex/reconcile-readme/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Reconcile README"
+  short_description: "Reconcile the problem index with ticket state."

package/skills-codex/reconcile-stories/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: wr-itil:reconcile-stories
+description: Detect and correct drift between docs/stories/README.md and the on-disk story inventory. Wraps the diagnose-only <itil-plugin-root>/scripts/reconcile-stories.sh script with an agent-applied-edits pattern that preserves narrative content (the "Last reviewed" prose paragraph). Use when docs/stories/README.md Story Rankings or Done sections drift from filesystem state — typically detected by manage-story Step 0 preflight or work-problems preflight on RFC iters with story-tier traces.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Reconcile Stories Skill
+
+Sibling to `/wr-itil:reconcile-readme` (the "`docs/problems/README.md` drifts from filesystem truth across sessions despite (refresh-on-create) and (refresh-on-transition) both Closed" problem / the "Governance Skills Commit Their Own Completed Work" architecture rule) and `/wr-itil:reconcile-rfcs` (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 1 item 5), applied at the story tier per the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem Phase 2 Slice 9.
+
+**Diagnose-only mechanic** — wraps `<itil-plugin-root>/scripts/reconcile-stories.sh` (resolved via `<itil-plugin-root>/bin/wr-itil-reconcile-stories` `$PATH` shim per the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule). The script reads `docs/stories/<state>/STORY-NNN-*.md` files across all 5 lifecycle subdirs (draft, accepted, in-progress, done, archived), parses `docs/stories/README.md`'s Story Rankings + Done tables, and reports each disagreement. Exit codes: `0` clean, `1` drift detected (structured stdout), `2` parse error.
+
+**Reverse-trace pass** — when the parent directories exist, the reconciler checks auto-maintained `## Stories` sections on problem, JTBD and legacy RFC files. For an the "A release row is the RFC, and the map is the approval surface" architecture rule row-backed RFC, it checks the map row instead: the RFC must resolve and the row must contain the story card.
+- `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — story claims parent but parent's `## Stories` table doesn't list the story
+- `STALE_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent lists the story but story no longer claims the parent
+- `STATUS_MISMATCH STORY-NNN in <PARENT-ID> ## Stories claims=<X> actual=<Y>` — parent's row claims one lifecycle status; story's filesystem subdir is a different state
+- `UNRESOLVED_RFC_TRACE STORY-NNN claims=RFC-NNN` — neither a legacy RFC file nor a story-map release row exists
+- `MISSING_REVERSE_TRACE STORY-NNN in RFC-NNN release row` — the release row exists but does not contain the story card
+
+## When to invoke
+
+- **Drift detected by another skill's preflight** — `/wr-itil:manage-story` or `/wr-itil:work-problems` Step 0 preflight may surface `docs/stories/README.md` drift; this skill is the recovery path.
+- **Manual drift recovery** — user notices the README is stale (e.g. story moved between lifecycle subdirs without README refresh; reverse-trace `## Stories` section out of date on a problem ticket).
+- **CI drift gate** — a CI step running `<itil-plugin-root>/bin/wr-itil-reconcile-stories` against the merge target would surface drift before merge; this skill is the in-repo recovery path.
+
+## Composition with manage-story
+
+`manage-story` (the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem Phase 2 Slice 8) owns the inline the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem / the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem README refresh on every lifecycle transition (draft → accepted → in-progress → done). When the inline refresh is satisfied, the README stays current and `reconcile-stories` reports clean. The reconcile skill is the *recovery* path when inline refresh was missed (typically when story files are moved manually, or when frontmatter trace edits don't ride through `manage-story`).
+
+## Steps
+
+### 1. Run the diagnose script
+
+```bash
+<itil-plugin-root>/bin/wr-itil-reconcile-stories docs/stories docs/problems docs/rfcs docs/jtbd docs/story-maps > /tmp/wr-itil-stories-drift-$$.txt
+reconcile_exit=$?
+```
+
+- **Exit 0**: README is clean. Report "no drift detected" and exit.
+- **Exit 1**: drift detected. Continue to Step 2.
+- **Exit 2**: parse error (README missing or malformed). Halt; the README needs structural repair which this skill doesn't own (the `manage-story review` flow handles structural-rebuild semantics).
+
+### 2. Read drift entries + plan edits
+
+Read `/tmp/wr-itil-stories-drift-$$.txt` line by line. Each line is one of:
+- `DRIFT    STORY-NNN rankings: claims=<X> actual=<Y>` — Story Rankings row has wrong Status; update the row.
+- `STALE    STORY-NNN rankings: actual=<state>` — Story Rankings table is missing a row; add it.
+- `MISMATCH STORY-NNN done: actual=<state>` — Done table has wrong row OR an extra row; remove/adjust.
+- `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story added; call `update-<parent-kind>-references-section.sh <parent-file> "Stories"` to refresh.
+- `STALE_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story removed; same helper call (idempotent, lazy-empty discipline removes when no traces remain).
+- `STATUS_MISMATCH STORY-NNN in <PARENT-ID> ## Stories claims=<X> actual=<Y>` — same helper call refreshes the status column.
+- `UNRESOLVED_RFC_TRACE` / row `MISSING_REVERSE_TRACE` — repair the map's release row or card through `/wr-itil:manage-story-map`; do not create an empty RFC file.
+
+### 3. Apply edits
+
+For README drift entries — edit `docs/stories/README.md` in-place preserving the "Last reviewed" prose paragraph at the top. Use the Edit tool with narrow `old_string` / `new_string` pairs targeting only the table row(s) affected.
+
+For reverse-trace drift entries — invoke the appropriate Slice 2a/2b helper for each parent file:
+
+```bash
+# Problem parent
+<itil-plugin-root>/bin/wr-itil-update-problem-references-section "$problem_file" "Stories"
+# RFC parent
+<itil-plugin-root>/bin/wr-itil-update-rfc-references-section "$rfc_file" "Stories"
+# JTBD parent
+<itil-plugin-root>/bin/wr-itil-update-jtbd-references-section "$jtbd_file" "Stories"
+```
+
+### 4. Verify + commit
+
+Re-run `<itil-plugin-root>/bin/wr-itil-reconcile-stories` after edits. Exit 0 expected. Stage all modified files (README + parent files) and commit per the "Governance Skills Commit Their Own Completed Work" architecture rule single-commit grain.
+
+Commit message:
+
+```
+docs(stories): reconcile docs/stories/README.md drift (N entries)
+
+Refs: <relevant problem/RFC/story IDs derived from the drift entries>
+```
+
+The "Governance Skills Commit Their Own Completed Work" architecture rule commit grain is "one reconciliation pass per commit" — covers README + N parent files all in one commit since they're all reconciling to filesystem truth, a single coherent action.
+
+### 5. Report
+
+After commit, report:
+- Number of drift entries reconciled.
+- Files modified (README + each parent reverse-trace surface touched).
+- Commit SHA.
+- Trailing pointer: `Run /wr-itil:manage-story review next to refresh story rankings + INVEST scoring if any stories crossed the accepted gate during the reconciliation window.`
+
+## Ownership boundary
+
+`reconcile-stories` owns drift DETECTION and MECHANICAL REPAIR of `docs/stories/README.md` + reverse-trace sections. It does NOT:
+- Move story files between lifecycle subdirs (that's `manage-story` § Status transitions).
+- Edit story frontmatter (that's `manage-story` at lifecycle transitions OR `capture-story` at capture-time).
+- Refresh story body sections (User value / Acceptance criteria / Implementation notes are owned by `manage-story` lifecycle transitions per I10 INVEST gates).
+- Run WSJF computation (I11 invariant: stories MUST NOT carry a WSJF field in Phase 2 per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 253).
+
+## Related
+
+- **the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem** — driver problem ticket.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule** — Problem-RFC-Story framework. Phase 2 amendment 2026-05-10 introduces the story tier; line 270 names the auto-maintained `## Stories` reverse-trace section contract.
+- **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — plugin-bundled scripts via `bin/` on `$PATH`. `<itil-plugin-root>/bin/wr-itil-reconcile-stories` shim follows this grammar.
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — single-commit grain. The reconciliation pass is a single coherent action; one commit per pass.
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default. Bats coverage at `<itil-plugin-root>/scripts/test/reconcile-stories.bats` (the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem Phase 2 Slice 9).
+- **the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule** — diagnose-only advisory-exit contract. `reconcile-stories.sh` is exit-1 on drift, exit-0 on clean, exit-2 on parse error.
+- **the "`docs/problems/README.md` drifts from filesystem truth across sessions despite (refresh-on-create) and (refresh-on-transition) both Closed" problem** / `reconcile-readme.sh` — sibling at the problems tier.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 1 item 5** / `reconcile-rfcs.sh` — sibling at the RFC tier.
+- **Slice 2a/2b helpers** — `update-problem-references-section.sh`, `update-rfc-references-section.sh`, `update-jtbd-references-section.sh` are the load-bearing reverse-trace refresh helpers this skill invokes; all three accept `"Stories"` as a section-name token per their lookup tables.
+- **the ": Enforce Governance Without Slowing Down" user outcome** — Enforce Governance Without Slowing Down. Drift detection is an automated governance enforcement surface; mechanical repair preserves the spirit while removing manual toil.
+- **the ": Decompose a Fix Into Coordinated Changes" user outcome** — Decompose a Fix Into Coordinated Changes. Story tier reverse-trace integrity is load-bearing for the working-the-problem flow's per-story dispatch (Slice 13 traversal).
+
+$ARGUMENTS

package/skills-codex/reconcile-stories/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Reconcile Stories"
+  short_description: "Reconcile the story index with story state."