@windyroad/itil 0.14.0 → 0.15.0-preview.157

package/skills/manage-incident/test/manage-incident-restore-forwarder.bats

@@ -0,0 +1,66 @@
+#!/usr/bin/env bats
+# Contract assertions for manage-incident's `restored` subcommand forwarder (P071 split slice 6b).
+#
+# Per ADR-010 amended (Skill Granularity section) + P071 phased plan:
+# `/wr-itil:manage-incident <I> restored` delegates to the new
+# `/wr-itil:restore-incident <I>` skill via a thin-router forwarder.
+# Original skill already carries `deprecated-arguments: true` frontmatter
+# (slice 5); forwarder emits a canonical one-line systemMessage
+# deprecation notice.
+#
+# Structural assertion — Permitted Exception to the source-grep ban
+# (ADR-005 / P011 / ADR-037 contract-assertion pattern).
+#
+# @problem P071
+# @jtbd JTBD-001 (enforce governance without slowing down)
+# @jtbd JTBD-101 (extend the suite with clear patterns)
+# @jtbd JTBD-201 (restore service fast with an audit trail)
+#
+# Cross-reference:
+#   P071: docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md
+#   ADR-010 amended — split naming + forwarder contract + deprecated-arguments flag
+#   ADR-011 — manage-incident skill-wrapping precedent (restore transition + manage-problem handoff)
+#   ADR-013 Rule 1 — structured user interaction (forwarder emits systemMessage, not AskUserQuestion)
+#   ADR-037 — contract-assertion bats pattern
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "manage-incident SKILL.md frontmatter has deprecated-arguments: true (ADR-010 amended)" {
+  # Already pinned by slice 5; slice 6b inherits. Guard against regression.
+  run grep -nE "^deprecated-arguments:[[:space:]]*true[[:space:]]*$" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-incident Step 1 forwards 'restored' argument to /wr-itil:restore-incident (P071)" {
+  # The forwarder names the target skill explicitly so the router is legible
+  # at the contract level. ADR-010's canonical shape: "invokes the new
+  # named skill via the Skill tool, not via re-prompting the user".
+  run grep -inE "/wr-itil:restore-incident" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-incident Step 1 emits the canonical restored deprecation notice (ADR-010 amended)" {
+  # ADR-010's canonical deprecation-notice template:
+  # "/wr-<plugin>:<old> <arg> is deprecated; use /wr-<plugin>:<new>
+  #  directly. This forwarder will be removed in <plugin>'s next major
+  #  version."
+  # The notice MUST be emitted as a systemMessage (not AskUserQuestion)
+  # because deprecation is informational, not decisional (ADR-013 Rule 1
+  # structured-interaction scope).
+  run grep -inE "is deprecated.*use /wr-itil:restore-incident|deprecated.*restore-incident|restored.*removed in .* next major version" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-incident Step 1 restored forwarder delegates via Skill tool (P071 regression guard)" {
+  # The forwarder must not duplicate the restore logic — it must delegate.
+  # Per ADR-010: "thin-router forwarder re-invokes the new named skill
+  # via the Skill tool". If the forwarder grows its own rename + handoff
+  # logic, the deprecation window will harden into a permanent fork.
+  # Guard against this by asserting the forwarder block mentions "delegate"
+  # or "Skill tool" language near the restore-incident reference.
+  run grep -inE "delegate.*restore-incident|Skill tool.*restore-incident|restore-incident.*Skill tool" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/mitigate-incident/SKILL.md

@@ -0,0 +1,211 @@
+---
+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 ADR-011.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
+---
+
+# 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 (JTBD-201).
+
+This skill is the P071 phased-landing split of `/wr-itil:manage-incident <I> mitigate <action>` per ADR-010 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, ask via `AskUserQuestion` for the incident ID and the action.
+
+## Reversible preference (ADR-011)
+
+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.
+
+## Evidence-first gate (ADR-011)
+
+**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 `AskUserQuestion`:
+
+> "Incident `<I###>` has no hypothesis with cited evidence. Per ADR-011, 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
+
+Extract `<I###>` and `<action>` from `$ARGUMENTS`. Normalise `<I###>`:
+
+- Accept `I007`, `i007`, `007`, `7` → canonicalise to `I007` (uppercase I + zero-padded 3 digits).
+- If missing, ask via `AskUserQuestion`.
+
+Extract `<action>` as everything after the incident ID. If missing or trivially short (< 8 chars), ask via `AskUserQuestion` for a descriptive action.
+
+### 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)
+
+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 ADR-011:
+
+```
+- [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 `AskUserQuestion` with the three-option prompt from "Evidence-first gate" above. 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 — 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 (ADR-011 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 ADR-011.
+- 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 (ADR-014)
+
+Per ADR-014, 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 Skill tool instead — per ADR-015 it wraps the same pipeline subagent.
+3. `git commit -m "docs(incidents): I<NNN> mitigated — <action summary>"`.
+4. If risk is above appetite: use `AskUserQuestion` to ask whether to commit anyway, remediate first, or park the work. If `AskUserQuestion` is unavailable, skip the commit and report the uncommitted state clearly.
+
+### 9. Auto-release when changesets are queued (ADR-020)
+
+**Skip this step if the skill is running inside an AFK orchestrator.** Orchestrators handle release cadence themselves per ADR-018 (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 ADR-015):**
+
+1. Invoke the release scorer. Two paths are valid:
+   - **Primary**: delegate to subagent type `wr-risk-scorer:pipeline` via the Agent tool.
+   - **Fallback**: if that subagent type is not available, invoke skill `/wr-risk-scorer:assess-release` via the Skill tool.
+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 ADR-013 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 P071 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
+
+- **P071** (`docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md`) — originating ticket. This skill is slice 6a of the P071 phased-landing plan.
+- **ADR-010 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.
+- **ADR-011** (`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.
+- **ADR-013** Rule 1 — structured user interaction (evidence-gate prompt uses AskUserQuestion; deprecation notices use systemMessage).
+- **ADR-013** Rule 6 — policy-within-appetite non-interactive actions (release drain).
+- **ADR-014** — governance skills commit their own work.
+- **ADR-015** — release scorer delegation pattern.
+- **ADR-020** — auto-release when changesets are queued.
+- **ADR-037** (`docs/decisions/037-skill-testing-strategy.proposed.md`) — contract-assertion bats pattern applied to this skill.
+- **JTBD-001** (`docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md`) — discoverable surface via `/wr-itil:` autocomplete.
+- **JTBD-101** (`docs/jtbd/plugin-developer/JTBD-101-extend-suite.proposed.md`) — one skill per distinct user intent.
+- **JTBD-201** (`docs/jtbd/tech-lead/JTBD-201-restore-service-fast.proposed.md`) — evidence-first audit trail preserved post-split.
+- `packages/itil/skills/manage-incident/SKILL.md` — hosts the thin-router forwarder for the deprecated `manage-incident <I###> mitigate <action>` form.
+- `packages/itil/skills/list-incidents/SKILL.md` — slice 5 precedent; the split-skill shape this slice mirrors.
+
+$ARGUMENTS

package/skills/mitigate-incident/test/mitigate-incident-contract.bats

@@ -0,0 +1,152 @@
+#!/usr/bin/env bats
+# Contract assertions for /wr-itil:mitigate-incident (P071 split slice 6a).
+#
+# This skill hosts the "mitigate an incident" user intent previously
+# hidden behind /wr-itil:manage-incident <I> mitigate <action>. It records
+# a mitigation attempt, transitions an incident from .investigating.md to
+# .mitigating.md (first mitigation only), and appends the attempt + outcome
+# to the Mitigation attempts timeline per ADR-011.
+#
+# Structural assertion — Permitted Exception to the source-grep ban
+# (ADR-005 / P011 / ADR-037 contract-assertion pattern).
+#
+# @problem P071
+# @jtbd JTBD-001 (enforce governance without slowing down — discoverable surface)
+# @jtbd JTBD-101 (extend the suite with clear patterns — one skill per distinct user intent)
+# @jtbd JTBD-201 (restore service fast with an audit trail — mitigation + evidence gate)
+#
+# Cross-reference:
+#   P071: docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md
+#   ADR-010 amended (Skill Granularity section) — split naming + forwarder contract
+#   ADR-011 — manage-incident skill-wrapping precedent (evidence-gate, reversible preference)
+#   ADR-037 — contract-assertion bats pattern
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md exists and has frontmatter" {
+  [ -f "$SKILL_FILE" ]
+  run head -1 "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "---" ]
+}
+
+@test "SKILL.md frontmatter name is wr-itil:mitigate-incident (P071 + ADR-010 amended)" {
+  # Split naming convention per ADR-010 amendment: <verb>-<object> pair.
+  # The new skill's name must match the phased-landing plan pinned in P071.
+  run grep -n "^name: wr-itil:mitigate-incident$" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md frontmatter description names the mitigate intent (P071)" {
+  # Description must name "mitigate" and "incident" so Claude Code autocomplete
+  # surfaces the user intent rather than a generic name.
+  run grep -inE "^description:.*mitigat.*incident|^description:.*incident.*mitigat" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md frontmatter allowed-tools grants file-mutation surface (P071 — mitigate requires rename + edit)" {
+  # Unlike list-incidents (read-only), mitigate-incident renames
+  # .investigating.md → .mitigating.md, updates the Status field, and
+  # appends to Mitigation attempts. It must declare Write + Edit + Bash
+  # (for git mv) in its allowed-tools. AskUserQuestion is required for
+  # the evidence-gate pre-flight prompt per ADR-011 when a hypothesis
+  # lacks cited evidence.
+  run grep -nE "^allowed-tools:" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE "^allowed-tools:.*Write" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE "^allowed-tools:.*Edit" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE "^allowed-tools:.*Bash" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE "^allowed-tools:.*AskUserQuestion" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md documents the evidence-gate pre-flight (P071 + ADR-011)" {
+  # Per ADR-011's "Do not act on a hypothesis without at least one cited
+  # evidence source" rule, mitigate-incident's pre-flight must block the
+  # first mitigation attempt when no hypothesis has cited evidence.
+  # The SKILL.md must name the gate explicitly so the audit-trail
+  # invariant (JTBD-201) is legible.
+  run grep -inE "evidence|hypothes" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md documents the .investigating.md → .mitigating.md rename (P071 + ADR-011)" {
+  # The first mitigation attempt transitions the incident file from
+  # .investigating.md to .mitigating.md. Subsequent mitigations append
+  # to the existing .mitigating.md. The SKILL.md must name both
+  # suffixes explicitly so the file-suffix contract is legible.
+  run grep -inE "\.investigating\.md" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -inE "\.mitigating\.md" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md documents the reversible-mitigation preference (P071 + ADR-011)" {
+  # Per ADR-011, mitigate-incident prefers reversible mitigations
+  # (rollback → feature flag → restart → route traffic → scale → fix)
+  # over forward fixes. The SKILL.md must name the preference so the
+  # cool-headed-commitment invariant is preserved post-split.
+  run grep -inE "reversible|rollback" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md documents the Mitigation attempts timeline append (P071 + ADR-011)" {
+  # Every mitigation attempt, successful or not, must append a
+  # [timestamp] action → outcome row to the Mitigation attempts section.
+  # The SKILL.md must name the append contract so future maintainers
+  # don't drop failed-attempt recording.
+  run grep -inE "[Mm]itigation attempt" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md cites P071 and ADR-010 amended (P071 + ADR-025)" {
+  # ADR-025 inheritance per ADR-037: contract-assertion bats should reflect
+  # traceability cites on the skill spec document.
+  run grep -inE "P071|ADR-010" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md cites ADR-011 for the incident lifecycle conventions (P071 + ADR-011)" {
+  # mitigate-incident inherits file-suffix conventions and the
+  # evidence-first rule from ADR-011. The SKILL.md must cite ADR-011
+  # so the precedent chain is legible.
+  run grep -inE "ADR-011" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md does not carry a deprecated-arguments frontmatter flag (clean-split skill)" {
+  # mitigate-incident is a clean-split skill with no argument-subcommands
+  # itself (its arguments are data parameters — incident ID + action).
+  # ADR-010 amendment's `deprecated-arguments: true` flag is only valid
+  # on host skills with forwarder routes. mitigate-incident is a
+  # forwarder TARGET, not a host. It must NOT carry the flag.
+  run grep -E "^deprecated-arguments:" "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "SKILL.md does not use word-argument subcommand branching (P071 regression guard)" {
+  # The whole point of P071: Claude Code autocomplete does not surface
+  # word-argument subcommands. A clean-split skill must not reintroduce
+  # word-arg subcommand routing (e.g. `list` / `mitigate` / `restore`).
+  # The data parameters <I> and <action> are strings, not verb keywords,
+  # so the anti-pattern is patterns like `If arguments start with "list"`.
+  run grep -inE "If arguments start with \"(list|mitigate|restore|close|link)\"|If arguments contain \"(list|mitigate|restore|close|link)\"" "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "SKILL.md documents the low-severity lightweight path (P071 + ADR-011 edge case)" {
+  # ADR-011's Step 12 edge case: for Sev 4-5 incidents, the Hypotheses
+  # section may be skipped if the user confirms no investigation is
+  # needed. Timeline, Observations, and at least one mitigation attempt
+  # remain mandatory. The split skill must preserve this lightweight
+  # path so JTBD-001's "without slowing down" outcome holds during
+  # low-severity incidents.
+  run grep -inE "lightweight|low.?severity|Sev 4|Sev 5" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/restore-incident/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: wr-itil:restore-incident
+description: Mark an incident as service-restored — transitions a mitigating incident to restored, appends a Timeline entry, and hands off to /wr-itil:manage-problem for linked-problem creation or update per ADR-011.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
+---
+
+# Restore Incident
+
+Mark an active incident as service-restored and hand off to problem management for root-cause tracking. This skill is the active-restoration path — the point where the "cool-headed, evidence-first" incident lifecycle crosses from mitigation to post-restoration (JTBD-201).
+
+The first restore attempt moves the file from `.mitigating.md` to `.restored.md`, updates the `**Status**` field to "Restored", appends a verification-signal entry to the Timeline, and invokes `/wr-itil:manage-problem` via the Skill tool so a problem record captures the root-cause handoff. If the user declines problem creation with a justification, a `## No Problem` section is written on the incident instead — preserving the audit-trail invariant.
+
+This skill is the P071 phased-landing split of `/wr-itil:manage-incident <I> restored` per ADR-010 amended Skill Granularity rule: one skill per distinct user intent. The argument `<I>` is a data parameter, permitted under the amendment — only word-verb-arguments must be split out. The original `/wr-itil:manage-incident <I> restored` 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:restore-incident <I###>` — one positional data parameter:
+
+- `<I###>` — the incident ID (e.g. `I007` or bare `007`). Resolves to `docs/incidents/<I###>-*.mitigating.md` (primary path) or `docs/incidents/<I###>-*.restored.md` (idempotent re-invocation).
+
+If `$ARGUMENTS` is empty or malformed, ask via `AskUserQuestion` for the incident ID.
+
+## Pre-flight (ADR-011)
+
+Restore requires two pre-flight conditions:
+
+1. **Mitigation recorded**: at least one `[<timestamp> UTC] <action> → <outcome>` row in the `## Mitigation attempts` section. A restore with no mitigation recorded usually means the incident self-resolved — in that case the user should record the self-resolution as a mitigation entry first (e.g. `[<timestamp> UTC] (no action taken — issue self-resolved) → pending verification`).
+2. **Verification signal captured**: the user must describe the signal that confirms service is restored (e.g. "error rate back to baseline per Datadog", "user reports normal", "synthetic probe passing"). This is the verification evidence that the restore is real, not wishful.
+
+If either pre-flight fails, block the transition and ask via `AskUserQuestion` what to do: (a) record a mitigation + verification signal now and retry, (b) document why this incident is an exception (e.g. Sev 4-5 lightweight path) and proceed with an Audit-trail note, (c) cancel.
+
+## Steps
+
+### 1. Parse arguments
+
+Extract `<I###>` from `$ARGUMENTS`. Normalise:
+
+- Accept `I007`, `i007`, `007`, `7` → canonicalise to `I007` (uppercase I + zero-padded 3 digits).
+- If missing, ask via `AskUserQuestion`.
+
+### 2. Locate the incident file
+
+```bash
+ls docs/incidents/<I###>-*.mitigating.md docs/incidents/<I###>-*.restored.md 2>/dev/null
+```
+
+- If neither exists (the incident is `.investigating.md` or `.closed.md`), report "No active mitigation-or-restored incident `<I###>` found. If the incident is still investigating, record at least one mitigation attempt via `/wr-itil:mitigate-incident <I###> <action>` first." and exit.
+- If a `.mitigating.md` file matches, this is the restore transition (Case A in Step 4).
+- If a `.restored.md` file matches, this is an idempotent re-invocation (Case B in Step 4).
+- If multiple files match (should not happen under the naming convention), report the ambiguity and exit.
+
+### 3. Pre-flight: verification signal + mitigation-attempts check
+
+For the Case A path (restore transition), perform the pre-flight checks:
+
+1. Read the `## Mitigation attempts` section. If it is missing, empty, or contains only `*(none yet)*`, the first pre-flight fails. Ask via `AskUserQuestion`.
+2. Ask via `AskUserQuestion` for the verification signal if not already provided in `$ARGUMENTS`. The signal is free-text and should name the metric, probe, or report that confirms restoration.
+
+### 4. Record the restore and transition if needed
+
+Compute a UTC timestamp (e.g. `2026-04-21T14:37Z`). Then:
+
+**Case A — first restore (`.mitigating.md` → `.restored.md`)**:
+
+1. `git mv docs/incidents/<I###>-<title>.mitigating.md docs/incidents/<I###>-<title>.restored.md`
+2. Update the `**Status**:` field from `Mitigating` to `Restored` via `Edit`.
+3. Append to the `## Timeline` section:
+
+   ```markdown
+   - [<timestamp> UTC] Service restored — <verification signal>
+   ```
+
+**Case B — idempotent re-invocation (`.restored.md` stays `.restored.md`)**:
+
+1. No `git mv` needed.
+2. Do not re-edit the `**Status**:` field.
+3. If a verification signal was provided in `$ARGUMENTS` and differs from the existing Timeline, append an additional `[<timestamp> UTC] Service restored (re-verified) — <verification signal>` line to the `## Timeline`. Otherwise, skip the Timeline append and proceed to Step 5 (the user may be re-running the handoff).
+
+### 5. Problem handoff
+
+Ask via `AskUserQuestion`: "Service restored. Should I create or update a problem record for the root cause? (a) yes — recommended, (b) no — document why (trivial/one-off)".
+
+**Branch (a) — Yes, create or update problem**:
+
+1. Construct a handoff payload:
+   - Incident ID and title
+   - Timeline summary (most recent entries)
+   - Top-ranked hypothesis + cited evidence from `## Hypotheses`
+   - Mitigation applied + verification signal from `## Mitigation attempts` + the just-appended Timeline entry
+2. Invoke `/wr-itil:manage-problem` via the **Skill tool** with the payload as arguments. The problem skill's existing dedupe flow handles new-vs-update — do not duplicate that logic here.
+3. Capture the returned `P<NNN>` (or `P<NNN> (updated)` for a dedupe hit).
+4. Write (or update) the incident's `## Linked Problem` section:
+
+   ```markdown
+   ## Linked Problem
+   P<NNN> (<title>) — <status>
+   ```
+
+   If the section already exists, edit it in place; otherwise append at the end of the file.
+
+**Branch (b) — No, document the no-problem justification**:
+
+1. Ask via `AskUserQuestion` for the justification (free-text). Examples: "one-off cosmic-bit-flip; not reproducible", "transient upstream outage; no action on our side", "test incident (training exercise)".
+2. Write a `## No Problem` section into the incident file:
+
+   ```markdown
+   ## No Problem
+   <reason — e.g. "one-off cosmic-bit-flip; not reproducible">
+   ```
+
+   If a `## Linked Problem` section exists, replace it with the `## No Problem` section (one or the other — never both).
+
+### 6. Quality checks
+
+After the restore, verify:
+
+- **Status consistency**: `**Status**:` field matches the filename suffix (`Restored` + `.restored.md`).
+- **Timeline monotonicity**: the new "Service restored" entry's timestamp is ≥ the last existing timeline entry's timestamp.
+- **Post-restore sections present**: exactly one of `## Linked Problem` or `## No Problem` exists; never both, never neither.
+
+### 7. Report
+
+Report:
+
+- The file path created/modified.
+- The incident ID and title.
+- The transition (Mitigating → Restored, or Restored → Restored for re-invocations).
+- The verification signal recorded.
+- Whether a problem was created, updated, or skipped with a `## No Problem` justification.
+- The linked problem ID (if any).
+- A pointer: "Run `/wr-itil:close-incident <I###>` when the linked problem reaches Known Error, Verifying, or Closed (or if the incident carries a No Problem justification), or keep the incident in Restored while the root cause work progresses."
+
+### 8. Commit the completed work (ADR-014)
+
+Per ADR-014, 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 Skill tool instead — per ADR-015 it wraps the same pipeline subagent.
+3. `git commit -m "docs(incidents): I<NNN> restored — <verification signal summary>"`.
+4. If risk is above appetite: use `AskUserQuestion` to ask whether to commit anyway, remediate first, or park the work. If `AskUserQuestion` is unavailable, skip the commit and report the uncommitted state clearly.
+
+### 9. Auto-release when changesets are queued (ADR-020)
+
+**Skip this step if the skill is running inside an AFK orchestrator.** Orchestrators handle release cadence themselves per ADR-018 (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 ADR-015):**
+
+1. Invoke the release scorer. Two paths are valid:
+   - **Primary**: delegate to subagent type `wr-risk-scorer:pipeline` via the Agent tool.
+   - **Fallback**: if that subagent type is not available, invoke skill `/wr-risk-scorer:assess-release` via the Skill tool.
+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 ADR-013 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>. Restoration 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
+
+`restore-incident` writes the Timeline "Service restored" entry, the Status field, the file rename on the transition, and exactly one of `## Linked Problem` or `## No Problem`. It does NOT:
+
+- Close the incident (that is `/wr-itil:close-incident <I###>` — slice 6c).
+- Link the incident to an existing problem without performing the restore transition (that is `/wr-itil:link-incident <I###> P<MMM>` — slice 6d).
+- Record a mitigation attempt (that is `/wr-itil:mitigate-incident <I###> <action>` — slice 6a).
+- Rename or transition a `.investigating.md` file — the incident must already be `.mitigating.md` before restore.
+
+If the user wants any of the above, the skill reports the appropriate sibling and exits.
+
+## Related
+
+- **P071** (`docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md`) — originating ticket. This skill is slice 6b of the P071 phased-landing plan.
+- **ADR-010 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.
+- **ADR-011** (`docs/decisions/011-manage-incident-skill.proposed.md`) — incident lifecycle file-suffix conventions (`.investigating.md` / `.mitigating.md` / `.restored.md` / `.closed.md`) + Decision Outcome point 4 (direct Skill-tool invocation of `/wr-itil:manage-problem` for problem handoff).
+- **ADR-013** Rule 1 — structured user interaction (verification-signal and handoff prompts use AskUserQuestion; deprecation notice uses systemMessage).
+- **ADR-013** Rule 6 — policy-within-appetite non-interactive actions (release drain).
+- **ADR-014** — governance skills commit their own work.
+- **ADR-015** — release scorer delegation pattern.
+- **ADR-020** — auto-release when changesets are queued.
+- **ADR-037** (`docs/decisions/037-skill-testing-strategy.proposed.md`) — contract-assertion bats pattern applied to this skill.
+- **JTBD-001** (`docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md`) — discoverable surface via `/wr-itil:` autocomplete.
+- **JTBD-101** (`docs/jtbd/plugin-developer/JTBD-101-extend-suite.proposed.md`) — one skill per distinct user intent.
+- **JTBD-201** (`docs/jtbd/tech-lead/JTBD-201-restore-service-fast.proposed.md`) — this skill IS the active-restoration path; audit trail invariants preserved post-split.
+- `packages/itil/skills/manage-incident/SKILL.md` — hosts the thin-router forwarder for the deprecated `manage-incident <I###> restored` form.
+- `packages/itil/skills/mitigate-incident/SKILL.md` — slice 6a precedent; restore-incident mirrors the split shape.
+- `packages/itil/skills/manage-problem/SKILL.md` — cross-skill invocation target during problem handoff.
+
+$ARGUMENTS