From silver-bullet
Reviews ROADMAP.md files for quality: validates required phase fields, 100% requirement coverage, no phantom requirements, no circular dependencies, success criteria derivation, and plans completeness.
How this skill is triggered — by the user, by Claude, or both
Slash command
/silver-bullet:review-roadmap <roadmap-path> [--source-inputs <requirements-path>]<roadmap-path> [--source-inputs <requirements-path>]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
ROADMAP.md reviewer skill. Implements the artifact-reviewer framework interface to validate a ROADMAP.md file against the SB roadmap quality criteria. Returns structured PASS/ISSUES_FOUND findings.
ROADMAP.md reviewer skill. Implements the artifact-reviewer framework interface to validate a ROADMAP.md file against the SB roadmap quality criteria. Returns structured PASS/ISSUES_FOUND findings.
This reviewer MUST load the following before executing any review:
@skills/artifact-reviewer/rules/reviewer-interface.md — interface contract (input/output shape, prohibitions)@skills/artifact-reviewer/rules/review-loop.md — 2-pass loop mechanism and audit trail format/artifact-reviewer <roadmap-path> [--source-inputs <requirements-path>]
Or invoke directly:
/review-roadmap <roadmap-path> [--source-inputs <requirements-path>]
| Field | Type | Required | Description |
|---|---|---|---|
| artifact_path | string | YES | Path to ROADMAP.md file to review |
| source_inputs[0] | string | NO | Path to REQUIREMENTS.md for cross-reference |
| review_context | string | NO | Additional context string |
Read the artifact at artifact_path completely before evaluating any criterion. Validate every criterion explicitly — do NOT skip sections.
For each phase defined in the roadmap, verify all four fields are present and non-empty:
[goal text] or TBDNone for the first phase, but field must exist)None for infrastructure phases, but field must exist)If any phase is missing a required field or has a placeholder value: Emit ISSUE finding ROAD-F01 with location = the phase name and missing field, suggestion = "Fill in the [field] for Phase [N] with real content. 'Depends on: None' is valid for the first phase."
Only evaluate this criterion when source_inputs contains a requirements path.
Procedure:
source_inputs[0]REQ-nn and NFR-nn)If any orphaned requirement exists: Emit ISSUE finding ROAD-F10 with location = the orphaned requirement ID, suggestion = "Add [REQ-ID] to the Requirements field of the phase where it will be implemented, or create a new phase if no existing phase covers it."
Every requirement ID referenced in any phase's Requirements field MUST exist in the linked Requirements file (when source_inputs provided), OR — if no requirements file is provided — must follow the REQ-nn/NFR-nn format.
If any phase references a requirement ID that doesn't exist in the Requirements file: Emit ISSUE finding ROAD-F20 with location = the phase name and phantom ID, suggestion = "Either add [REQ-ID] to REQUIREMENTS.md with its full definition, or remove it from Phase [N]'s Requirements field."
Verify the phase dependency graph has no issues:
INSERTED in the phase name or description)Procedure: build a dependency graph from all Depends on: fields, detect cycles and backward references.
If circular dependency found: Emit ISSUE finding ROAD-F30 with location = the phases involved in the cycle, suggestion = "Break the dependency cycle between [Phase A] and [Phase B] by removing one dependency direction or reordering the phases."
If backward reference found (not INSERTED): Emit ISSUE finding ROAD-F31 with location = the referencing phase, suggestion = "Phase [N] depends on Phase [M] which comes later. Either reorder the phases or mark Phase [N] as INSERTED if it was added out of sequence."
For each phase, every Success Criterion in the Success Criteria field should trace to at least one requirement in that phase's Requirements field. A success criterion that references outcomes entirely unrelated to the listed requirements is a traceability gap.
This check applies best-effort alignment: look for semantic overlap between the success criterion language and the requirement descriptions. Do not fail on criteria for infrastructure phases with no requirements.
If a Success Criterion has no traceable requirement in the phase: Emit ISSUE finding ROAD-F40 with location = the phase and criterion, suggestion = "Either add a requirement to Phase [N] that this success criterion traces to, or rewrite the criterion to reflect the phase's actual requirements."
For each phase in the roadmap:
TBD in the Plans fieldIf a completed phase has an empty Plans field: Emit ISSUE finding ROAD-F50 with location = the phase name, suggestion = "Add the list of plan files that implemented Phase [N] to the Plans field, e.g., 01-PLAN.md, 02-PLAN.md."
If an upcoming phase has no Plans field at all: Emit ISSUE finding ROAD-F51 with location = the phase name, suggestion = "Add Plans: TBD to Phase [N] as a placeholder until plans are drafted."
Return structured findings using the schema from reviewer-interface.md. Finding IDs MUST use the prefix ROAD-F.
status: "PASS" | "ISSUES_FOUND"
findings:
- id: "ROAD-F01" # unique within this review
severity: "ISSUE" # or "INFO"
description: "..." # what is wrong
location: "..." # section header or line reference
suggestion: "..." # specific, actionable fix
Status rules:
PASS — zero ISSUE-severity findings; INFO findings allowedISSUES_FOUND — one or more ISSUE-severity findingsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub alo-exp/silver-bullet --plugin silver-bullet