@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/skills-codex/reconcile-story-maps/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: wr-itil:reconcile-story-maps
+description: Detect and correct drift between docs/story-maps/README.md and the on-disk story-map HTML inventory. Wraps the diagnose-only <itil-plugin-root>/scripts/reconcile-story-maps.sh script with an agent-applied-edits pattern preserving narrative content.
+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 Story Maps Skill
+
+Sibling to `/wr-itil:reconcile-stories` (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), `/wr-itil:reconcile-rfcs` (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 1 item 5), and `/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), applied at the story-map 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 5.
+
+**Diagnose-only mechanic** — wraps `<itil-plugin-root>/scripts/reconcile-story-maps.sh` via the `<itil-plugin-root>/bin/wr-itil-reconcile-story-maps` `$PATH` shim per the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule. Script reads `docs/story-maps/<state>/STORY-MAP-NNN-*.html` files across 5 lifecycle subdirs (draft, accepted, in-progress, completed, archived), parses `docs/story-maps/README.md`, and reports disagreements. Exit codes: `0` clean, `1` drift detected, `2` parse error.
+
+## When to invoke
+
+- Drift surfaced by another skill's preflight (e.g. `/wr-itil:manage-story-map`).
+- Manual drift recovery (e.g. story-map moved between lifecycle subdirs without README refresh).
+- CI drift gate against merge target.
+
+## Steps
+
+### 1. Run the diagnose script
+
+```bash
+<itil-plugin-root>/bin/wr-itil-reconcile-story-maps docs/story-maps > /tmp/wr-itil-story-maps-drift-$$.txt
+reconcile_exit=$?
+```
+
+Exit 0 → clean; exit 1 → drift to address in Step 2; exit 2 → parse error (halt).
+
+### 2. Read drift entries + plan edits
+
+Each line is one of:
+- `MISSING  STORY-MAP-NNN README claims it exists but no file on disk` — remove README row.
+- `STALE    STORY-MAP-NNN README missing entry; actual=<state>` — add README row.
+
+### 3. Apply edits
+
+Edit `docs/story-maps/README.md` in-place preserving narrative. Use Edit tool with narrow `old_string`/`new_string` pairs targeting only the affected rows.
+
+### 4. Verify + commit
+
+Re-run `<itil-plugin-root>/bin/wr-itil-reconcile-story-maps` (expect exit 0). Stage README + commit per the "Governance Skills Commit Their Own Completed Work" architecture rule single-commit grain.
+
+Commit message: `docs(story-maps): reconcile docs/story-maps/README.md drift (N entries)`.
+
+### 5. Report
+
+Report drift entries reconciled + files modified + commit SHA + trailing pointer to `/wr-itil:manage-story-map review` if any maps crossed lifecycle states during the window.
+
+## Ownership boundary
+
+Detects + mechanically repairs `docs/story-maps/README.md` drift. Does NOT:
+- Move story-map files between lifecycle subdirs (manage-story-map's surface).
+- Edit `<meta>` blocks or `<style>` blocks or HTML body content (manage-story-map's surface).
+- Run WSJF (I5 invariant: no WSJF on story-maps).
+
+## 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 story-map tier.
+- **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — bin/ on PATH.
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — single-commit grain.
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default; bats at `<itil-plugin-root>/scripts/test/reconcile-story-maps.bats`.
+- **the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule** — advisory-exit contract; exit 0 clean / exit 1 drift / exit 2 parse error.
+- **`/wr-itil:reconcile-stories`** — sibling at the story tier.
+- **`/wr-itil:reconcile-rfcs`** — sibling at the RFC tier.
+- **the ": Decompose a Fix Into Coordinated Changes" user outcome** — Decompose a Fix Into Coordinated Changes.
+- **the "Trust That the README Describes the Plugin I Just Installed" user outcome** — Trust That the README Describes the Plugin I Just Installed.
+
+$ARGUMENTS

package/skills-codex/reconcile-story-maps/agents/openai.yaml

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