@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/skills-codex/report-upstream/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Report Upstream"
+  short_description: "Report a local problem to an upstream project."

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

@@ -0,0 +1,216 @@
+---
+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 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.
+
+
+# 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 (the "Restore Service Fast with an Audit Trail" user outcome).
+
+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 installed skill invocation 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 "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem phased-landing split of `/wr-itil:manage-incident <I> restored` per the "Rename `wr-problem` Plugin to `wr-itil`" architecture rule 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, 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 `mitigate-incident` Surface 1 / `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. This scopes to the `<I###>` ID only — the verification signal (Pre-flight / Step 3) and the problem-handoff decision (Step 5) remain genuine interactive user-authority surfaces. The exact usage block is in Step 1.
+
+## Pre-flight (the "Add `manage-incident` Skill to `wr-itil` Plugin" architecture rule)
+
+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 `request_user_input` 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 (fail-fast on typos — the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule Surface 1)
+
+Extract `<I###>` from `$ARGUMENTS`. Normalise:
+
+- 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 `mitigate-incident` Step 1 + `transition-problem` Step 1 + `work-problem` singular precedent for consistency across the suite (the "Extend the Suite with New Plugins" user outcome — clear patterns).
+
+**Usage block** (emitted on any malformed-argument case; copy verbatim so adopters get a consistent shape):
+
+```
+Usage: /wr-itil:restore-incident <I###>
+  <I###>  — incident ID (e.g. I007 or bare 007); must resolve to docs/incidents/<I###>-*.{mitigating,restored}.md
+
+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###>-*.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 `request_user_input`.
+2. Ask via `request_user_input` 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 `request_user_input`: "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 **installed skill invocation** 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 `request_user_input` 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 (the "Governance Skills Commit Their Own Completed Work" architecture rule)
+
+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> restored — <verification signal summary>"`.
+4. If commit risk is above appetite: **framework-mediated, no 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**: score the restore action against the live realised-risk baseline (incident Likelihood already 5) — net risk-reducing actions take the risk-reducing path (`RISK_BYPASS: reducing`) and proceed; otherwise auto-remediate (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 the commit and report the uncommitted state.
+
+### 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>. 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
+
+- **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 6b of the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem phased-landing plan.
+- **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.proposed.md`) — incident lifecycle file-suffix conventions (`.investigating.md` / `.mitigating.md` / `.restored.md` / `.closed.md`) + Decision Outcome point 4 (direct installed-skill-invocation invocation of `/wr-itil:manage-problem` for problem handoff).
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule** Rule 1 — structured user interaction (verification-signal and handoff prompts use request_user_input; deprecation notice uses systemMessage).
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule** Rule 6 — policy-within-appetite non-interactive actions (release drain).
+- **the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule** (`docs/decisions/044-decision-delegation-contract.proposed.md`) — Framework-Mediated Surface: `<I###>` argument-shape backfill is a typo-class signal resolved by fail-fast + exit (Arguments + Step 1), NOT a user decision. The genuine user-authority asks remain interactive per the 6-class taxonomy: verification-signal + mitigation-attempts pre-flight (cat-2 deviation-approval), problem-handoff + no-problem justification (cat-1 direction-setting). the "alignment audit — sweep all unaudited skills/hooks/agents/ADRs/JTBDs/READMEs against the framework-resolution boundary (master ticket)" problem Phase-remediation surface (mirrors the shipped `mitigate-incident` Surface 1).
+- **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`) — this skill IS the active-restoration path; audit trail invariants preserved post-split.
+- `<itil-plugin-root>/skills/manage-incident/SKILL.md` — hosts the thin-router forwarder for the deprecated `manage-incident <I###> restored` form.
+- `<itil-plugin-root>/skills/mitigate-incident/SKILL.md` — slice 6a precedent; restore-incident mirrors the split shape.
+- `<itil-plugin-root>/skills/manage-problem/SKILL.md` — cross-skill invocation target during problem handoff.
+
+$ARGUMENTS

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Restore Incident"
+  short_description: "Record service restoration and hand off problem work."