@windyroad/itil 0.4.4 → 0.4.5-preview.109

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-itil",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "ITIL-aligned IT service management for Claude Code"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.4.4",
+  "version": "0.4.5-preview.109",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/skills/manage-problem/SKILL.md

@@ -65,7 +65,8 @@ Problems are ranked using Weighted Shortest Job First (WSJF):
 |--------|---------|-------------|
 | S | 1 | < 1 hour, single file, quick fix |
 | M | 2 | 1-4 hours, few files, moderate change |
-| L | 4 | > 4 hours, multiple files, significant change |
+| L | 4 | 4 hours – 1 day, multiple files, significant change within a single plugin |
+| XL | 8 | > 1 day, multi-day or cross-package work (multiple plugins, migration, new ADR required) |
 
 **Example**: A Known Error with severity 8 (Impact 4 × Likelihood 2) and Small effort:
 WSJF = (8 × 2.0) / 1 = **16.0** — do this first.
@@ -73,7 +74,10 @@ WSJF = (8 × 2.0) / 1 = **16.0** — do this first.
 An Open problem with severity 6 (Impact 3 × Likelihood 2) and Large effort:
 WSJF = (6 × 1.0) / 4 = **1.5** — lower priority despite medium severity.
 
-When estimating effort, read the problem's root cause analysis and fix strategy. If effort is unknown, default to M (2).
+An Open problem with severity 8 (Impact 2 × Likelihood 4) and Extra-Large effort (multi-day, cross-package):
+WSJF = (8 × 1.0) / 8 = **1.0** — defer until severity climbs or scope shrinks.
+
+When estimating effort, read the problem's root cause analysis and fix strategy. If effort is unknown, default to M (2). Effort is a **live estimate**, not a set-once label: re-rate it when root cause is confirmed, when architect review narrows or expands scope, and during each `manage-problem review`. A note capturing the reason for any bucket change makes the ranking audit-able (see steps 7 and 9b).
 
 ## Working a Problem
 
@@ -252,6 +256,7 @@ Pre-flight checks before allowing transition:
 - [ ] At least one investigation task is checked off
 - [ ] A reproduction test exists or is referenced
 - [ ] A workaround is documented (even if "feature disabled")
+- [ ] Effort bucket re-rated against the now-documented fix strategy; if the bucket changed since creation, update the Effort / WSJF lines and note the reason (P047 — creation-time estimates drift as scope clarifies)
 
 If any check fails, report which checks failed and ask the user to address them before transitioning.
 
@@ -306,7 +311,7 @@ Parked problems are excluded from WSJF ranking — do not read, score, or update
 4. **Re-assess Likelihood** (1-5) using the likelihood levels from RISK-POLICY.md. Ask: "Given the current codebase, how likely is this to affect the user?"
 5. **Calculate Severity** = Impact × Likelihood
 6. **Look up Label** from the risk matrix label bands
-7. **Estimate Effort** (S/M/L) by reading the root cause analysis and fix strategy. Consider: how many files, how complex, does it need planning?
+7. **Re-estimate Effort** (S / M / L / XL) by reading the root cause analysis and fix strategy. Consider: how many files, how complex, does it need planning, is it cross-package or migration-heavy (XL territory)? If the bucket has changed since last review, update the Effort line in the problem file and note the reason in a short parenthetical (e.g. "L → XL — architect review added ADR + migration script"). P047.
 8. **Calculate WSJF** = (Severity × Status Multiplier) / Effort Divisor
 9. **Update the Priority line** in the problem file if the score changed
 10. **Auto-transition to Known Error**: If an open problem has confirmed root cause AND a workaround documented (even "feature disabled"), automatically transition it to known-error:

package/skills/manage-problem/test/manage-problem-effort-buckets.bats

