---

name: prep-spec description: Prepare a spec for implementation with agent reviews and execution recommendation. Orchestrates UX Designer, Architect, and optionally TEA agents for comprehensive review, then recommends /loop, /loop --with-checkpoints, or ralph-loop based on requirements count, integration points, and risk keywords. when_to_use: before implementing a feature spec, to catch blindspots and choose the right execution strategy version: 1.2.0

/prep-spec

Prepare a feature specification for implementation with multi-agent review and execution recommendation.

Announce at start: "Reviewing spec with UX and Architect agents..."

Usage

Copy/prep-spec <path-to-spec> [--skip-ux] [--include-tea] [--force] [--save-report]

Parameters

---

Process

Step 0: Pre-Check

1. Read spec file — If not found, error with suggestion
2. Check frontmatter — If status: prepped already set, stop unless --force

Step 1: Quick Analysis

Extract key metrics:

Output:

CopyRequirements: {N} | Phases: {N} | Integrations: {N} | Risk: {keywords or "none"} | UI: {yes/no}

Step 2: Agent Reviews (Sequential)

Run agents in sequence: UX → Architect → TEA (if --include-tea).

UX Designer (skip if --skip-ux or no UI):

• User flow completeness
• Edge cases (error/empty/loading states)
• Accessibility gaps
• Mobile considerations

Architect:

• Technical blindspots
• Existing code reuse
• Architectural fit
• Dependencies
• Context pressure (single session fit?)
• Integration depth — For features modifying existing flows, trace the full pipeline: what triggers it, what it triggers, what data flows where. Flag any ungated paths that contradict the spec's intent as BLOCKERS, not warnings.

TEA (only if --include-tea):

• Testability
• Test strategy gaps
• E2E vs unit coverage

Step 3: Output Findings Directly to Chat

CRITICAL: Output all findings immediately in chat, organized by severity.

Format:

Copy## Findings

### Blockers
- [BLOCKER] {finding} — {source: UX/Architect/TEA}
- [BLOCKER] {finding} — {source}

### Warnings
- [WARNING] {finding} — {source}

### Suggestions
- [SUGGESTION] {finding} — {source}

If no blockers: "No blockers found." If no warnings: "No warnings." If no suggestions: "No suggestions."

Step 4: Output Decisions Using /simplify Format

After findings, output decisions table directly in chat:

Copy## Decisions Needed

| # | Question | Options | My Pick |
|---|----------|---------|---------|
| 1 | {question} | A) {opt1} B) {opt2} | A — {reason} |
| 2 | {question} | A) {opt1} B) {opt2} | B — {reason} |

If no decisions needed: "No decisions needed — spec is clear."

Step 5: Recommend Execution Path

Decision logic:

CopyIF blockers > 0:
  → BLOCKED (resolve first)
ELSE IF risk_keywords_found OR integration_points >= 3:
  → ralph-loop (high risk/complexity)
ELSE IF requirements >= 12 OR phases >= 3:
  → /loop --with-checkpoints (medium complexity)
ELSE:
  → /loop (simple)

Thresholds:

Risk keywords: auth, payment, migration, security, breaking change, RLS

Output recommendation:

Copy## Execution

**Recommendation:** {/loop | /loop --with-checkpoints | ralph-loop | BLOCKED}
**Reason:** {brief explanation}

{If /loop}
Ready to implement. Run `/loop` and describe the task.

{If /loop --with-checkpoints}
Medium complexity. Use `/loop` but pause after each phase for review.

{If ralph-loop}
Run: `/generate-ralph-loop features/{spec-name}_acceptance_tests.md`

{If BLOCKED}
Resolve blockers first, then re-run `/prep-spec --force`.

Step 6: Update Spec Frontmatter

Add YAML frontmatter to spec file:

Copy---
status: prepped
prepped_date: {YYYY-MM-DD}
prepped_by: /prep-spec
reviews:
  ux: {passed|failed|skipped}
  architect: {passed|failed|skipped}
  tea: {passed|failed|skipped}
execution: {/loop|/loop --with-checkpoints|ralph-loop|blocked}
---

Step 7: Save Report (Optional)

Only save to file if --save-report flag is used or there are 5+ findings.

Otherwise, all output goes directly to chat — no file created.

If saving: bmad/artifacts/{spec-name}-review.md

Step 8: Generate UAT (if ralph-loop)

If recommendation is ralph-loop:

1. Call /generate-uat {spec_path}
2. Update frontmatter with uat_file path

---

Output Template (Direct to Chat)

ALL output goes directly to chat. Keep it scannable.

Copy## {Spec Name} — Review

**Requirements:** {N} | **Phases:** {N} | **Integrations:** {N} | **Risk:** {keywords or "none"} | **UI:** {yes/no}

---

### Blockers
{list or "None"}

### Warnings
{list or "None"}

### Suggestions
{list or "None"}

---

### Decisions Needed

| # | Question | Options | My Pick |
|---|----------|---------|---------|
{table rows or "No decisions needed — spec is clear."}

---

### Execution

**{/loop | /loop --with-checkpoints | ralph-loop | BLOCKED}** — {brief reason}

{next step: command to run or blockers to resolve}

---

Blocker Criteria

A finding is a BLOCKER (not a warning) if:

• The spec's core intent cannot be achieved without addressing it
• Existing code contradicts the spec (e.g., unconditional recording when spec requires consent gating)
• Identity, terminology, or schema is undefined/wrong
• A race condition or data loss could occur

When in doubt: if the feature would be broken without fixing it, it's a blocker.

---

Edge Cases

---

Dependencies

• /bmad:bmm:agents:ux-designer — UX review
• /bmad:bmm:agents:architect — Architecture review
• /bmad:bmm:agents:tea — Testability review (optional)
• /generate-uat — UAT file generation (if ralph-loop)