/bmad-readiness-check

name: bmad-readiness-check
description: |
  SOLUTIONING GATE — validates cohesion across planning artifacts before any
  implementation begins. Cross-references PRD (or tech-spec), architecture document,
  and epics/stories for coverage consistency and missing pieces. Returns a verdict
  of PASS, CONCERNS, or FAIL with specifics. Does NOT touch code.

  Use when the user says:
  - "check if we're ready to build" / "are we ready to implement?"
  - "validate planning" / "gate check" / "readiness check"
  - "run the solutioning gate" / "check implementation readiness"
  - "is the architecture complete?" / "do requirements match architecture?"
  - "sign off on planning" / "planning done, check it"
  - "validate PRD against architecture" / "cross-reference planning docs"

  Intents supported: Validate (primary).
  Track-adaptive: works for Quick Flow (tech-spec + architecture), BMad Method
  (PRD + architecture + epics), and Enterprise (all of the above + optional
  security/DevOps addenda).
allowed-tools: Read, Write, Bash, Glob, Grep, TodoWrite

BMAD Readiness Check

**"Planning ends here."** This skill is the gate between Solutioning and Implementation. It validates that the planning corpus is internally consistent — requirements are covered by architecture, epics trace back to requirements, and nothing critical is missing — before a single line of code is written.

The output is a `readiness-report.md` with a clear PASS / CONCERNS / FAIL verdict and actionable specifics.

---

Workflow

Use TodoWrite to track: Load Artifacts → Cross-Reference → Quality Checks → Generate Report → Display Verdict.

---

Step 1 — Locate Planning Artifacts

Run the bundled existence check:

bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-readiness-check/scripts/readiness-check.sh" <output-folder>

The script checks for required artifact files and prints a PASS / CONCERNS / FAIL pre-flight verdict. Read its output; it will also print artifact paths for you to load in Step 2.

Default search root is `bmad-output/` (or the user-configured `outputFolder`). If the user supplies a custom path, pass it as the argument.

---

Step 2 — Load and Parse Artifacts

Read each artifact the script located:

**Requirements document** (PRD or tech-spec):

• Extract labelled Functional Requirements (FR-001, FR-002 …) or requirement

bullets if not labelled.

• Extract Non-Functional Requirements (NFR-001 … or named sections:

Performance, Security, Scalability, Reliability, Maintainability).

• Note epic count and high-level scope statements.

**Architecture document**:

• Extract system components and their responsibilities.
• Locate FR traceability matrix or explicit FR-to-component mappings.
• Locate NFR coverage sections.
• Note technology stack decisions and trade-off notes.

**Epics / stories** (if present):

• Count epics and stories.
• For each epic, identify which PRD requirement(s) it references.

Record a baseline:

Baseline
- FRs found: N
- NFRs found: N
- Epics found: N  (0 if Quick Flow)
- Stories found: N  (0 if not yet decomposed)

---

Step 3 — Cross-Reference Checks

3a. FR → Architecture Coverage

For each FR, search the architecture document for the FR identifier AND for the subject matter of the requirement. Mark:

• **Covered** — FR explicitly addressed, component assigned.
• **Implied** — subject matter covered but not explicitly linked.
• **Missing** — no evidence of coverage.

3b. NFR → Architecture Coverage

For each NFR category, check for a dedicated architecture section or explicit strategy:

• Performance: caching, response-time targets, async patterns.
• Security: auth/authz model, encryption, secrets management.
• Scalability: horizontal/vertical strategy, load balancing.
• Reliability: failover, backup, uptime targets.
• Others as present.

Mark each: **Addressed** / **Partial** / **Missing**.

3c. Epic → FR Traceability (BMad Method / Enterprise tracks)

For each epic, verify it references at least one FR or PRD section. Flag orphan epics (no traceable requirement).

3d. Architecture Quality Spot-Checks

Verify the architecture document contains:

• [ ] Architectural pattern stated and justified
• [ ] Component responsibilities and interfaces defined
• [ ] Data model / entity relationships
• [ ] API design or service contracts
• [ ] Technology choices with rationale
• [ ] Trade-offs documented
• [ ] Assumptions and constraints listed

---

Step 4 — Compute Verdict

Apply these thresholds (adapted from BMAD Method v6 gate criteria, expressed as PASS / CONCERNS / FAIL):

| Criterion | PASS | CONCERNS | FAIL | |-----------|------|----------|------| | FR coverage (covered + implied) | ≥ 90 % | 80–89 % | < 80 % | | NFR coverage (addressed + partial) | ≥ 90 % | 80–89 % | < 80 % | | Architecture quality checks | ≥ 80 % | 70–79 % | < 70 % | | Blocker issues (critical gaps) | 0 | have mitigation | unmitigated | | Epic traceability (if applicable) | all linked | ≥ 80 % linked | < 80 % |

**Overall verdict rule:**

• **PASS** — all criteria at PASS threshold, no blockers.
• **CONCERNS** — one or more criteria in CONCERNS band, blockers have

mitigation plans. Proceed with caution; address concerns during story refinement.

• **FAIL** — any criterion below CONCERNS threshold, or any unmitigated

blocker. Do not proceed to story creation until issues are resolved.

---

Step 5 — Generate Report

Write the readiness report using the template:

${CLAUDE_PLUGIN_ROOT}/skills/bmad-readiness-check/templates/readiness-report.template.md

Save to: `<outputFolder>/readiness-report-<project-slug>-<date>.md`

Use the Write tool. Fill all `{{placeholder}}` fields from your analysis.

---

Step 6 — Display Verdict

Print a concise summary to the user:

Readiness Check Complete

Artifact Coverage
  FR coverage:          XX %
  NFR coverage:         XX %
  Architecture quality: XX %

Verdict: PASS | CONCERNS | FAIL

<One-sentence rationale>

Report s