@@ -0,0 +1,56 @@
+#!/usr/bin/env bats
+# Doc-lint guard: manage-problem SKILL.md must define the XL effort bucket
+# and require effort re-rating at lifecycle transitions.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that the skill specification document conforms to the
+# effort-bucket and re-rating contract introduced by P047.
+#
+# Cross-reference:
+#   P047: docs/problems/047-wsjf-effort-bucket-accuracy-gaps.open.md
+#   @jtbd JTBD-006 (Progress the Backlog While I'm Away — finer ranking signal)
+#   @jtbd JTBD-101 (Extend the Suite with Clear Patterns — consistent WSJF semantics)
+#   @jtbd JTBD-001 (Enforce Governance Without Slowing Down — explicit re-rate audit trail)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md effort table includes an XL bucket with divisor 8" {
+  # P047 concern (2): the L bucket is open-ended (>4 hours, no upper bound),
+  # so multi-day / multi-week work ranks identically to a 4-hour L task.
+  # The XL bucket disambiguates the top end of the effort spectrum.
+  run grep -En "^\|\s*XL\s*\|\s*8\s*\|" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md step 7 pre-flight checks effort bucket re-rating" {
+  # P047 concern (1): effort is set at problem creation and never re-rated.
+  # Step 7 (Open → Known Error transition) must prompt the reviewer to
+  # re-evaluate the effort bucket against the now-documented fix strategy.
+  # Match tight phrasings that can only appear in the new pre-flight item,
+  # not incidental co-occurrences on a summary line.
+  run grep -inE "effort bucket (reviewed|re-?rated|re-?assessed|re-?estimated)|re-?(rate|estimate|assess)( the)? effort bucket" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md step 9b requires explicit effort re-estimation with reason" {
+  # P047 candidate fix (2): step 9b's effort re-rate is implicit today
+  # ("Estimate Effort"). The explicit form ("Re-estimate Effort; if the
+  # bucket changed since last review, update the file and note the reason")
+  # makes the check unmissable and leaves an audit trail.
+  run grep -in "re-estimate effort\|re.estimate effort" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  # The note-the-reason phrase must appear near the re-estimate instruction
+  run grep -inE "note.*reason|reason.*noted|note the reason" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md XL bucket description names its scope as multi-day / cross-package" {
+  # P047 scoping: XL must be unambiguously wider than L. The description
+  # should reference multi-day or cross-package to distinguish it from L's
+  # "> 4 hours, multiple files, significant change".
+  run grep -inE "XL.*(multi.?day|multi-?week|cross-?package|multi-?package)" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/work-problems/SKILL.md

@@ -83,7 +83,7 @@ Read the problem file and apply these deterministic rules:
 
 The default is to work the problem. Only skip when the rule explicitly says so. This is an AFK loop — forward progress matters more than avoiding dead ends, because dead ends are cheap (findings are saved) and interactive input is expensive (user is absent).
 
-**Time-box each problem** to avoid runaway investigation: the delegated `manage-problem` skill's internal logic decides scope. If investigation reveals the scope has grown (e.g., effort was estimated S but turns out to be L), save findings to the problem file, update the WSJF score, and move to the next problem. Never sink unbounded effort into one problem during AFK mode.
+**Time-box each problem** to avoid runaway investigation: the delegated `manage-problem` skill's internal logic decides scope. If investigation reveals the scope has grown (e.g., effort was estimated S but turns out to be L or XL), save findings to the problem file, update the WSJF score, and move to the next problem. Never sink unbounded effort into one problem during AFK mode.
 
 If a problem is skipped by this step, add it to a "skipped" list with the reason and loop back to step 3 for the next one.
 
@@ -163,7 +163,7 @@ When `AskUserQuestion` is unavailable or the user is AFK, the skill (and the del
 
 **Review needed first**: If no problems have WSJF scores, run `/wr-itil:manage-problem review` as the first iteration to score everything, then proceed to the work loop.
 
-**Scope creep during investigation**: If investigating an open problem reveals the scope is larger than expected (effort re-sized from S to L), save findings to the problem file, update the WSJF score, and move to the next problem. Don't sink unlimited effort into one problem during AFK mode — the user can decide when they return.
+**Scope creep during investigation**: If investigating an open problem reveals the scope is larger than expected (effort re-sized from S to L, or L to XL), save findings to the problem file, update the WSJF score, and move to the next problem. Don't sink unlimited effort into one problem during AFK mode — the user can decide when they return.
 
 **Circular work**: If the same problem keeps appearing as highest-WSJF across iterations without making progress, skip it after the second attempt and note it as "stuck — needs interactive attention".