@windyroad/retrospective 0.1.5 → 0.1.6-preview.104

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-retrospective",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Session retrospective reminders and plan review for Claude Code"
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/retrospective",
-  "version": "0.1.5",
+  "version": "0.1.6-preview.104",
   "description": "Session retrospectives that update briefings and create problem tickets",
   "bin": {
     "windyroad-retrospective": "./bin/install.mjs"

package/skills/run-retro/SKILL.md

@@ -28,6 +28,13 @@ Consider the work done in this session and identify:
 
 **What should we make easier or automate** — repetitive manual steps, missing tooling, things that could be scripted. These should become problem tickets via the `/problem` skill.
 
+**What recurring workflow did I (or the assistant) perform that would be better as a skill?** — multi-step sequences that (a) were invoked multiple times in one session, (b) have a deterministic action order, and (c) are reusable across projects, not project-specific logic. These are **skill candidates**, not problem tickets, and route through Step 4b below.
+
+Examples of skill candidates vs problem tickets:
+- `fetch origin → check changesets → score risk → commit → push → release → sync manifest → mark Fix Released` — deterministic, recurring, cross-project → **skill candidate** (e.g. `wr-itil:ship-fix`).
+- "The commit gate rejected my work twice because X was misconfigured" — diagnostic, project-specific → **problem ticket**.
+- "I always forget to run `npm run verify` before pushing" — short, user-habit rather than codifiable sequence → **BRIEFING.md** note, not a skill.
+
 ### 3. Update BRIEFING.md
 
 Edit `docs/BRIEFING.md`:
@@ -50,6 +57,32 @@ For each item identified in "What was harder than it should have been", "What fa
 - If yes: update it with new evidence from this session
 - If no: create a new problem ticket
 
+### 4b. Recommend new skills
+
+For each **skill candidate** identified in Step 2, route the decision through `AskUserQuestion`. This is the ADR-013 Rule 1 structured-interaction pattern — do not present the choices as prose enumeration in the skill output.
+
+For each candidate, invoke `AskUserQuestion` with:
+- `header: "Skill candidate"`
+- `multiSelect: false`
+- Three options:
+  1. `Create a new skill` — description: "Scaffold a new skill for this recurring workflow. Requires suggested name, scope, and triggers — Step 4b records them for a future scaffolding flow to pick up."
+  2. `Track as a problem ticket instead` — description: "File the candidate via /wr-itil:manage-problem so it can be planned and WSJF-ranked alongside other backlog items."
+  3. `Skip — not skill-worthy` — description: "Neither create nor track. The candidate is too small, too ambiguous, or too project-specific to codify."
+
+When the user chooses **Create a new skill**, record a candidate entry with:
+- **Suggested skill name** (e.g. `wr-itil:ship-fix`) — kebab-case, namespaced to the owning plugin
+- **Scope** — one sentence on what the skill does and when it should fire
+- **Triggers** — example user prompts that should invoke it
+- **Prior uses** — 2-3 observed invocations from this session
+
+Store the candidate entry in the Step 5 summary under "Skill Candidates". Skill scaffolding itself is out of scope for this retrospective — scaffolding may land in a future skill (see P012 skill testing harness for the testing side of that).
+
+When the user chooses **Track as a problem ticket**, fall through to the Step 4 flow with a "this should be a skill" note in the ticket description.
+
+When the user chooses **Skip**, record the candidate in the Step 5 summary under "Skill Candidates" with a `skipped` marker so the pattern is still visible in the session audit trail.
+
+**Non-interactive fallback (per ADR-013 Rule 6):** if `AskUserQuestion` is unavailable, record each candidate in the Step 5 summary under "Skill Candidates" with a `flagged — not actioned (non-interactive)` marker and do not create tickets or scaffold. The user can review the flags and decide when they return.
+
 ### 5. Summary
 
 Present a summary to the user:
@@ -65,8 +98,13 @@ Present a summary to the user:
 ### Problems Created/Updated
 - [problem ticket]: [summary]
 
+### Skill Candidates
+- [suggested name] — [scope]. Triggers: [examples]. Decision: [created / tracked as P<NNN> / skipped / flagged (non-interactive)].
+
 ### No Action Needed
 - [learnings that were already captured]
 ```
 
+If the "Skill Candidates" section is empty, omit it rather than rendering an empty header.
+
 $ARGUMENTS

package/skills/run-retro/test/run-retro-skill-candidates.bats

@@ -0,0 +1,94 @@
+#!/usr/bin/env bats
+# Doc-lint guard: run-retro SKILL.md must include the skill-recommendation branch.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests do not assert hook behaviour; they assert that the skill specification
+# document includes the skill-candidate branch added in P044.
+#
+# Cross-reference:
+#   P044 (docs/problems/044-run-retro-does-not-recommend-new-skills.known-error.md)
+#   ADR-013 Rule 1 / Rule 6 (docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+#   @jtbd JTBD-101 (extend the suite with clear patterns)
+
+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 Step 2 includes the skill-candidate reflection category (P044)" {
+  # P044 fix: Step 2 must prompt for recurring workflows that would be better as skills.
+  # Regression guard: if Step 2 is rewritten and the skill-candidate prompt is dropped,
+  # this test fails.
+  run grep -n "recurring workflow.*better as a skill\|would be better as a skill" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md includes a Step 4b Recommend new skills branch (P044)" {
+  # P044 fix: a dedicated output branch for skill candidates, distinct from Step 4
+  # (problem tickets) and Step 5 (summary).
+  run grep -n "Recommend new skills\|Step 4b" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b uses AskUserQuestion (ADR-013 Rule 1)" {
+  # ADR-013 Rule 1: the skill-candidate decision branch must use AskUserQuestion,
+  # not prose '(a)/(b)/(c)' enumeration. Architect review flagged this as the
+  # gotcha to avoid when implementing P044.
+  run grep -n "AskUserQuestion" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b header matches ADR-013 structured-interaction pattern" {
+  # Header: "Skill candidate" identifies the AskUserQuestion call site and is what
+  # other tests / review tooling can grep for.
+  run grep -n "Skill candidate" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b names the three structured options (P044)" {
+  # The three decision options must be explicit: create, track, skip.
+  run grep -n "Create a new skill" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -n "Track as a problem ticket" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -n "Skip — not skill-worthy\|Skip - not skill-worthy" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b has non-interactive fallback per ADR-013 Rule 6" {
+  # ADR-013 Rule 6: if AskUserQuestion is unavailable, flag candidates instead of
+  # silently choosing. P044 implementation uses "flagged — not actioned" wording.
+  run grep -n "non-interactive\|Rule 6" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 summary template has a Skill Candidates slot (P044)" {
+  # P044 fix: the summary template must include a Skill Candidates section so
+  # recommendations are visible in the session audit alongside BRIEFING changes
+  # and problem tickets.
+  run grep -n "### Skill Candidates" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md does not contain 'Options: (a)' prose option list (ADR-013)" {
+  # ADR-013 Rule 1: user-facing decisions must use AskUserQuestion, not prose
+  # "Options: (a)/(b)/(c)". This matches the narrow pattern used by
+  # manage-problem-no-prose-options.bats so criteria lists using (a)/(b)/(c)
+  # as internal enumeration (which are fine) don't trip the test.
+  run grep -n "Options: (a)" "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "SKILL.md does not contain 'Your call:' prose option prompt (ADR-013)" {
+  # ADR-013 Rule 1: mirrors the manage-problem regression guard.
+  run grep -n "Your call:" "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}