refactor: modernize module-help CSV format#2120
Conversation
…utcome-based skill New CSV format: module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs - Replace sequence numbers with after/before dependency graph - Drop command, workflow-file, agent, options columns - Add action column for multi-action skills (tech-writer, create-story) - Add args column for CLI shortcut hints - Make description optional (only when adding flow/routing context beyond frontmatter) - Expand module names for clarity - Rewrite bmad-help SKILL.md from procedural 8-step execution to outcome-based design - Fix eslint config to ignore gitignored lock files (pnpm-lock.yaml, bun.lock)
🤖 Augment PR SummarySummary: This PR modernizes the module help catalog format and refreshes the Changes:
Technical Notes: The new CSV schema is intended to be interpreted via the merged help catalog and dependency resolution, with artifact-based completion detection using resolved 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
|
|
||
| ## EXECUTION | ||
| ``` | ||
| module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs |
There was a problem hiding this comment.
This section defines a new 13-column help catalog schema (action/args/after/before)—please double-check that the generator/consumer for {project-root}/_bmad/_config/bmad-help.csv is updated to match, otherwise bmad-help may read the wrong columns/order at runtime.
Severity: high
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| For each recommended item, present: | ||
| - `[menu-code]` **Display name** — e.g., "[CP] Create PRD" | ||
| - Skill name in backticks — e.g., `bmad-create-prd` | ||
| - For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!" |
There was a problem hiding this comment.
The multi-action example (“tech-writer lets create a mermaid diagram!”) doesn’t clearly encode the action (and optional args) in a way the user can reliably repeat, which may prevent users from actually invoking the recommended action.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
📝 WalkthroughWalkthroughUpdated SKILL.md for bmad-help from a detailed step-by-step procedure to a condensed specification. Added explicit Purpose, Desired Outcomes, and Data Sources sections. Replaced granular workflow with CSV schema interpretation and simplified Response Format with ordering rules. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
🚥 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)
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: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/core-skills/bmad-help/SKILL.md`:
- Around line 41-48: Update the CSV Interpretation section of SKILL.md to add a
"Dependency resolution" subsection that defines handling for complex cases:
detect and break circular dependencies (e.g., A after=B and B after=A) by
prioritizing original catalog order; when multiple `required=true` items at the
same level have no `after`/`before` relationships, present them in catalog order
and state that any can be done first; treat dependencies that reference
non-existent skills as satisfied (optionally log or flag a warning); and accept
explicit user-reported completions even if artifacts aren't detected. Reference
the CSV fields `after`, `before`, `required=true`, and the `skill-name` /
`skill-name:action` format so implementers know which tokens to resolve.
- Line 63: Remove the fallback text "Description if present in CSV; otherwise
your existing knowledge of the skill suffices" from SKILL.md and replace it with
a strict instruction that a skill description must be present in the CSV and
must be used as the sole source for project-specific details (do not fabricate
or fill gaps from the model's prior knowledge); update any guidance text around
the skill description field to explicitly require CSV-provided descriptions and
to instruct the system to return an error or leave fields blank if the CSV lacks
a description (reference the exact phrase in SKILL.md to locate and update the
line).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 80d07456-fe1b-4de3-b2f4-25687241f49d
⛔ Files ignored due to path filters (3)
eslint.config.mjsis excluded by!eslint.config.mjssrc/bmm-skills/module-help.csvis excluded by!**/*.csvsrc/core-skills/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (1)
src/core-skills/bmad-help/SKILL.md
| **Dependencies** determine ordering within and across phases: | ||
| - `after` — skills that should ideally complete before this one | ||
| - `before` — skills that should run after this one | ||
| - Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills | ||
|
|
||
| 3. **Ground in project knowledge** — If `project_knowledge` resolves to an existing path, read available documentation files (architecture docs, project overview, tech stack references) for grounding context. Use discovered project facts when composing any project-specific output. Never fabricate project-specific details — if documentation is unavailable, state so. | ||
| **Required gates**: | ||
| - `required=true` items must complete before the user can meaningfully proceed to later phases | ||
| - A phase with no required items is entirely optional — recommend it but be clear about what's actually required next |
There was a problem hiding this comment.
Missing guidance on complex dependency scenarios.
The CSV Interpretation section doesn't address:
- Circular dependencies: What if skill A has
after=Band skill B hasafter=A? - Multiple required items: Line 66 says "then the next required item" but what if multiple required items exist at the same level with no dependency relationship?
- Broken chains: What if a required skill has
after=Xbut skill X doesn't exist in the catalog?
These scenarios could cause the skill to provide contradictory or incorrect recommendations.
📋 Suggested additions to CSV Interpretation
Add a Dependency Resolution subsection:
**Dependency resolution**:
- If circular dependencies are detected, break the cycle by prioritizing items earlier in the original catalog order
- When multiple required items have no mutual dependencies, present them in catalog order but make it clear any can be tackled first
- If a dependency references a non-existent skill, treat it as satisfied (log warning if possible)
- If user explicitly states completion of a step not detected via artifacts, trust the user's statement🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core-skills/bmad-help/SKILL.md` around lines 41 - 48, Update the CSV
Interpretation section of SKILL.md to add a "Dependency resolution" subsection
that defines handling for complex cases: detect and break circular dependencies
(e.g., A after=B and B after=A) by prioritizing original catalog order; when
multiple `required=true` items at the same level have no `after`/`before`
relationships, present them in catalog order and state that any can be done
first; treat dependencies that reference non-existent skills as satisfied
(optionally log or flag a warning); and accept explicit user-reported
completions even if artifacts aren't detected. Reference the CSV fields `after`,
`before`, `required=true`, and the `skill-name` / `skill-name:action` format so
implementers know which tokens to resolve.
| - `[menu-code]` **Display name** — e.g., "[CP] Create PRD" | ||
| - Skill name in backticks — e.g., `bmad-create-prd` | ||
| - For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!" | ||
| - Description if present in CSV; otherwise your existing knowledge of the skill suffices |
There was a problem hiding this comment.
Remove fallback to "existing knowledge".
Line 63 states "Description if present in CSV; otherwise your existing knowledge of the skill suffices" — this could cause hallucinations. If a skill lacks a description in the CSV and the LLM doesn't have accurate knowledge, it may fabricate details.
🛡️ Proposed fix
-- Description if present in CSV; otherwise your existing knowledge of the skill suffices
+- Description if present in CSV; if absent, show only the display name and skill ID without elaborating on behaviorThis aligns with the "Never fabricate project-specific details" constraint from line 27.
📝 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.
| - Description if present in CSV; otherwise your existing knowledge of the skill suffices | |
| - Description if present in CSV; if absent, show only the display name and skill ID without elaborating on behavior |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core-skills/bmad-help/SKILL.md` at line 63, Remove the fallback text
"Description if present in CSV; otherwise your existing knowledge of the skill
suffices" from SKILL.md and replace it with a strict instruction that a skill
description must be present in the CSV and must be used as the sole source for
project-specific details (do not fabricate or fill gaps from the model's prior
knowledge); update any guidance text around the skill description field to
explicitly require CSV-provided descriptions and to instruct the system to
return an error or leave fields blank if the CSV lacks a description (reference
the exact phrase in SKILL.md to locate and update the line).
1 participant
Summary
core-skills/module-help.csvandbmm-skills/module-help.csvto new 13-column formatafter/beforedependency graphcommand,workflow-file,agent,optionscolumns; addaction,argscolumnsbmad-helpSKILL.md from procedural 8-step execution to outcome-based design (~50% shorter)pnpm-lock.yaml,bun.lock)New CSV format
Test plan