feat(ralph-specum): auto-discover and invoke skills on start#98
Open
feat(ralph-specum): auto-discover and invoke skills on start#98
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… passes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe PR bumps the ralph-specum plugin version from 4.1.2 to 4.2.0 across marketplace and plugin configuration files, and introduces comprehensive documentation for a multi-pass Skill Discovery workflow in both normal and quick modes, including new progress tracking and task planning documents. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plugins/ralph-specum/commands/start.md (1)
11-19:⚠️ Potential issue | 🟡 MinorChecklist is stale — missing the new Skill Discovery step.
The top-level checklist still shows the old 5-item structure. Step 3 (Skill Discovery Pass 1) is not listed, "Classify intent" is now part of Step 2 rather than a separate item, and the step numbers for "Scan existing specs" and "Route to action" are off.
🛠️ Proposed fix
Create a task for each item and complete in order: 1. **Handle branch** -- check git branch, create/switch if needed 2. **Parse input** -- extract name, goal, flags from $ARGUMENTS; classify intent -3. **Classify intent** -- determine what user wants (new spec, resume, quick mode) -4. **Scan existing specs** -- find matching or related specs -5. **Route to action** -- invoke appropriate flow (new, resume, or quick mode) +3. **Skill Discovery Pass 1** -- scan skills and match against goal text (normal mode only) +4. **Scan existing specs** -- find matching or related specs +5. **Route to action** -- invoke appropriate flow (new, resume, or quick mode) +6. **Quick Mode Flow** -- follow quick-mode.md sequence if --quick flag present🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/ralph-specum/commands/start.md` around lines 11 - 19, The top-level checklist is missing the new "Skill Discovery (Pass 1)" step and the numbering is incorrect; update the checklist to insert a new item "3. Skill Discovery (Pass 1) -- detect required skills and capabilities" after "Parse input", renumber the subsequent items so "Classify intent" remains correctly placed (either as its own step or clearly noted under "Parse input" per current design), and ensure the existing items "Handle branch", "Parse input", "Classify intent", "Scan existing specs", and "Route to action" appear with correct order and numbering exactly as shown in the diff so the flow reflects the new Skill Discovery phase.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/ralph-specum/commands/start.md`:
- Around line 162-172: Update the second-pass logging instruction so the wording
matches the progress template: change the inline log text `- No skills matched`
to `- No new skills matched` in plugins/ralph-specum/commands/start.md (the step
describing Pass 2 and the Appendix "Post-Research Retry") and apply the same
change in quick-mode.md Step 12.6 so both the instruction and the `###
Post-Research Retry` template use the exact phrase `- No new skills matched`.
- Around line 41-72: Pass 1 discovery results are being overwritten because New
Flow initializes .ralph-state.json after Step 3 writes discoveredSkills; move
the Pass 1 discovery block so it runs after state initialization in the "New
Flow" (i.e., run the skill discovery once the .ralph-state.json exists) or
change the state init to merge existing discoveredSkills instead of resetting
them. Specifically, relocate the Step 3 "Skill Discovery Pass 1" logic into the
New Flow between current step 7 (state init) and step 8 (create .progress.md) or
modify the state initialization to merge rather than replace discoveredSkills;
ensure references to .ralph-state.json and the discoveredSkills array are
preserved and that deduplication logic (checking invoked:true) still runs before
invoking Skill({ skill: "ralph-specum:<name>" }).
In `@plugins/ralph-specum/references/quick-mode.md`:
- Around line 147-157: Summary: The "Pass 2" no-match log wording is
inconsistent between the instruction and the Post-Research Retry template;
standardize on "No new skills matched". Fix: update the Pass 2 log instruction
that currently says "- No skills matched" to read "- No new skills matched"
wherever it appears in quick-mode.md and start.md, and ensure the "###
Post-Research Retry" subsection template under "## Skill Discovery" uses the
same phrase; verify any references to the Pass 2 message in related
docs/templates are updated to keep wording consistent.
In `@specs/smart-skill-swap-retry/.progress.md`:
- Line 32: The stopword count in the line starting "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)" is incorrect; update the
parenthetical count to "(23 words)" (or recount and adjust if you intend to
add/remove words) so the text matches the actual list length.
In `@specs/smart-skill-swap-retry/tasks.md`:
- Line 346: Update the phrasing for the Threshold line in
specs/smart-skill-swap-retry/tasks.md by hyphenating the compound modifier:
change the phrase "**Threshold**: 2 word overlap" to "**Threshold**: 2-word
overlap" so the compound adjective is grammatically correct.
---
Outside diff comments:
In `@plugins/ralph-specum/commands/start.md`:
- Around line 11-19: The top-level checklist is missing the new "Skill Discovery
(Pass 1)" step and the numbering is incorrect; update the checklist to insert a
new item "3. Skill Discovery (Pass 1) -- detect required skills and
capabilities" after "Parse input", renumber the subsequent items so "Classify
intent" remains correctly placed (either as its own step or clearly noted under
"Parse input" per current design), and ensure the existing items "Handle
branch", "Parse input", "Classify intent", "Scan existing specs", and "Route to
action" appear with correct order and numbering exactly as shown in the diff so
the flow reflects the new Skill Discovery phase.
Comment on lines
+41
to
+72
| ## 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:<name>" })` | ||
| - 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 | ||
| - **<skill-name>**: matched (keywords: <overlapping words>) | ||
| - **<skill-name>**: no match | ||
| - **<skill-name>**: skipped (unreadable) | ||
| - **<skill-name>**: skipped (no description) | ||
| ``` | ||
| If no skills match: `- No skills matched` |
There was a problem hiding this comment.
Pass 1 discoveries are overwritten by state initialization in the normal-mode New Flow.
The execution order is:
- Step 3 (Pass 1) — invokes skills, then tries to write
discoveredSkillsto.ralph-state.json(Step 3.7), but.ralph-state.jsondoesn't exist yet for a brand-new spec. - New Flow step 7 — initializes
.ralph-state.jsonfrom scratch with"discoveredSkills": [], silently discarding whatever Pass 1 recorded. - New Flow step 12 (Pass 2) — reads
discoveredSkills: [](no Pass 1 records), bypassing deduplication and potentially re-invoking the same skills a second time.
This is in contrast to Quick Mode (quick-mode.md) which correctly initializes state before running Pass 1 (Step 5 → Step 9).
The root fix is to move Pass 1 to inside the New Flow, after state initialization (i.e., between current New Flow steps 7 and 8), matching the Quick Mode pattern. Alternatively, New Flow step 7 should explicitly merge rather than reset discoveredSkills if any were already accumulated.
Note: This bug only affects normal mode + new spec. Resume flow is unaffected since state already exists and is updated correctly at Step 3.7.
🛠️ Sketch of the fix (New Flow reordering)
Move the discovery block out of Step 3 and into the New Flow section:
-## 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.
-
-[full Pass 1 instructions...]
-
## Step 4: Scan Existing SpecsThen inside "### New Flow", after the current step 7 (state init) and before step 8 (create .progress.md):
7. Initialize `.ralph-state.json`:
{ ..., "discoveredSkills": [] }
+7a. **Skill Discovery Pass 1** -- scan skills, match against goal text, invoke matches
+ [full Pass 1 instructions, state write now safe since file was just created]
8. Create `.progress.md` with goalAlso update the Quick Mode Check note in Step 2 accordingly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/ralph-specum/commands/start.md` around lines 41 - 72, Pass 1
discovery results are being overwritten because New Flow initializes
.ralph-state.json after Step 3 writes discoveredSkills; move the Pass 1
discovery block so it runs after state initialization in the "New Flow" (i.e.,
run the skill discovery once the .ralph-state.json exists) or change the state
init to merge existing discoveredSkills instead of resetting them. Specifically,
relocate the Step 3 "Skill Discovery Pass 1" logic into the New Flow between
current step 7 (state init) and step 8 (create .progress.md) or modify the state
initialization to merge rather than replace discoveredSkills; ensure references
to .ralph-state.json and the discoveredSkills array are preserved and that
deduplication logic (checking invoked:true) still runs before invoking Skill({
skill: "ralph-specum:<name>" }).
Comment on lines
+162
to
+172
| 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 | ||
| - **<skill-name>**: matched (keywords: <overlapping words>) | ||
| - **<skill-name>**: no match (already invoked) | ||
| - **<skill-name>**: skipped (unreadable) | ||
| - **<skill-name>**: skipped (no description) | ||
| ``` | ||
| If no new skills match: `- No new skills matched` |
There was a problem hiding this comment.
Pass 2 "no match" log instruction disagrees with the template.
Line 162 instructs to log - No skills matched, but the progress template at line 172 shows - No new skills matched. The template wording is more appropriate for a second pass. Fix the inline instruction to match (same issue exists in quick-mode.md Step 12.6).
🛠️ Proposed fix
- 6. If no skills match across all scanned skills: log `- No skills matched`
+ 6. If no new skills match across all scanned skills: log `- No new skills matched`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 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 | |
| - **<skill-name>**: matched (keywords: <overlapping words>) | |
| - **<skill-name>**: no match (already invoked) | |
| - **<skill-name>**: skipped (unreadable) | |
| - **<skill-name>**: skipped (no description) | |
| ``` | |
| If no new skills match: `- No new skills matched` | |
| 6. If no new skills match across all scanned skills: log `- No new skills matched` | |
| 7. Update `.ralph-state.json` with updated `discoveredSkills` array | |
| 8. Append a `### Post-Research Retry` subsection to `.progress.md` under `## Skill Discovery`: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/ralph-specum/commands/start.md` around lines 162 - 172, Update the
second-pass logging instruction so the wording matches the progress template:
change the inline log text `- No skills matched` to `- No new skills matched` in
plugins/ralph-specum/commands/start.md (the step describing Pass 2 and the
Appendix "Post-Research Retry") and apply the same change in quick-mode.md Step
12.6 so both the instruction and the `### Post-Research Retry` template use the
exact phrase `- No new skills matched`.
Comment on lines
+147
to
+157
| 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 | ||
| - **<skill-name>**: matched (keywords: <overlapping words>) | ||
| - **<skill-name>**: no match (already invoked) | ||
| - **<skill-name>**: skipped (unreadable) | ||
| - **<skill-name>**: skipped (no description) | ||
| ``` | ||
| If no new skills match: `- No new skills matched` |
There was a problem hiding this comment.
Pass 2 "no match" log message is inconsistent between the instruction and the template.
Line 147 says to log - No skills matched, but the markdown template at line 157 shows - No new skills matched. For Pass 2, the template wording is more accurate since skills may have matched in Pass 1. The same inconsistency exists in start.md Pass 2 (lines 162/172).
🛠️ Proposed fix
-6. If no skills match across all scanned skills: log `- No skills matched`
+6. If no new skills match across all scanned skills: log `- No new skills matched`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 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 | |
| - **<skill-name>**: matched (keywords: <overlapping words>) | |
| - **<skill-name>**: no match (already invoked) | |
| - **<skill-name>**: skipped (unreadable) | |
| - **<skill-name>**: skipped (no description) | |
| ``` | |
| If no new skills match: `- No new skills matched` | |
| 6. If no new skills match across all scanned skills: log `- No new skills matched` | |
| 7. Update `.ralph-state.json` with updated `discoveredSkills` array | |
| 8. Append a `### Post-Research Retry` subsection to `.progress.md` under `## Skill Discovery`: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/ralph-specum/references/quick-mode.md` around lines 147 - 157,
Summary: The "Pass 2" no-match log wording is inconsistent between the
instruction and the Post-Research Retry template; standardize on "No new skills
matched". Fix: update the Pass 2 log instruction that currently says "- No
skills matched" to read "- No new skills matched" wherever it appears in
quick-mode.md and start.md, and ensure the "### Post-Research Retry" subsection
template under "## Skill Discovery" uses the same phrase; verify any references
to the Pass 2 message in related docs/templates are updated to keep wording
consistent.
|
|
||
| ### 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) |
There was a problem hiding this comment.
Stopword count is off by two.
The list has 23 words, not 25. Purely a documentation nit with no functional impact.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@specs/smart-skill-swap-retry/.progress.md` at line 32, The stopword count in
the line starting "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)" is incorrect; update the parenthetical count to "(23
words)" (or recount and adjust if you intend to add/remove words) so the text
matches the actual list length.
| - **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 |
There was a problem hiding this comment.
Grammar nit: hyphenate the compound modifier.
2 word overlap → 2-word overlap
🧰 Tools
🪛 LanguageTool
[grammar] ~346-~346: Use a hyphen to join words.
Context: ...eds, about (25 words) - Threshold: 2 word overlap -- prevents false positives...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@specs/smart-skill-swap-retry/tasks.md` at line 346, Update the phrasing for
the Threshold line in specs/smart-skill-swap-retry/tasks.md by hyphenating the
compound modifier: change the phrase "**Threshold**: 2 word overlap" to
"**Threshold**: 2-word overlap" so the compound adjective is grammatically
correct.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Skill({ skill: "ralph-specum:<name>" })with no user confirmation.ralph-state.jsondiscoveredSkillsarray with{ name, matchedAt, invoked }objects.progress.mdunder## Skill Discovery/### Post-Research RetrysectionsFiles Changed
plugins/ralph-specum/commands/start.md— Added Step 3 (Skill Discovery Pass 1) and step 12 (Pass 2) in normal mode flow; addeddiscoveredSkillsto state initplugins/ralph-specum/references/quick-mode.md— Added step 9 (Pass 1) and step 12 (Pass 2) in quick mode flow; addeddiscoveredSkillsto state initplugins/ralph-specum/.claude-plugin/plugin.json— Version bump 4.1.2 → 4.2.0.claude-plugin/marketplace.json— Version bump 4.1.2 → 4.2.0Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores