From silver-bullet
Validates SPEC.md coverage in PLAN.md files before build, surfacing assumptions and emitting BLOCK/WARN/INFO findings. Use for pre-build gap analysis.
How this skill is triggered — by the user, by Claude, or both
Slash command
/silver-bullet:silver-validateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Pre-build validation skill. Reads `.planning/SPEC.md` and `.planning/phases/` PLAN.md files, performs gap analysis between acceptance criteria and implementation plans, surfaces all assumptions, and emits machine-readable FINDING lines. BLOCK findings must be resolved before implementation begins.
Pre-build validation skill. Reads .planning/SPEC.md and .planning/phases/ PLAN.md files, performs gap analysis between acceptance criteria and implementation plans, surfaces all assumptions, and emits machine-readable FINDING lines. BLOCK findings must be resolved before implementation begins.
Never modifies SPEC.md or PLAN.md files. Read-only analysis, write-only to .planning/VALIDATION.md.
Read the User Workflow Preferences section of silver-bullet.md to load user workflow preferences before any other step.
grep -A 50 "^## [0-9]\+\. User Workflow Preferences" silver-bullet.md | head -60
Display banner:
SILVER BULLET ► VALIDATE
When the user requests skipping any step:
Non-skippable gates: Step 1 (Read SPEC.md), Step 3 (Gap Analysis), Step 5 (User Decision Gate). These cannot be skipped under any circumstances — they are the core validation contract.
Detect validation mode before parsing artifacts:
test -f .planning/SPEC.md && echo "spec-mode" || echo "no-spec"
find .planning/phases/ -name "*PLAN.md" 2>/dev/null | head -1
Spec mode (default): .planning/SPEC.md exists — run full SPEC ↔ PLAN gap analysis (Steps 1 and 3a).
Plan-only mode: .planning/SPEC.md is absent but at least one *PLAN.md exists under .planning/phases/. Use this for silver:devops, silver:fast Tier 2, and other infra-only work where workflow-chain-guard requires a silver:validate marker before implementation edits but no product SPEC exists yet. Skip Step 1 and Step 3a (AC coverage); run Steps 2, 3b–3d, and 3f only.
Display mode in the banner:
Mode: {spec | plan-only}
Verify .planning/SPEC.md exists:
ls .planning/SPEC.md
If missing and no *PLAN.md exists under .planning/phases/:
FINDING [BLOCK] VAL-000: Neither SPEC.md nor PLAN.md found — nothing to validate
Spec ref: pre-flight
Plan ref: missing
Resolution: Run /silver:plan (or /silver:spec for product work) before /silver:validate
Exit after emitting VAL-000 when neither artifact exists.
If missing but PLAN.md exists: continue in plan-only mode (do not emit VAL-000 as BLOCK).
Check for PLAN.md files in .planning/phases/:
find .planning/phases/ -name "*PLAN.md" 2>/dev/null
If none found: emit the following (INFO only — validation can still run for pre-planning awareness):
FINDING [INFO] VAL-001: No PLAN.md files found in .planning/phases/
Spec ref: pre-flight
Plan ref: missing
Resolution: Validation is running in pre-planning mode — gap analysis will show all AC items as uncovered
Skip this entire step in plan-only mode. In spec mode, do not proceed until SPEC.md is fully parsed.
Read .planning/SPEC.md and extract:
1a. Acceptance Criteria
Parse the ## Acceptance Criteria section. Extract each checklist item (lines starting with - [ ] or - [x]). Number them sequentially: AC-01, AC-02, etc.
1b. Assumptions
Parse all [ASSUMPTION: ... | Status: ... | Owner: ...] blocks from SPEC.md. Extract:
1c. Open Questions
Parse the ## Open Questions section if present. Extract each open item.
1d. Spec metadata
Read frontmatter fields: spec-version, jira-id (if present).
After parsing, display summary:
SPEC.md parsed:
Acceptance Criteria: {N} items (AC-01 through AC-NN)
Assumptions: {N} total ({A} Accepted, {F} Follow-up-required, {B} Blocking)
Open Questions: {N} items
Spec version: {spec-version or "not set"}
Scan .planning/phases/ for PLAN.md files in the current phase:
find .planning/phases/ -name "*PLAN.md" | sort
For each PLAN.md found, extract:
<name> elements or ## Task N: headings)files_modified list (from frontmatter)requirements list (from frontmatter) — these are spec traceability linksBuild a coverage map:
Display summary:
PLAN.md files scanned: {N}
Tasks found: {T} across {N} plans
Tasks with requirement IDs: {R}
Tasks without requirement IDs (orphan candidates): {O}
This step cannot be skipped. Run every subsection that applies to the active mode (spec vs plan-only).
3a. AC Coverage Check (BLOCK severity — spec mode only)
Skip 3a entirely in plan-only mode (no acceptance criteria without SPEC.md).
For each AC item (AC-01 through AC-NN): check whether any PLAN.md task:
requirements frontmatter, ORIf NO task addresses an AC item:
FINDING [BLOCK] VAL-{NNN}: Acceptance criterion AC-{NN} has no coverage in any PLAN.md
Spec ref: ## Acceptance Criteria, item {AC-NN}: "{criterion text}"
Plan ref: missing
Resolution: Add a PLAN.md task that implements this criterion, or remove it from SPEC.md if out of scope
3b. Assumption Status Check (WARN/INFO severity)
For each assumption parsed in Step 1b:
If Status is Follow-up-required:
FINDING [WARN] VAL-{NNN}: Assumption requires follow-up before implementation
Spec ref: [ASSUMPTION: {assumption text}] Status: Follow-up-required, Owner: {owner}
Plan ref: {task if referenced, else "not addressed in any task"}
Resolution: Resolve assumption status with {owner} before beginning implementation
If Status is Blocking:
FINDING [BLOCK] VAL-{NNN}: Blocking assumption not resolved
Spec ref: [ASSUMPTION: {assumption text}] Status: Blocking, Owner: {owner}
Plan ref: {task if referenced, else "not addressed in any task"}
Resolution: This assumption must be resolved before any implementation begins — contact {owner}
If Status is Accepted:
FINDING [INFO] VAL-{NNN}: Assumption accepted — surfaced for developer awareness
Spec ref: [ASSUMPTION: {assumption text}] Status: Accepted, Owner: {owner}
Plan ref: awareness only
Resolution: No action required — assumption is accepted
3c. Orphan Task Check (WARN severity)
For each PLAN.md task that has NO requirement IDs in frontmatter AND no detectable link to any AC item:
FINDING [WARN] VAL-{NNN}: Orphan task — no traceability to SPEC.md
Spec ref: missing
Plan ref: "{task name}" in {plan file}
Resolution: Add a requirements: [AC-NN, ...] field to this task's PLAN.md frontmatter, or confirm the task is infrastructure/chore (not feature work)
3d. Open Question Check (WARN severity)
For each open question from Step 1c that is not marked resolved:
FINDING [WARN] VAL-{NNN}: Open question unresolved
Spec ref: ## Open Questions, item: "{question text}"
Plan ref: missing
Resolution: Answer or defer this question before implementation to avoid mid-build scope changes
After all checks complete, tally findings:
Gap analysis complete:
BLOCK: {B} findings
WARN: {W} findings
INFO: {I} findings
Print ALL [ASSUMPTION] blocks from SPEC.md as a numbered awareness list regardless of their status. This is mandatory — developers must see all assumptions before implementation begins.
## Assumptions Awareness (VALD-05)
The following assumptions underpin this spec. Review before implementing.
{N}. [ASSUMPTION: {text}]
Status: {status} | Owner: {owner}
{N+1}. [ASSUMPTION: {text}]
Status: {status} | Owner: {owner}
... (all assumptions listed)
If SPEC.md contains zero assumptions, display:
## Assumptions Awareness (VALD-05)
No [ASSUMPTION: ...] blocks found in SPEC.md.
Consider whether implicit assumptions exist that should be made explicit.
This step cannot be skipped. User must acknowledge findings before proceeding.
If any BLOCK findings exist:
Display all BLOCK findings prominently:
VALIDATION BLOCKED — {B} BLOCK FINDING(S)
{list all BLOCK findings with full FINDING format}
Then ask:
BLOCK findings must be resolved before implementation begins. What would you like to do?
A. Return to {/silver:spec in spec mode | /silver:plan in plan-only mode} to resolve the gaps B. Show me the BLOCK findings again C. I have resolved the issues — re-run /silver:validate
Do NOT allow proceeding to Step 6 while BLOCK findings exist. If user selects C, restart from Step 0.
Plan-only mode — additional BLOCK rules (3f):
When SPEC.md is absent, emit BLOCK (not advisory) when:
*PLAN.md file exists under .planning/phases/ (should have been caught in Step 0)Emit WARN (not BLOCK) for infra plans missing rollback notes when the change is clearly reversible/config-only.
If only WARN/INFO findings (zero BLOCKs):
Display findings summary:
VALIDATION ADVISORY — {W} WARN, {I} INFO
{list WARN findings}
{list INFO findings}
Then ask:
WARN findings will be recorded in .planning/VALIDATION.md and will appear in the PR description.
A. Accept and proceed — write VALIDATION.md and continue B. Return to {/silver:spec in spec mode | /silver:plan in plan-only mode} to address WARN findings first C. Show me all findings again
Only proceed to Step 6 when user selects A.
If zero findings of any severity:
Display:
VALIDATION CLEAN — ZERO FINDINGS
{In spec mode: All acceptance criteria are covered. No unresolved assumptions or open questions.}
{In plan-only mode: PLAN.md is actionable with verification evidence. No blocking gaps.}
Automatically proceed to Step 6.
Write .planning/VALIDATION.md using the active runtime file-writing mechanism with ALL findings in machine-readable format.
This file is consumed by pr-traceability.sh (Plan 02) to populate PR description deferred items.
---
validation-mode: {spec | plan-only}
spec-version: {spec-version from SPEC.md frontmatter, or "n/a" in plan-only mode}
validation-date: {today's date in YYYY-MM-DD}
finding-counts:
block: {B}
warn: {W}
info: {I}
---
# Validation Findings
Generated by /silver:validate on {date}. Consumed by pr-traceability.sh for PR description.
## BLOCK Findings
{Each BLOCK finding in exact format:}
FINDING [BLOCK] VAL-{NNN}: {description}
Spec ref: {section and item}
Plan ref: {task or "missing"}
Resolution: {required action}
## WARN Findings
{Each WARN finding in exact format:}
FINDING [WARN] VAL-{NNN}: {description}
Spec ref: {section and item}
Plan ref: {task or "missing"}
Resolution: {required action}
## INFO Findings
{Each INFO finding in exact format:}
FINDING [INFO] VAL-{NNN}: {description}
Spec ref: {section and item}
Plan ref: awareness only
Resolution: {action or "No action required"}
If zero findings, write an empty findings file:
---
spec-version: {spec-version}
validation-date: {date}
finding-counts:
block: 0
warn: 0
info: 0
---
# Validation Findings
No findings — all acceptance criteria covered, no unresolved assumptions or open questions.
Display final summary:
VALIDATION COMPLETE
Findings: {B} BLOCK, {W} WARN, {I} INFO
Assumptions surfaced: {N}
Status: {PASS (no BLOCK findings) | BLOCKED (has BLOCK findings)}
Findings written to: .planning/VALIDATION.md
If Status is PASS, the workflow may proceed to implementation. If Status is BLOCKED, implementation is gated until BLOCK findings are resolved.
npx claudepluginhub alo-exp/silver-bullet --plugin silver-bulletGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.