diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cf02218..5699e8e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "ralph-specum", "description": "Spec-driven development with research, requirements, design, tasks, and autonomous execution. Fresh context per task.", - "version": "4.1.2", + "version": "4.2.0", "author": { "name": "tzachbon" }, diff --git a/plugins/ralph-specum/.claude-plugin/plugin.json b/plugins/ralph-specum/.claude-plugin/plugin.json index 4f0a16b..9347436 100644 --- a/plugins/ralph-specum/.claude-plugin/plugin.json +++ b/plugins/ralph-specum/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "ralph-specum", - "version": "4.1.2", + "version": "4.2.0", "description": "Spec-driven development with task-by-task execution. Research, requirements, design, tasks, and autonomous implementation with fresh context per task.", "author": { "name": "tzachbon" diff --git a/plugins/ralph-specum/commands/start.md b/plugins/ralph-specum/commands/start.md index 18eaa35..f4c17dd 100644 --- a/plugins/ralph-specum/commands/start.md +++ b/plugins/ralph-specum/commands/start.md @@ -36,9 +36,42 @@ Read `${CLAUDE_PLUGIN_ROOT}/references/intent-classification.md` and follow the ### Quick Mode Check -If `--quick` flag detected in $ARGUMENTS, skip to **Step 5: Quick Mode Flow**. +If `--quick` flag detected in $ARGUMENTS, skip to **Step 6: Quick Mode Flow**. + +## Step 3: Skill Discovery Pass 1 + +> **Normal mode only** -- quick mode skips to Step 6 and never reaches this step. Quick mode gets its own Pass 1 in quick-mode.md. + +Scan all skill files and match against the goal text: + +1. Read each `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` file's YAML frontmatter (`name`, `description` fields) + - If a SKILL.md is unreadable (file error, permissions): skip that skill, log warning + - If a SKILL.md has no `description` field in frontmatter: skip that skill, log "no description" +2. Determine **context text**: the goal text only (from Step 2) +3. Tokenize both context text and each skill's `description` using these rules: + a. Lowercase the entire string + b. Replace hyphens with spaces ("brainstorming-style" -> "brainstorming style") + c. Strip all punctuation (parentheses, commas, periods, colons, quotes, brackets, etc.) + d. Split on whitespace into word tokens + e. Remove stopwords: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about +4. Count word overlap between context tokens and description tokens +5. If overlap >= 2 AND skill not already in `discoveredSkills` with `invoked: true`: + - Invoke: `Skill({ skill: "ralph-specum:" })` + - On success: add `{ name, matchedAt: "start", invoked: true }` to `discoveredSkills` + - On failure: set `invoked: false` -- add `{ name, matchedAt: "start", invoked: false }`, log warning, continue +6. If no skills match across all scanned skills: log `- No skills matched` +7. Update `.ralph-state.json` with updated `discoveredSkills` array +8. Append a `## Skill Discovery` section to `.progress.md` with match details per skill: + ```markdown + ## Skill Discovery + - ****: matched (keywords: ) + - ****: no match + - ****: skipped (unreadable) + - ****: skipped (no description) + ``` + If no skills match: `- No skills matched` -## Step 3: Scan Existing Specs +## Step 4: Scan Existing Specs Read `${CLAUDE_PLUGIN_ROOT}/references/spec-scanner.md` and follow the scanning algorithm and index hint logic. @@ -48,7 +81,7 @@ Read `${CLAUDE_PLUGIN_ROOT}/references/spec-scanner.md` and follow the scanning **Summary**: Scans ./specs/ directory (and all configured specs_dirs) for related specs using keyword matching. Displays related specs with relevance scores. Shows index hint if codebase indexing not yet done. Stores relatedSpecs in .ralph-state.json for use during interview. -## Step 4: Route to Action +## Step 5: Route to Action Based on detection logic from Step 2: @@ -97,14 +130,48 @@ Continuing... "phase": "research", "taskIndex": 0, "totalTasks": 0, "taskIteration": 1, "maxTaskIterations": 5, "globalIteration": 1, "maxGlobalIterations": 100, - "commitSpec": true, "quickMode": false + "commitSpec": true, "quickMode": false, + "discoveredSkills": [] } ``` 8. Create `.progress.md` with goal 9. Update Spec Index: `./plugins/ralph-specum/hooks/scripts/update-spec-index.sh --quiet` 10. **Goal Interview** -- Read `${CLAUDE_PLUGIN_ROOT}/references/goal-interview.md` and follow brainstorming dialogue 11. **Team Research Phase** -- Read `${CLAUDE_PLUGIN_ROOT}/references/parallel-research.md` and follow the dispatch pattern -12. **STOP** -- After merge and state update (awaitingApproval=true), display walkthrough and wait for user +12. **Skill Discovery Pass 2 (Post-Research Retry)** -- Re-scan skills with enriched context after research completes: + + ### Skill Discovery Pass 2 + + Scan all skill files and match against goal + research context: + + 1. Read each `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` file's YAML frontmatter (`name`, `description` fields) + - If a SKILL.md is unreadable (file error, permissions): skip that skill, log warning + - If a SKILL.md has no `description` field in frontmatter: skip that skill, log "no description" + 2. Determine **context text**: goal text + the **Executive Summary** section from `research.md` + 3. Tokenize both context text and each skill's `description` using these rules: + a. Lowercase the entire string + b. Replace hyphens with spaces ("brainstorming-style" -> "brainstorming style") + c. Strip all punctuation (parentheses, commas, periods, colons, quotes, brackets, etc.) + d. Split on whitespace into word tokens + e. Remove stopwords: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about + 4. Count word overlap between context tokens and description tokens + 5. If overlap >= 2 AND skill not already in `discoveredSkills` with `invoked: true`: + - Invoke: `Skill({ skill: "ralph-specum:" })` + - On success: add `{ name, matchedAt: "post-research", invoked: true }` to `discoveredSkills` + - On failure: set `invoked: false` -- add `{ name, matchedAt: "post-research", invoked: false }`, log warning, continue + 6. If no skills match across all scanned skills: log `- No skills matched` + 7. Update `.ralph-state.json` with updated `discoveredSkills` array + 8. Append a `### Post-Research Retry` subsection to `.progress.md` under `## Skill Discovery`: + ```markdown + ### Post-Research Retry + - ****: matched (keywords: ) + - ****: no match (already invoked) + - ****: skipped (unreadable) + - ****: skipped (no description) + ``` + If no new skills match: `- No new skills matched` + +13. **STOP** -- After merge and state update (awaitingApproval=true), display walkthrough and wait for user ### Research Walkthrough (Normal Mode Only) @@ -133,7 +200,7 @@ Then STOP. Output: `-> Next: Run /ralph-specum:requirements` End response immediately. -## Step 5: Quick Mode Flow +## Step 6: Quick Mode Flow Read `${CLAUDE_PLUGIN_ROOT}/references/quick-mode.md` and follow the full quick mode execution sequence. diff --git a/plugins/ralph-specum/references/quick-mode.md b/plugins/ralph-specum/references/quick-mode.md index 38e9352..d1dd125 100644 --- a/plugins/ralph-specum/references/quick-mode.md +++ b/plugins/ralph-specum/references/quick-mode.md @@ -72,29 +72,93 @@ Validation Sequence: taskIndex: 0, totalTasks: 0, taskIteration: 1, maxTaskIterations: 5, globalIteration: 1, maxGlobalIterations: 100, commitSpec: $commitSpec, - quickMode: true } + quickMode: true, discoveredSkills: [] } 6. Write .progress.md with original goal 7. Update .current-spec (bare name or full path) 8. Update Spec Index: ./plugins/ralph-specum/hooks/scripts/update-spec-index.sh --quiet -9. Goal Type Detection: - - Classify as "fix" or "add" using regex indicators - - Fix: fix|resolve|debug|broken|failing|error|bug|crash|issue|not working - - Add: add|create|build|implement|new|enable|introduce (default) - - For fix goals: run reproduction, document BEFORE state -10. Research Phase: run Team Research flow (skip walkthrough), clear awaitingApproval -11. Requirements Phase: delegate to product-manager with Quick Mode Directive, review loop -12. Design Phase: delegate to architect-reviewer with Quick Mode Directive, review loop -13. Tasks Phase: delegate to task-planner with Quick Mode Directive, review loop -14. Transition to Execution: +9. Skill Discovery Pass 1: scan skills, match against goal text, invoke matches +10. Goal Type Detection: + - Classify as "fix" or "add" using regex indicators + - Fix: fix|resolve|debug|broken|failing|error|bug|crash|issue|not working + - Add: add|create|build|implement|new|enable|introduce (default) + - For fix goals: run reproduction, document BEFORE state +11. Research Phase: run Team Research flow (skip walkthrough), clear awaitingApproval +12. Skill Discovery Pass 2: re-scan skills using goal + research Executive Summary, invoke new matches +13. Requirements Phase: delegate to product-manager with Quick Mode Directive, review loop +14. Design Phase: delegate to architect-reviewer with Quick Mode Directive, review loop +15. Tasks Phase: delegate to task-planner with Quick Mode Directive, review loop +16. Transition to Execution: - Count total tasks (number of `- [ ]` checkboxes) - Update state: phase="execution", totalTasks=, taskIndex=0 - If commitSpec: stage, commit, push spec files -15. Invoke spec-executor for task 1 +17. Invoke spec-executor for task 1 ``` +## Step 9: Skill Discovery Pass 1 + +Scan all skill files and match against the goal text: + +1. Read each `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` file's YAML frontmatter (`name`, `description` fields) + - If a SKILL.md is unreadable (file error, permissions): skip that skill, log warning + - If a SKILL.md has no `description` field in frontmatter: skip that skill, log "no description" +2. Determine **context text**: the goal text only (from step 1) +3. Tokenize both context text and each skill's `description` using these rules: + a. Lowercase the entire string + b. Replace hyphens with spaces ("brainstorming-style" -> "brainstorming style") + c. Strip all punctuation (parentheses, commas, periods, colons, quotes, brackets, etc.) + d. Split on whitespace into word tokens + e. Remove stopwords: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about +4. Count word overlap between context tokens and description tokens +5. If overlap >= 2 AND skill not already in `discoveredSkills` with `invoked: true`: + - Invoke: `Skill({ skill: "ralph-specum:" })` + - On success: add `{ name, matchedAt: "start", invoked: true }` to `discoveredSkills` + - On failure: set `invoked: false` -- add `{ name, matchedAt: "start", invoked: false }`, log warning, continue +6. If no skills match across all scanned skills: log `- No skills matched` +7. Update `.ralph-state.json` with updated `discoveredSkills` array +8. Append a `## Skill Discovery` section to `.progress.md` with match details per skill: + ```markdown + ## Skill Discovery + - ****: matched (keywords: ) + - ****: no match + - ****: skipped (unreadable) + - ****: skipped (no description) + ``` + If no skills match: `- No skills matched` + +## Step 12: Skill Discovery Pass 2 (Post-Research Retry) + +Re-scan skills with enriched context after research completes: + +1. Read each `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` file's YAML frontmatter (`name`, `description` fields) + - If a SKILL.md is unreadable (file error, permissions): skip that skill, log warning + - If a SKILL.md has no `description` field in frontmatter: skip that skill, log "no description" +2. Determine **context text**: goal text + the **Executive Summary** section from `research.md` +3. Tokenize both context text and each skill's `description` using these rules: + a. Lowercase the entire string + b. Replace hyphens with spaces ("brainstorming-style" -> "brainstorming style") + c. Strip all punctuation (parentheses, commas, periods, colons, quotes, brackets, etc.) + d. Split on whitespace into word tokens + e. Remove stopwords: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about +4. Count word overlap between context tokens and description tokens +5. If overlap >= 2 AND skill not already in `discoveredSkills` with `invoked: true`: + - Invoke: `Skill({ skill: "ralph-specum:" })` + - On success: add `{ name, matchedAt: "post-research", invoked: true }` to `discoveredSkills` + - On failure: set `invoked: false` -- add `{ name, matchedAt: "post-research", invoked: false }`, log warning, continue +6. If no skills match across all scanned skills: log `- No skills matched` +7. Update `.ralph-state.json` with updated `discoveredSkills` array +8. Append a `### Post-Research Retry` subsection to `.progress.md` under `## Skill Discovery`: + ```markdown + ### Post-Research Retry + - ****: matched (keywords: ) + - ****: no match (already invoked) + - ****: skipped (unreadable) + - ****: skipped (no description) + ``` + If no new skills match: `- No new skills matched` + ## Quick Mode Directive -Each agent delegation in steps 10-13 includes this directive in the Task prompt: +Each agent delegation in steps 11-15 includes this directive in the Task prompt: ```text Quick Mode Context: @@ -109,7 +173,7 @@ Running in quick mode with no user feedback. You MUST: ## Quick Mode Review Loop (Per Artifact) -After each phase agent returns in steps 11-13, run spec-reviewer to validate: +After each phase agent returns in steps 13-15, run spec-reviewer to validate: ```text Set iteration = 1 diff --git a/specs/smart-skill-swap-retry/.progress.md b/specs/smart-skill-swap-retry/.progress.md new file mode 100644 index 0000000..088012a --- /dev/null +++ b/specs/smart-skill-swap-retry/.progress.md @@ -0,0 +1,206 @@ +# Progress: smart-skill-swap-retry + +## Goal +I want that on smart start it will try to look for and swap every skill it deems necessary, and also retry it after research if it missed something. + +## Goal Type +- Type: add (enhance existing feature) + +## Completed Tasks +- [x] 1.1 Add discoveredSkills to state initialization in start.md (normal mode) +- [x] 1.2 Add discoveredSkills to state initialization in quick-mode.md +- [x] 1.3 Add Skill Discovery Pass 1 to start.md (normal mode, Step 2.5) +- [x] 1.5 Add Skill Discovery Pass 2 to start.md (normal mode, post-research) +- [x] 1.6 Add Skill Discovery Pass 1 to quick-mode.md (Step 8.5) +- [x] 1.8 Add Skill Discovery Pass 2 to quick-mode.md (Step 10.5) +- [x] 1.9 Add error handling instructions to both discovery passes + +## Completed Tasks (Phase 2) +- [x] 2.1 Ensure tokenization rules are identically worded in all 4 passes + +- [x] 2.2 Clean up step numbering in start.md +- [x] 2.3 Clean up step numbering in quick-mode.md + +## Completed Tasks (Phase 4) +- [x] 4.1 Bump plugin version + +## Current Task +Awaiting next task + +### Task 2.1 Completion +- Verified all 4 tokenization rule blocks are already word-for-word identical across start.md Pass 1 (line 51-56), start.md Pass 2 (line 151-156), quick-mode.md Pass 1 (line 105-110), quick-mode.md Pass 2 (line 136-141) +- Stopword list matches in all 4: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about (25 words) +- No changes needed -- POC phase already established identical wording + +### Task 1.9 Completion +- Added error handling for 4 scenarios to all 4 discovery insertion points (start.md Pass 1 + Pass 2, quick-mode.md Pass 1 + Pass 2) +- Scenarios: unreadable SKILL.md (skip + log warning), missing description (skip + log "no description"), Skill invocation failure (set invoked: false + log warning + continue), no matches (log "No skills matched") +- Added "skipped (unreadable)" and "skipped (no description)" entries to progress logging format in all 4 passes + +### Task 1.8 Completion +- Added Step 10.5 (Skill Discovery Pass 2) to quick-mode.md between step 10 (Research) and step 11 (Requirements) +- Added both code block entry and detailed ## section with full discovery instructions +- Uses goal text + Executive Summary from research.md as context, matchedAt: "post-research" +- Logs to progress under ### Post-Research Retry + +## Learnings +- All 6 ralph-specum skills have `description` in YAML frontmatter -- this is the matching surface +- Skills with `user-invocable: false` (interview-framework, reality-verification, delegation-principle, communication-style) should still be auto-discoverable +- Two clear insertion points: after Step 2 (input parsing) and after research.md creation (before requirements) +- The Skill tool (`Skill({ skill: "ralph-specum:" })`) is the correct invocation mechanism +- Keyword matching is sufficient for ~6 skills; semantic matching would be overengineered +- Both quick mode and normal mode should auto-invoke without prompts (skills are additive context) +- `discoveredSkills` array in .ralph-state.json prevents duplicate invocations across passes +- Skill descriptions contain many generic words ("should", "used", "when", "asks") that need stopword filtering to avoid false positives +- Threshold of 2 keyword overlaps balances precision vs recall for 6 skills +- No separate reference file needed -- only 2 insertion points with minor context differences (goal-only vs goal+summary) +- Post-research pass should use Executive Summary section only, not full research.md (too noisy) +- Resume flow should NOT re-run discovery -- skills were loaded in original session context +- Coordinator performs discovery inline (reading frontmatter + matching) -- this is coordination work, not implementation requiring subagent delegation +- start.md Step 2.5 is normal mode only -- quick mode jumps from Step 2 to Step 5 (quick-mode.md), so it never hits Step 2.5. Quick mode gets Pass 1 at quick-mode.md step 8.5 instead +- Tokenization must treat hyphens as word separators (skill descriptions use them: "brainstorming-style"), strip parentheses/commas/punctuation, and compare case-insensitively +- Task planning: 4 insertion points total (2 in start.md for normal mode, 2 in quick-mode.md for quick mode) -- each self-contained inline +- Task planning: state init happens in 2 places (start.md step 7 for normal, quick-mode.md step 5 for quick) -- both need discoveredSkills: [] +- Task planning: no build/lint/typecheck commands exist for this plugin -- quality gates are structural grep checks on markdown content +- Task planning: version bump is 4.1.2 -> 4.2.0 (minor, new feature) in both plugin.json and marketplace.json +- Task planning: start.md normal mode New Flow step numbering is 1-12; insert post-research pass after step 11 (Team Research) before step 12 (STOP) +- Pass 2 inserted as step 12, STOP renumbered to step 13. New Flow is now steps 1-13 +- Step 2.5 renumbered to Step 3, cascading: Step 3->4, Step 4->5, Step 5->6. Top-level steps now 1-6 sequential. "Skip to Step 5" references updated to "Step 6" +- quick-mode.md uses compact code block for step listing + separate ## sections for detailed instructions. Pass 1 added as both step 8.5 in code block and ## Step 8.5 section with full instructions +- Pass 2 in quick-mode.md follows same pattern: code block entry at 10.5 + detailed ## Step 10.5 section. Mirrors start.md Pass 2 structure exactly. +- quick-mode.md renumbered from X.5 (8.5, 10.5) to clean integers 1-17. Step 8.5->9, old 9->10, old 10->11, Step 10.5->12, old 11->13, old 12->14, old 13->15, old 14->16, old 15->17. Section headers and cross-references updated: "steps 11-15" for directive, "steps 13-15" for review loop. + +### Verification: 1.4 [VERIFY] Quality checkpoint: grep for consistent terminology +- Status: PASS +- discoveredSkills count in start.md: 4 (threshold >= 2) -- PASS +- matchedAt count in start.md: 2 (threshold >= 1) -- PASS +- invoked count in start.md: 3 (present in both success and failure paths) -- PASS +- Terminology cross-check with design.md: all field names (discoveredSkills, matchedAt, invoked), values ("start", "post-research", true/false), and object structure ({ name, matchedAt, invoked }) match exactly +- No fixes needed + +### Verification: 1.7 [VERIFY] Quality checkpoint: both files have Pass 1 +- Status: PASS +- 'Skill Discovery Pass 1' in start.md: 1 (threshold >= 1) -- PASS +- 'Skill Discovery Pass 1' in quick-mode.md: 2 (threshold >= 1) -- PASS +- 'overlap >= 2' in start.md: 2 (threshold >= 1) -- PASS +- 'overlap >= 2' in quick-mode.md: 1 (threshold >= 1) -- PASS +- Both files contain Pass 1 instructions with matching algorithm and threshold +- No fixes needed + +### Verification: 1.10 [VERIFY] Quality checkpoint: full content verification +- Status: PASS +- 'Skill Discovery' in start.md: 6 (threshold >= 2) -- PASS +- 'Skill Discovery' in quick-mode.md: 7 (threshold >= 2) -- PASS +- 'discoveredSkills' in start.md: 7 (threshold >= 3) -- PASS +- 'discoveredSkills' in quick-mode.md: 7 (threshold >= 3) -- PASS +- 'stopwords' in start.md: 2 (threshold >= 1) -- PASS +- 'stopwords' in quick-mode.md: 2 (threshold >= 1) -- PASS +- All 4 discovery insertion points verified with required elements +- No fixes needed + +### Verification: 1.11 POC Checkpoint: verify feature works end-to-end +- Status: PASS +- Normal mode flow traced: Step 1 -> Step 2 -> Step 2.5 (Pass 1) -> Step 3 -> Step 4 (New Flow steps 1-11) -> Step 12 (Pass 2) -> Step 13 (STOP) -- correct, no gaps +- Quick mode flow traced: steps 1-8 -> 8.5 (Pass 1) -> 9-10 -> 10.5 (Pass 2) -> 11-15 -- correct, no gaps +- Step numbering: no conflicts found. start.md uses Step 1/2/2.5/3/4/5 top-level and 1-13 in New Flow. quick-mode.md uses 1-8, 8.5, 9-10, 10.5, 11-15 with matching ## sections +- Cross-references verified: "skip to Step 5" (line 39) correctly points to Step 5 (line 203), Step 2.5 note correctly says quick mode skips to Step 5 +- Tokenization rules identical across all 4 insertion points (start.md Pass 1 line 51-56, Pass 2 line 151-156; quick-mode.md Pass 1 line 105-110, Pass 2 line 136-141) +- Stopword list identical across all 4: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about (25 words) +- `ralph-specum:` Skill invocation syntax: 2 occurrences in start.md (>= 1) -- PASS +- `ralph-specum:` Skill invocation syntax: 2 occurrences in quick-mode.md (>= 1) -- PASS +- No fixes needed + +### Verification: 3.1 Verify all 6 skills are discoverable via frontmatter +- Status: PASS +- All 6 skill directories found: communication-style, delegation-principle, interview-framework, reality-verification, smart-ralph, spec-workflow +- All 6 SKILL.md files have `name` field in YAML frontmatter matching directory basename +- All 6 SKILL.md files have `description` field in YAML frontmatter +- Invocation syntax `ralph-specum:` matches directory names for all 6 +- Verification command (`for d in ... grep -l ...`) output 6 matches, 0 MISSING lines +- No fixes needed + +### Verification: 2.4 [VERIFY] Quality checkpoint: refactoring consistency +- Status: PASS +- 'Skill Discovery' in start.md: 6 (threshold >= 2) -- PASS +- 'Skill Discovery' in quick-mode.md: 7 (threshold >= 2) -- PASS +- start.md step headers: Step 1, 2, 3, 4, 5, 6 -- sequential integers, no X.5 steps -- PASS +- start.md New Flow sub-steps: 1-13 -- sequential integers, no X.5 -- PASS +- quick-mode.md execution sequence: 1-17 -- sequential integers, no X.5 -- PASS +- quick-mode.md section headers: ## Step 9, ## Step 12 -- match code block numbers -- PASS +- Quick Mode Check cross-ref: "skip to Step 6" matches ## Step 6 header -- PASS +- Quick Mode Directive: "steps 11-15" covers agent delegation steps correctly -- PASS +- Review Loop: "steps 13-15" covers Requirements/Design/Tasks correctly -- PASS +- No broken "Step N" references found in either file +- No X.5 step numbers remain in quick-mode.md +- No fixes needed + +### Verification: 3.2 Verify tokenization handles existing skill descriptions correctly +- Status: PASS +- Source: interview-framework SKILL.md description = "Adaptive brainstorming-style dialogue for all spec phases (Understand, Propose Approaches, Confirm & Store)" +- Tokenization steps applied: + 1. Lowercase: "adaptive brainstorming-style dialogue for all spec phases (understand, propose approaches, confirm & store)" + 2. Hyphens->spaces: "adaptive brainstorming style dialogue for all spec phases (understand, propose approaches, confirm & store)" + 3. Strip punctuation: "adaptive brainstorming style dialogue for all spec phases understand propose approaches confirm store" + 4. Split: 13 tokens + 5. Remove stopwords ("for" removed): 12 tokens remaining +- Final tokens: ["adaptive", "brainstorming", "style", "dialogue", "all", "spec", "phases", "understand", "propose", "approaches", "confirm", "store"] +- Matches expected output from task description exactly +- Sample goal test: "Add adaptive brainstorming for goal exploration" + - Goal tokens after tokenization: ["add", "adaptive", "brainstorming", "goal", "exploration"] + - Overlap with skill tokens: ["adaptive", "brainstorming"] = 2 words + - 2 >= 2 (threshold) -> MATCH confirmed +- Tokenization rules verified against start.md lines 52-56 (identical in all 4 discovery passes per task 2.1) +- No fixes needed + +### Verification: 3.3 Verify discovery instructions reference correct CLAUDE_PLUGIN_ROOT path +- Status: PASS +- CLAUDE_PLUGIN_ROOT in start.md: 8 occurrences (threshold >= 2) -- PASS + - Skills path refs: line 47 (Pass 1), line 147 (Pass 2) use `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` + - Other refs: branch-management, intent-classification, spec-scanner, goal-interview, parallel-research, quick-mode +- CLAUDE_PLUGIN_ROOT in quick-mode.md: 2 occurrences (threshold >= 1) -- PASS + - Skills path refs: line 101 (Pass 1), line 132 (Pass 2) use `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` +- Skill invocation pattern `ralph-specum:` in start.md: 2 Skill tool invocations (lines 59, 159) -- PASS +- Skill invocation pattern `ralph-specum:` in quick-mode.md: 2 Skill tool invocations (lines 113, 144) -- PASS +- No hardcoded paths to skills directory found -- all use CLAUDE_PLUGIN_ROOT variable +- No fixes needed + +### Verification: 3.4 [VERIFY] Quality checkpoint: content completeness +- Status: PASS +- discoveredSkills in start.md: 7 (threshold >= 3) -- PASS +- discoveredSkills in quick-mode.md: 7 (threshold >= 3) -- PASS +- matchedAt in start.md: 4 (threshold >= 2) -- PASS +- matchedAt in quick-mode.md: 4 (threshold >= 2) -- PASS +- invoked in start.md: 7 (threshold >= 2) -- PASS +- invoked in quick-mode.md: 7 (threshold >= 2) -- PASS +- Post-Research in start.md: 3 (threshold >= 1) -- PASS +- Post-Research in quick-mode.md: 3 (threshold >= 1) -- PASS +- progress.md in start.md: 4 (threshold >= 2) -- PASS +- progress.md in quick-mode.md: 5 (threshold >= 2) -- PASS +- All 10 structural content checks passed with counts well above thresholds +- No fixes needed + +### Verification: 3.5 Verify AC coverage by tracing each acceptance criterion +- Status: PASS +- All 22 ACs traced to implementation in start.md and/or quick-mode.md +- AC-1.1: PASS -- start.md line 47, quick-mode.md line 101 read SKILL.md frontmatter via CLAUDE_PLUGIN_ROOT/skills/*/SKILL.md +- AC-1.2: PASS -- start.md lines 51-57, quick-mode.md lines 105-111 implement tokenization + overlap >= 2 +- AC-1.3: PASS -- start.md line 59, quick-mode.md line 113 invoke via Skill({ skill: "ralph-specum:" }) +- AC-1.4: PASS -- no filtering on user-invocable field in either file (verified via grep: 0 matches) +- AC-1.5: PASS -- start.md Step 3 (after Step 2 input parsing, before Step 4/5 phase work); quick-mode.md step 9 (after step 8, before step 10/11) +- AC-2.1: PASS -- start.md step 12, quick-mode.md step 12 use goal text + Executive Summary from research.md +- AC-2.2: PASS -- start.md line 158, quick-mode.md line 143 skip skills already in discoveredSkills with invoked: true +- AC-2.3: PASS -- start.md Pass 2 at step 12 before STOP (step 13); quick-mode.md Pass 2 at step 12 before Requirements (step 13) +- AC-2.4: PASS -- Pass 2 exists in both start.md (step 12) and quick-mode.md (step 12) +- AC-3.1: PASS -- discoveredSkills: [] in state init (start.md line 134, quick-mode.md line 75); objects have { name, matchedAt, invoked } +- AC-3.2: PASS -- matchedAt: "start" (Pass 1) and "post-research" (Pass 2) in both files +- AC-3.3: PASS -- invoked: true on success, invoked: false on failure in all 4 passes +- AC-3.4: PASS -- "Update .ralph-state.json with updated discoveredSkills array" in all 4 passes +- AC-4.1: PASS -- "Append a ## Skill Discovery section to .progress.md" in Pass 1 of both files +- AC-4.2: PASS -- format includes "matched (keywords: )" in all passes +- AC-4.3: PASS -- "### Post-Research Retry" subsection appended in Pass 2 of both files +- AC-4.4: PASS -- "No skills matched" (Pass 1) / "No new skills matched" (Pass 2) logged explicitly +- AC-5.1: PASS -- quick-mode.md has no confirmation prompts in discovery steps +- AC-5.2: PASS -- start.md has no confirmation prompts in discovery steps +- AC-5.3: PASS -- all 4 passes: "set invoked: false, log warning, continue" on failure +- Gaps found: 0 +- No fixes needed diff --git a/specs/smart-skill-swap-retry/tasks.md b/specs/smart-skill-swap-retry/tasks.md new file mode 100644 index 0000000..8ebb83c --- /dev/null +++ b/specs/smart-skill-swap-retry/tasks.md @@ -0,0 +1,346 @@ +--- +generated: auto +--- + +# Tasks: Smart Skill Swap & Retry + +## Phase 1: Make It Work (POC) + +Focus: Get skill discovery working end-to-end in both normal and quick mode. Accept inline duplication between the two files -- we can DRY up later if warranted. + +- [x] 1.1 Add discoveredSkills to state initialization in start.md (normal mode) + - **Do**: + 1. Open `plugins/ralph-specum/commands/start.md` + 2. In Step 7 (New Flow), add `"discoveredSkills": []` to the `.ralph-state.json` initialization JSON block (after `quickMode`) + - **Files**: `plugins/ralph-specum/commands/start.md` + - **Done when**: The JSON block in start.md step 7 includes `"discoveredSkills": []` + - **Verify**: `grep -c 'discoveredSkills' plugins/ralph-specum/commands/start.md` returns >= 1 + - **Commit**: `feat(ralph-specum): add discoveredSkills to normal mode state init` + - _Requirements: FR-5, AC-3.1_ + - _Design: State Schema Changes_ + +- [x] 1.2 Add discoveredSkills to state initialization in quick-mode.md + - **Do**: + 1. Open `plugins/ralph-specum/references/quick-mode.md` + 2. In step 5 (Write .ralph-state.json), add `"discoveredSkills": []` to the JSON block (after `quickMode`) + - **Files**: `plugins/ralph-specum/references/quick-mode.md` + - **Done when**: The JSON block in quick-mode.md step 5 includes `"discoveredSkills": []` + - **Verify**: `grep -c 'discoveredSkills' plugins/ralph-specum/references/quick-mode.md` returns >= 1 + - **Commit**: `feat(ralph-specum): add discoveredSkills to quick mode state init` + - _Requirements: FR-5, AC-3.1_ + - _Design: State Schema Changes_ + +- [x] 1.3 Add Skill Discovery Pass 1 to start.md (normal mode, Step 2.5) + - **Do**: + 1. Open `plugins/ralph-specum/commands/start.md` + 2. Insert a new section `## Step 2.5: Skill Discovery Pass 1` between the "Quick Mode Check" subsection (after Step 2) and Step 3 (Scan Existing Specs) + 3. Include the full inline discovery instructions from design.md "Discovery Instructions Block" template, configured for Pass 1: + - Context text: goal text only + - matchedAt: `"start"` + - Tokenization rules (lowercase, hyphens->spaces, strip punctuation, split whitespace, remove stopwords) + - Threshold: overlap >= 2 words + - Skip skills already invoked + - Invoke via `Skill({ skill: "ralph-specum:" })` + - Update `.ralph-state.json` discoveredSkills array + - Append `## Skill Discovery` section to `.progress.md` with match details + 4. Add a note that this step runs in normal mode only (quick mode skips to Step 5) + - **Files**: `plugins/ralph-specum/commands/start.md` + - **Done when**: Step 2.5 exists between Quick Mode Check and Step 3, contains full tokenization rules, matching algorithm, state update, and progress logging instructions + - **Verify**: `grep -A2 'Step 2.5' plugins/ralph-specum/commands/start.md | head -3` shows the section header + - **Commit**: `feat(ralph-specum): add skill discovery pass 1 to normal mode` + - _Requirements: FR-1, FR-2, FR-3, AC-1.1, AC-1.2, AC-1.3, AC-1.5_ + - _Design: Discovery Instructions Block, Insertion Points (Normal Mode)_ + +- [x] 1.4 [VERIFY] Quality checkpoint: grep for consistent terminology + - **Do**: Verify start.md uses consistent naming (discoveredSkills, matchedAt, invoked) matching design.md + - **Verify**: `grep -c 'discoveredSkills' plugins/ralph-specum/commands/start.md` returns >= 2 (init + pass 1) AND `grep -c 'matchedAt' plugins/ralph-specum/commands/start.md` returns >= 1 + - **Done when**: Terminology matches design spec + - **Commit**: `chore(ralph-specum): fix terminology` (only if fixes needed) + +- [x] 1.5 Add Skill Discovery Pass 2 to start.md (normal mode, post-research) + - **Do**: + 1. Open `plugins/ralph-specum/commands/start.md` + 2. In the New Flow section, insert a new step after step 11 (Team Research Phase) and before step 12 (STOP/walkthrough). Renumber if needed, or insert as step 11.5 + 3. Include the full inline discovery instructions configured for Pass 2: + - Context text: goal text + Executive Summary section from research.md + - matchedAt: `"post-research"` + - Same tokenization rules as Pass 1 + - Skip skills already in discoveredSkills with `invoked: true` + - Invoke newly matched skills + - Update state + - Append `### Post-Research Retry` subsection to `.progress.md` + - **Files**: `plugins/ralph-specum/commands/start.md` + - **Done when**: Post-research pass exists after research and before walkthrough/STOP, references Executive Summary as context source, skips already-invoked skills + - **Verify**: `grep -c 'Post-Research' plugins/ralph-specum/commands/start.md` returns >= 1 + - **Commit**: `feat(ralph-specum): add skill discovery pass 2 to normal mode` + - _Requirements: FR-4, FR-7, AC-2.1, AC-2.2, AC-2.3_ + - _Design: Discovery Instructions Block, Insertion Points (Normal Mode)_ + +- [x] 1.6 Add Skill Discovery Pass 1 to quick-mode.md (Step 8.5) + - **Do**: + 1. Open `plugins/ralph-specum/references/quick-mode.md` + 2. In the Quick Mode Execution Sequence, insert step 8.5 between step 8 (Update Spec Index) and step 9 (Goal Type Detection) + 3. Add the step as: `8.5. Skill Discovery Pass 1: scan skills, match against goal text, invoke matches` + 4. Include the full inline discovery instructions (same as start.md Pass 1 but self-contained in this file): + - Context text: goal text only + - matchedAt: `"start"` + - Full tokenization rules + - Threshold >= 2, skip already-invoked + - Invoke, update state, log to progress + - **Files**: `plugins/ralph-specum/references/quick-mode.md` + - **Done when**: Step 8.5 exists between steps 8 and 9, contains full discovery instructions + - **Verify**: `grep -c 'Skill Discovery Pass 1' plugins/ralph-specum/references/quick-mode.md` returns >= 1 + - **Commit**: `feat(ralph-specum): add skill discovery pass 1 to quick mode` + - _Requirements: FR-1, FR-2, FR-3, AC-1.1, AC-5.1_ + - _Design: Insertion Points (Quick Mode)_ + +- [x] 1.7 [VERIFY] Quality checkpoint: both files have Pass 1 + - **Do**: Verify both start.md and quick-mode.md contain Skill Discovery Pass 1 with matching algorithm + - **Verify**: `grep -c 'Skill Discovery Pass 1' plugins/ralph-specum/commands/start.md` >= 1 AND `grep -c 'Skill Discovery Pass 1' plugins/ralph-specum/references/quick-mode.md` >= 1 AND `grep -c 'overlap >= 2' plugins/ralph-specum/commands/start.md` >= 1 AND `grep -c 'overlap >= 2' plugins/ralph-specum/references/quick-mode.md` >= 1 + - **Done when**: Both files have consistent Pass 1 instructions with threshold + - **Commit**: `chore(ralph-specum): align pass 1 instructions` (only if fixes needed) + +- [x] 1.8 Add Skill Discovery Pass 2 to quick-mode.md (Step 10.5) + - **Do**: + 1. Open `plugins/ralph-specum/references/quick-mode.md` + 2. Insert step 10.5 between step 10 (Research Phase) and step 11 (Requirements Phase) + 3. Add the step as: `10.5. Skill Discovery Pass 2: re-scan skills using goal + research Executive Summary, invoke new matches` + 4. Include full inline discovery instructions for Pass 2: + - Context text: goal text + Executive Summary from research.md + - matchedAt: `"post-research"` + - Skip already-invoked skills + - Full tokenization rules + - Update state, log to progress under `### Post-Research Retry` + - **Files**: `plugins/ralph-specum/references/quick-mode.md` + - **Done when**: Step 10.5 exists between steps 10 and 11, uses Executive Summary as context source + - **Verify**: `grep -c 'Post-Research' plugins/ralph-specum/references/quick-mode.md` returns >= 1 AND `grep -c 'Executive Summary' plugins/ralph-specum/references/quick-mode.md` returns >= 1 + - **Commit**: `feat(ralph-specum): add skill discovery pass 2 to quick mode` + - _Requirements: FR-4, FR-7, AC-2.1, AC-2.2, AC-2.4_ + - _Design: Insertion Points (Quick Mode)_ + +- [x] 1.9 Add error handling instructions to both discovery passes + - **Do**: + 1. In start.md Step 2.5 and post-research pass, add explicit error handling notes: + - If SKILL.md is unreadable: skip skill, log warning + - If SKILL.md has no description field: skip skill, log "no description" + - If Skill tool invocation fails: set `invoked: false`, log warning, continue + - If no skills match: log "No skills matched" + 2. Add same error handling to quick-mode.md steps 8.5 and 10.5 + - **Files**: `plugins/ralph-specum/commands/start.md`, `plugins/ralph-specum/references/quick-mode.md` + - **Done when**: Error handling for all 4 scenarios (unreadable, no description, invoke fail, no match) is documented in all 4 insertion points + - **Verify**: `grep -c 'invoked: false' plugins/ralph-specum/commands/start.md` >= 1 AND `grep -c 'invoked: false' plugins/ralph-specum/references/quick-mode.md` >= 1 + - **Commit**: `feat(ralph-specum): add error handling to skill discovery` + - _Requirements: FR-8, AC-5.3_ + - _Design: Error Handling_ + +- [x] 1.10 [VERIFY] Quality checkpoint: full content verification + - **Do**: Verify all 4 discovery insertion points exist and have required elements + - **Verify**: Run all of these: + - `grep -c 'Skill Discovery' plugins/ralph-specum/commands/start.md` >= 2 (pass 1 + pass 2) + - `grep -c 'Skill Discovery' plugins/ralph-specum/references/quick-mode.md` >= 2 (pass 1 + pass 2) + - `grep -c 'discoveredSkills' plugins/ralph-specum/commands/start.md` >= 3 (init + 2 passes) + - `grep -c 'discoveredSkills' plugins/ralph-specum/references/quick-mode.md` >= 3 (init + 2 passes) + - `grep -c 'stopwords' plugins/ralph-specum/commands/start.md` >= 1 + - `grep -c 'stopwords' plugins/ralph-specum/references/quick-mode.md` >= 1 + - **Done when**: All grep counts meet thresholds + - **Commit**: `chore(ralph-specum): pass POC quality checkpoint` (only if fixes needed) + +- [x] 1.11 POC Checkpoint: verify feature works end-to-end + - **Do**: + 1. Read start.md fully and trace the normal mode flow: Step 1 -> Step 2 -> Step 2.5 (Pass 1) -> Step 3 -> Step 4 (New Flow) -> steps 1-11 -> Post-Research (Pass 2) -> STOP + 2. Read quick-mode.md fully and trace: steps 1-8 -> 8.5 (Pass 1) -> 9-10 -> 10.5 (Pass 2) -> 11-15 + 3. Verify no step numbering conflicts or broken references + 4. Verify the tokenization rules and stopword list are identical across all 4 insertion points + - **Verify**: `grep -c 'ralph-specum:' plugins/ralph-specum/commands/start.md` >= 1 AND `grep -c 'ralph-specum:' plugins/ralph-specum/references/quick-mode.md` >= 1 (proves Skill invocation syntax present in both) + - **Done when**: Both files have complete, consistent skill discovery instructions at correct insertion points with no broken step numbering + - **Commit**: `feat(ralph-specum): complete skill discovery POC` + +## Phase 2: Refactoring + +Focus: Clean up inline instructions for clarity. Ensure consistent formatting between normal and quick mode. + +- [x] 2.1 Ensure tokenization rules are identically worded in all 4 passes + - **Do**: + 1. Compare the tokenization rules text in start.md Pass 1 vs Pass 2 vs quick-mode.md Pass 1 vs Pass 2 + 2. Pick the clearest wording and normalize all 4 to use identical phrasing + 3. Ensure the stopword list is the same across all 4: `a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about` + - **Files**: `plugins/ralph-specum/commands/start.md`, `plugins/ralph-specum/references/quick-mode.md` + - **Done when**: Tokenization rules are word-for-word identical in all 4 insertion points + - **Verify**: Extract tokenization sections from both files and diff them (manual read + compare) + - **Commit**: `refactor(ralph-specum): normalize tokenization rules across discovery passes` + - _Design: Tokenization Rules_ + +- [x] 2.2 Clean up step numbering in start.md + - **Do**: + 1. Review start.md New Flow numbered list (steps 1-12) + 2. Decide: either use X.5 numbering (2.5, 11.5) or renumber to integers + 3. Ensure the Quick Mode Check note ("skip to Step 5") still references the correct step + 4. Ensure all cross-references within start.md are consistent + - **Files**: `plugins/ralph-specum/commands/start.md` + - **Done when**: Step numbering is clean with no broken cross-references + - **Verify**: `grep -n 'Step [0-9]' plugins/ralph-specum/commands/start.md` shows sequential numbering + - **Commit**: `refactor(ralph-specum): clean up step numbering in start.md` + +- [x] 2.3 Clean up step numbering in quick-mode.md + - **Do**: + 1. Review Quick Mode Execution Sequence numbered list + 2. Decide: either use X.5 numbering (8.5, 10.5) or renumber to integers + 3. Ensure all internal references are consistent + - **Files**: `plugins/ralph-specum/references/quick-mode.md` + - **Done when**: Step numbering is clean with no broken references + - **Verify**: `grep -n '^[0-9]' plugins/ralph-specum/references/quick-mode.md` shows logical sequence + - **Commit**: `refactor(ralph-specum): clean up step numbering in quick-mode.md` + +- [x] 2.4 [VERIFY] Quality checkpoint: refactoring consistency + - **Do**: Verify both files are internally consistent and cross-references work + - **Verify**: `grep -c 'Skill Discovery' plugins/ralph-specum/commands/start.md` >= 2 AND `grep -c 'Skill Discovery' plugins/ralph-specum/references/quick-mode.md` >= 2 AND no broken "Step N" references exist + - **Done when**: Both files read cleanly with no orphaned references + - **Commit**: `chore(ralph-specum): pass refactoring quality checkpoint` (only if fixes needed) + +## Phase 3: Testing + +Focus: Verify the markdown instructions are correct and complete by automated content checks. No runtime test framework exists -- validation is structural. + +- [x] 3.1 Verify all 6 skills are discoverable via frontmatter + - **Do**: + 1. Read each SKILL.md under `plugins/ralph-specum/skills/*/SKILL.md` + 2. Verify each has `name` and `description` in YAML frontmatter + 3. Verify the Skill invocation syntax `ralph-specum:` matches actual skill directory names + - **Files**: All 6 SKILL.md files (read-only verification) + - **Done when**: All 6 skills have name + description frontmatter matching their directory names + - **Verify**: `for d in plugins/ralph-specum/skills/*/; do name=$(basename "$d"); grep -l "name: $name" "$d/SKILL.md" || echo "MISSING: $name"; done` outputs 6 matches and no MISSING lines + - **Commit**: none (read-only check) + - _Requirements: AC-1.1, AC-1.4_ + +- [x] 3.2 Verify tokenization handles existing skill descriptions correctly + - **Do**: + 1. Read interview-framework SKILL.md description: "Adaptive brainstorming-style dialogue for all spec phases (Understand, Propose Approaches, Confirm & Store)" + 2. Apply tokenization rules manually: + - Lowercase: "adaptive brainstorming-style dialogue for all spec phases (understand, propose approaches, confirm & store)" + - Hyphens->spaces: "adaptive brainstorming style dialogue for all spec phases (understand, propose approaches, confirm & store)" + - Strip punctuation: "adaptive brainstorming style dialogue for all spec phases understand propose approaches confirm store" + - Split: ["adaptive", "brainstorming", "style", "dialogue", "for", "all", "spec", "phases", "understand", "propose", "approaches", "confirm", "store"] + - Remove stopwords: ["adaptive", "brainstorming", "style", "dialogue", "all", "spec", "phases", "understand", "propose", "approaches", "confirm", "store"] + 3. Verify a goal like "Add adaptive brainstorming for goal exploration" would match (overlap: adaptive, brainstorming = 2 words) + 4. Document this test case in .progress.md under Learnings + - **Files**: `specs/smart-skill-swap-retry/.progress.md` (append) + - **Done when**: Tokenization produces expected tokens, match threshold works for sample case + - **Verify**: `grep -c 'tokenization' specs/smart-skill-swap-retry/.progress.md` >= 1 + - **Commit**: `test(ralph-specum): verify tokenization against real skill descriptions` + - _Design: Tokenization Rules, Matching Algorithm_ + +- [x] 3.3 Verify discovery instructions reference correct CLAUDE_PLUGIN_ROOT path + - **Do**: + 1. Check that all discovery instructions in start.md and quick-mode.md use `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` (not hardcoded paths) + 2. Verify the Skill invocation uses `ralph-specum:` format + - **Files**: `plugins/ralph-specum/commands/start.md`, `plugins/ralph-specum/references/quick-mode.md` (read-only) + - **Done when**: All path references use CLAUDE_PLUGIN_ROOT variable + - **Verify**: `grep -c 'CLAUDE_PLUGIN_ROOT' plugins/ralph-specum/commands/start.md` >= 2 (existing + new) AND `grep -c 'CLAUDE_PLUGIN_ROOT' plugins/ralph-specum/references/quick-mode.md` >= 1 + - **Commit**: none (read-only check) or `fix(ralph-specum): correct plugin root paths` if fixes needed + - _Requirements: AC-1.1_ + +- [x] 3.4 [VERIFY] Quality checkpoint: content completeness + - **Do**: Run all structural checks to ensure nothing was missed + - **Verify**: All of these pass: + - `grep -c 'discoveredSkills' plugins/ralph-specum/commands/start.md` >= 3 + - `grep -c 'discoveredSkills' plugins/ralph-specum/references/quick-mode.md` >= 3 + - `grep -c 'matchedAt' plugins/ralph-specum/commands/start.md` >= 2 + - `grep -c 'matchedAt' plugins/ralph-specum/references/quick-mode.md` >= 2 + - `grep -c 'invoked' plugins/ralph-specum/commands/start.md` >= 2 + - `grep -c 'invoked' plugins/ralph-specum/references/quick-mode.md` >= 2 + - `grep -c 'Post-Research' plugins/ralph-specum/commands/start.md` >= 1 + - `grep -c 'Post-Research' plugins/ralph-specum/references/quick-mode.md` >= 1 + - `grep -c 'progress.md' plugins/ralph-specum/commands/start.md` >= 2 (existing + discovery logging) + - `grep -c 'progress.md' plugins/ralph-specum/references/quick-mode.md` >= 2 + - **Done when**: All counts meet thresholds + - **Commit**: `chore(ralph-specum): pass content completeness checkpoint` (only if fixes needed) + +- [x] 3.5 Verify AC coverage by tracing each acceptance criterion + - **Do**: + 1. For each AC in requirements.md, verify the corresponding instruction exists in start.md or quick-mode.md: + - AC-1.1: Read SKILL.md files -> check for CLAUDE_PLUGIN_ROOT/skills reference + - AC-1.2: Keyword overlap matching -> check for tokenization + overlap >= 2 + - AC-1.3: Invoke via Skill tool -> check for `ralph-specum:` invocation + - AC-1.4: user-invocable: false still eligible -> check no filtering on this field + - AC-1.5: Discovery before phase delegation -> check Step 2.5 placement + - AC-2.1: Re-run with Executive Summary -> check post-research pass + - AC-2.2: Skip already-invoked -> check duplicate prevention logic + - AC-2.3: Before requirements -> check quick-mode step 10.5 before 11 + - AC-2.4: Both modes -> check both files have pass 2 + - AC-3.1-3.4: State tracking -> check discoveredSkills in state updates + - AC-4.1-4.4: Progress logging -> check progress.md append instructions + - AC-5.1-5.3: No prompts, immediate invoke, failure handling -> check no confirmation prompts, error handling + 2. Document any gaps found + - **Files**: `specs/smart-skill-swap-retry/.progress.md` (append if gaps found) + - **Done when**: Every AC-* has a traceable instruction in the modified files + - **Verify**: `grep -c 'Skill Discovery' plugins/ralph-specum/commands/start.md` >= 2 AND `grep -c 'Skill Discovery' plugins/ralph-specum/references/quick-mode.md` >= 2 (proves both passes exist in both modes) + - **Commit**: `fix(ralph-specum): address AC coverage gaps` (only if fixes needed) + - _Requirements: All ACs_ + +## Phase 4: Quality Gates + +- [x] 4.1 Bump plugin version + - **Do**: + 1. Bump patch version in `plugins/ralph-specum/.claude-plugin/plugin.json` (4.1.2 -> 4.2.0, minor bump for new feature) + 2. Bump matching version in `.claude-plugin/marketplace.json` (4.1.2 -> 4.2.0) + - **Files**: `plugins/ralph-specum/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` + - **Done when**: Both files show version 4.2.0 + - **Verify**: `grep '"version"' plugins/ralph-specum/.claude-plugin/plugin.json` shows 4.2.0 AND `grep -A1 'ralph-specum' .claude-plugin/marketplace.json | grep version` shows 4.2.0 + - **Commit**: `chore(ralph-specum): bump version to 4.2.0` + +- [ ] 4.2 [VERIFY] Full local quality check + - **Do**: Verify all modified files are syntactically valid markdown and contain no broken references + - **Verify**: All pass: + - `test -f plugins/ralph-specum/commands/start.md` (file exists) + - `test -f plugins/ralph-specum/references/quick-mode.md` (file exists) + - `grep -c 'discoveredSkills' plugins/ralph-specum/commands/start.md` >= 3 + - `grep -c 'discoveredSkills' plugins/ralph-specum/references/quick-mode.md` >= 3 + - `grep -c 'Step' plugins/ralph-specum/commands/start.md` >= 6 (all steps still present) + - JSON parse check: `python3 -c "import json; json.loads(open('plugins/ralph-specum/.claude-plugin/plugin.json').read())"` exits 0 + - JSON parse check: `python3 -c "import json; json.loads(open('.claude-plugin/marketplace.json').read())"` exits 0 + - **Done when**: All files valid, all checks pass + - **Commit**: `fix(ralph-specum): address quality issues` (only if fixes needed) + +- [ ] 4.3 Create PR and verify CI + - **Do**: + 1. Verify current branch is a feature branch: `git branch --show-current` + 2. If on default branch, STOP and alert user + 3. Stage modified files: `git add plugins/ralph-specum/commands/start.md plugins/ralph-specum/references/quick-mode.md plugins/ralph-specum/.claude-plugin/plugin.json .claude-plugin/marketplace.json` + 4. Push branch: `git push -u origin $(git branch --show-current)` + 5. Create PR: `gh pr create --title "feat(ralph-specum): auto-discover and invoke skills on start" --body "..."` + - **Verify**: `gh pr checks --watch` shows all green (or `gh pr checks` if no CI configured) + - **Done when**: PR created, CI passes (or no CI to run) + - **Commit**: none (PR creation, not a code change) + +- [ ] 4.4 Monitor CI and fix failures + - **Do**: + 1. Check CI status: `gh pr checks` + 2. If failures: read failure details, fix, push + 3. Re-verify: `gh pr checks` + - **Verify**: `gh pr checks` shows all passing or no checks configured + - **Done when**: All CI checks green + +- [ ] 4.5 [VERIFY] AC checklist final verification + - **Do**: + 1. Read requirements.md + 2. For each AC, verify implementation exists via grep/read + 3. Confirm: discoveredSkills in state (AC-3), progress logging (AC-4), both modes (AC-2.4, AC-5), error handling (AC-5.3) + - **Verify**: `grep -c 'discoveredSkills' plugins/ralph-specum/commands/start.md` >= 3 AND `grep -c 'discoveredSkills' plugins/ralph-specum/references/quick-mode.md` >= 3 AND `grep -c 'Post-Research' plugins/ralph-specum/commands/start.md` >= 1 AND `grep -c 'Post-Research' plugins/ralph-specum/references/quick-mode.md` >= 1 + - **Done when**: All ACs confirmed implemented + - **Commit**: none + +- [ ] 4.6 Address review comments (if any) + - **Do**: + 1. Check for PR review comments: `gh pr view --comments` + 2. Address each comment + 3. Push fixes + - **Verify**: `gh pr checks` still green after fixes + - **Done when**: All review comments resolved + +## Notes + +- **POC shortcuts taken**: Inline discovery instructions are duplicated between start.md and quick-mode.md (4 insertion points, each self-contained). This is intentional per design -- only 2 files, minor differences in context source. +- **Production TODOs**: If skill count grows beyond ~10, consider a centralized discovery reference file. For now, inline is simpler. +- **Key insight**: The "code" is markdown instructions for an AI agent. There is no runtime, no build, no test framework. "Testing" means structural validation of the markdown content. +- **Stopword list**: a, an, the, to, for, with, and, or, in, on, by, is, be, that, this, of, it, should, used, when, asks, needs, about (25 words) +- **Threshold**: 2 word overlap -- prevents false positives while catching real matches