@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/skills/work-problems/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Work Problems"
+  short_description: "Drain actionable problems with governed Codex subagents."

package/skills-codex/capture-problem/REFERENCE.md

@@ -0,0 +1,139 @@
+# `/wr-itil:capture-problem` Reference
+
+This file hosts the rationale, edge cases, contract trade-offs, and ADR cross-references for the `/wr-itil:capture-problem` skill. SKILL.md is the runtime contract (~150 lines, on-topic per the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule progressive disclosure); this REFERENCE.md is the on-demand expansion for maintainers and curious users.
+
+## Why a separate skill?
+
+The `/wr-itil:manage-problem` flow is ~10 turns of agent work for a full new-problem intake: Step 0 README reconciliation preflight, Step 2 wide-net duplicate grep + request_user_input branch, Step 3 next-ID, Step 4 information-gathering request_user_input, Step 4b multi-concern split request_user_input, Step 5 ticket file write + the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem README refresh, Step 11 commit gate.
+
+That cost is correct for the canonical new-problem path — the user wants to walk the flow, see duplicate-match prompts, and place the ticket in the WSJF ranking immediately.
+
+It is wrong for the **aside-invocation** use case. the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem surfaced three repeating patterns where the heavyweight cost is load-bearing friction:
+
+1. **Mid-AFK-iter sibling-findings**: agent observes a tangential ticket-worthy issue. The 10-turn ceremony breaks iter cadence — observation gets buried in `notes` field of `ITERATION_SUMMARY` and ~50% never reach the backlog.
+2. **User-initiated rapid captures**: user says "btw, this is broken too — capture it". The 10-turn ceremony breaks conversational flow.
+3. **AFK orchestrator main turn captures**: user-driven mid-loop interjections (the "Published skills reference repo-relative script paths — adopter `bash` invocations hard-fail at Step 0" problem / the "No pressure or nudge for keeping documentation up to date — README narrative drifts from package behaviour silently because no gate, hook, or advisory applies pressure on doc-content currency" problem / the "namespace-prefix detector must run against npm pack output not source tree — source-tree advisory misses publish-manifest drift class (broken-shim regression caught only after production ship)" problem in the session that surfaced the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem). Each capture took 5-15 minutes wall-clock through the heavyweight flow.
+
+`/wr-itil:capture-problem` is the source-side fix: a lightweight skill with a deferred-placeholder pattern that captures the observation in ~3-4 turns and routes the deferred re-rating + README refresh through `/wr-itil:review-problems` at a time of the user's choosing.
+
+## Contract trade-offs
+
+### Capture-time false-positives are cheaper than false-negatives
+
+the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem line 24: "capture-time false-positives (creating a duplicate that gets merged later) are cheaper than capture-time false-negatives (losing the observation entirely)."
+
+This is the structural rationale for:
+- **3-keyword cap on the duplicate-grep** — wider grep would surface more matches but force the user to either (a) add an request_user_input branch (which capture-problem doesn't have) or (b) ignore the matches and proceed silently. A 3-keyword cap keeps the match list short and audit-able in the report.
+- **Title-only filename match** — body-content matches would be too noisy at the conservative threshold. Files whose filenames have zero overlap but whose bodies mention a keyword are almost always different tickets that happen to discuss similar topics. False-positive cost would dominate.
+- **No halt-on-match** — even when matches are found, capture proceeds. The duplicate gets resolved at next `/wr-itil:review-problems` (where the full-rank scan can detect and merge actual duplicates with the user in the loop).
+
+### README refresh: inline (the "capture-problem → manage-problem same-session halts at Step 0 reconcile (HALT_ROUTE_RECONCILE on deferred-refresh seam)" problem Option 2 amendment, 2026-06-05)
+
+Capture-problem stages `docs/problems/README.md` inline at Step 6, mirroring `/wr-itil:manage-problem` Step 5 the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem (refresh-on-create) + the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem (last-reviewed rotation). The previously-load-bearing "Deferred-README-refresh contract" was reversed by user direction recorded in the "capture-problem → manage-problem same-session halts at Step 0 reconcile (HALT_ROUTE_RECONCILE on deferred-refresh seam)" problem on 2026-05-31, then implemented on 2026-06-05.
+
+**Rationale for the reversal** (user direction):
+- The "README-refresh enforcement gap — iter subprocess commits can land a `.verifying.md` rename without staging the corresponding Verification Queue row in `docs/problems/README.md`" problem README-refresh-discipline hook (shipped after the initial capture-problem design) blocks every capture commit that does not stage README. The "README-refresh hook conflicts with capture-problem SKILL's deferred-README-refresh contract — hook wins; SKILL needs update OR hook needs carve-out" problem workaround (a `RISK_BYPASS: capture-deferred-readme` trailer) cleared the gate but kept the README transiently stale by design — a contract that always felt half-superseded by the "README-refresh enforcement gap — iter subprocess commits can land a `.verifying.md` rename without staging the corresponding Verification Queue row in `docs/problems/README.md`" problem reality.
+- Option 2 acknowledges reality: stage the README. The cost is one mechanical render-and-stage primitive (already proven in `/wr-itil:manage-problem`); the capture-time speed distinction from manage-problem comes from the wide-net duplicate grep + request_user_input branches that capture-problem skips, not the README skip.
+- The `RISK_BYPASS: capture-deferred-readme` trailer is dropped from emission. The allow-list entry in `packages/itil/hooks/lib/readme-refresh-detect.sh::_README_REFRESH_BYPASS_TRAILERS` is retained as inert dead code for adopter compatibility (minimal-change discipline).
+
+**Trade-off table (post-amendment)**:
+
+| Surface | manage-problem | capture-problem (post-the "capture-problem → manage-problem same-session halts at Step 0 reconcile (HALT_ROUTE_RECONCILE on deferred-refresh seam)" problem) |
+|---------|----------------|------------------------------|
+| README authoritativeness | Always current at commit boundary | Always current at commit boundary |
+| Capture-time turn cost | +1-2 turns (regenerate + stage) | +1-2 turns (same primitive) |
+| WSJF ranking visibility | Immediate (deferred-placeholder row) | Immediate (deferred-placeholder row) |
+| Audit trail (commit) | One commit covers ticket + README | One commit covers ticket + README |
+| README staleness window | None | None |
+| Distinguishing cost shape | Wide-net duplicate grep + multi-request_user_input branches | Title-only 3-keyword grep + zero request_user_input |
+
+The on-disk ticket inventory remains the source of truth; `/wr-itil:list-problems` cache-stale fallback re-derives directly from ticket files when needed.
+
+### No request_user_input at all
+
+Architect Q4 + JTBD review confirmed: capture-problem is a **mechanical-stage skill** per the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule's framework-resolution boundary. Every potentially-interactive decision is framework-mediated:
+
+- **Duplicate-check**: false-positive bias > false-negative bias. Mechanical rule: list matches, proceed regardless.
+- **Priority**: framework-policy default `3 (Medium) — Impact 3 × Likelihood 1`, flagged for re-rate. Re-rating is mandatory before the ticket is worked, so no ticket gets ranked on a wrong default.
+- **Effort**: framework-policy default `M`, flagged for re-rate. Same re-rating contract as Priority.
+- **Multi-concern split**: out of scope. The user invoking capture-problem with a multi-concern observation gets one ticket with the full description as the body; they re-route to `/wr-itil:manage-problem` for the structured split.
+
+This mirrors the mechanical-stage carve-out pattern documented in CLAUDE.md (the "Agents over-ask in interactive sessions — conflating mechanical-stages with user-interactive-stages of multi-stage skill contracts (inverse-)" problem / inverse-the "Problem 078: Assistant does not offer to capture a problem ticket when the user delivers strong-signal correction" problem trap): when a SKILL contract names a stage as mechanical, do not ask. Per-action consent gates re-ask decisions the user already made and silently undo the load-bearing UX investment.
+
+## Edge cases
+
+### Empty `$ARGUMENTS`
+
+Halt-with-stderr-directive. capture-problem requires a description; without one there is nothing to capture. The directive points the user to `/wr-itil:manage-problem`, which has Step 4 request_user_input gathering for missing fields.
+
+AFK orchestrators MUST NOT invoke capture-problem with empty arguments — caller-side contract. The Rule 6 audit makes this explicit so AFK-iter writers don't accidentally introduce a halt mid-loop.
+
+### Description is a kebab-stopword soup
+
+If the description's first 8-10 tokens are entirely stopwords (e.g. "the and of to in"), the slug derivation falls back to the full description hash modulo a short integer. The resulting slug is non-meaningful but unique; the user re-titles at next investigation.
+
+This is a degenerate case — real captures carry meaningful first-tokens — but the fallback prevents a malformed empty-slug filename.
+
+### ID collision with origin
+
+The next-ID formula uses `git ls-tree origin/main` to read the remote-tracking ref without requiring a fetch. If a parallel session minted the same ID for a different problem and pushed it before this session captures, the local read sees the higher origin ID and increments past it.
+
+If the local session has not fetched recently and origin has captures the local doesn't see, the formula may still collide. The renumber audit log line in Step 7 captures the resolution. the "Problem 040: work-problems does not fetch origin before starting" problem incident applies.
+
+### Cross-skill marker ordering
+
+The `/tmp/manage-problem-grep-${SESSION_ID}` create-gate marker is shared between `manage-problem` and `capture-problem`. Whichever fires first writes the marker; subsequent calls are idempotent (`: > FILE`).
+
+This means a session that does `manage-problem` once then `capture-problem` three times has the marker set after the first manage-problem grep, and all three captures land without re-running the grep + mark sequence. capture-problem still runs its own minimal-grep in Step 2 (because the conservative threshold + report-listing is part of the contract), but the marker write is a no-op.
+
+### the "Problem 057: `git mv` + Edit + `git add` staging-ordering trap drops content edits from the commit" problem staging-trap
+
+Not applicable. capture-problem only Writes a new file; it does not `git mv` an existing one. The "Problem 057: `git mv` + Edit + `git add` staging-ordering trap drops content edits from the commit" problem rule (re-stage after Edit on a `git mv`-d file) is irrelevant to this skill.
+
+### Multi-concern descriptions
+
+If the user supplies a multi-concern description (e.g. "checkout flow leaks tokens AND the price calculator rounds wrong"), capture-problem creates ONE ticket with both observations in the description body. Re-routing to `/wr-itil:manage-problem` for the structured split (Step 4b) is a deliberate design choice — the heavyweight flow owns the multi-concern decision because the split prompt requires user input to confirm boundaries.
+
+The user can manually `/wr-itil:manage-problem <NNN>` later to split a captured multi-concern ticket if needed.
+
+## Composition with the rest of the suite
+
+### `/wr-itil:review-problems`
+
+Handles the deferred re-rating + README refresh. Step 9b's auto-transition pass keys off the deferred-placeholder string and surfaces captured tickets for re-rating. The README refresh in Step 9e regenerates the table covering all captured-but-not-rated tickets in one pass.
+
+### `/wr-itil:manage-problem`
+
+Heavyweight intake counterpart. Shares the create-gate marker with capture-problem. The two skills are designed to coexist — neither supersedes the other. A user who starts with capture-problem and decides they want the structured intake flow re-invokes manage-problem on the captured ticket ID to flesh out the placeholders.
+
+### `/wr-itil:work-problems` (AFK orchestrator)
+
+Iter subprocesses can invoke capture-problem to capture sibling-findings without breaking iter cadence. The AFK carve-out in the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule (line 85) excludes the **background-capture** variant from AFK contexts; the **foreground-lightweight-capture** variant introduced by this skill is fine inside iter subprocesses because it has no `Agent(run_in_background: true)` invocation — it's a normal foreground-synchronous skill that happens to do less work than manage-problem.
+
+### `/wr-itil:capture-problem` callers
+
+The intended invocation surface is `/wr-itil:capture-problem <description>`. The description must be a non-empty free-text payload; the skill does not branch on description shape.
+
+## Related ADRs
+
+- **the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule** — gate-marker-lifecycle (per-session /tmp markers; capture-problem reuses the manage-problem marker).
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule** — structured user interaction (Rule 6 fail-safe; capture-problem has no request_user_input branches so Rule 6 is trivially satisfied).
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — governance skills commit their own work (capture-problem owns its commit).
+- **the "Problem lifecycle — add a Verification Pending status between Known Error and Closed" architecture rule** — verification-pending status (out of scope for capture-problem; status transitions live in transition-problem).
+- **the "Problem-ticket directory layout — per-state subdirectories under `docs/problems/`" architecture rule** — problem-ticket directory layout (capture-problem matches current flat-layout production reality; auto-migration is a future the "Problem-ticket directory layout — per-state subdirectories under `docs/problems/`" architecture rule follow-up).
+- **the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule** — governance skill invocation patterns (this skill's parent ADR; foreground-lightweight-capture variant amendment 2026-05-03).
+- **the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule** — progressive disclosure (SKILL.md + REFERENCE.md split shape).
+- **the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
+- **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — bin/ on PATH (capture-problem reuses existing `wr-itil-reconcile-readme` shim; no new shim).
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests-default for skill testing (capture-problem's bats fixtures exercise primitives, not SKILL.md prose).
+
+## Related problems
+
+- **the "Problem 014: No lightweight aside invocation for governance skills (problems, retros, ADRs)" problem** — parent / master tracker.
+- **the "Problem 078: Assistant does not offer to capture a problem ticket when the user delivers strong-signal correction" problem** — capture-on-correction OFFER; depends on capture-problem.
+- **the "Problem 088: run-retro cannot see the full session context when invoked as a subagent, subprocess, or from any non-parent-session surface — 's fix is partially blind" problem** — settled the user-direction-scoped decision: capture-problem + capture-adr are shippable; capture-retro is deferred.
+- **the "Agent bypasses `/wr-itil:manage-problem` Step 2 duplicate-check by writing tickets directly to `docs/problems/`" problem** — manage-problem create-gate; capture-problem composes with the same marker.
+- **the "Agent defers ticket creation to retro summary "Tickets Deferred" section instead of immediately invoking `/wr-itil:manage-problem` — observations could be lost if user is in a rush" problem** — Tickets Deferred retro section (legacy when capture-problem ships).
+- **the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem** — driver ticket.
+- **the "Ship `/wr-architect:capture-adr` skill — lightweight aside-invocation surface for ADR capture during foreground work" problem** — sibling capture-adr.
+- **the "Ship pending-questions-surface hook — auto-surface accumulated `outstanding_questions` from `.afk-run-state/outstanding-questions.jsonl` at session start when user returns interactive" problem** — sibling pending-questions-surface hook.