silver-validate

/silver:validate — Pre-Build Gap Analysis

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.

Pre-flight: Load Preferences

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

Step-Skip Protocol

When the user requests skipping any step:

1. Explain why the step exists (one sentence)
2. Offer: A. Accept skip B. Lightweight alternative C. Show me what you have
3. If user chooses A permanently: record in silver-bullet.md §10b and templates/silver-bullet.md.base §9b, commit both.

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.

Step 0: Pre-flight Checks

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}

1. 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).

2. 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
   

Step 1: Read SPEC.md (NON-SKIPPABLE GATE — spec mode only)

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:

• Assumption text
• Status field value (Accepted / Follow-up-required / Blocking)
• Owner field value

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"}

Step 2: Read PLAN.md Files

Scan .planning/phases/ for PLAN.md files in the current phase:

find .planning/phases/ -name "*PLAN.md" | sort

For each PLAN.md found, extract:

• Plan name and phase
• Task names (from <name> elements or ## Task N: headings)
• files_modified list (from frontmatter)
• requirements list (from frontmatter) — these are spec traceability links

Build a coverage map:

• For each task: record which requirement IDs it claims to address
• Map requirement IDs back to AC items where possible (by ID pattern match or keyword)

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}

Step 3: Gap Analysis (NON-SKIPPABLE GATE)

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:

• References the AC's requirement ID in its requirements frontmatter, OR
• Contains the AC item text (or key noun phrases) in its task name or description

If 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

Step 4: Surface Assumptions (VALD-05)

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.

Step 5: User Decision Gate (NON-SKIPPABLE GATE)

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:

• No *PLAN.md file exists under .planning/phases/ (should have been caught in Step 0)
• Any scanned PLAN.md has zero implementation tasks
• Any PLAN.md task lacks verification or acceptance evidence (test command, provider plan/dry-run, policy check, or explicit rollback note for infra work)

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.

Step 6: Write .planning/VALIDATION.md

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.

Step 7: Summary Banner

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.