BMAD Synthesize

Auto-generate BMAD planning artifacts from StackShift reverse-engineering documentation.

Estimated Time: 10-30 minutes (depending on mode) Prerequisites: Gear 2 (Reverse Engineer) completed with 9+ docs Output: 4 BMAD artifacts in _bmad-output/planning-artifacts/

Compatibility

Reverse Engineer Version Docs Produced Coverage

v2.0+ (11 docs) Full set 100%

v1.x (9 docs) Missing business-context, decision-rationale ~85% average

Both are fully supported. With 9 docs, some sections will use inferred content from related docs, clearly marked with [INFERRED FROM: source-doc] .

When to Use This Skill

Use this skill when:

• Gear 2 has generated 9+ reverse-engineering docs

• You want BMAD artifacts without running the full BMAD conversation flow

• You chose bmad-autopilot as the implementation framework in Gear 1

• You want to convert existing reverse-engineering docs into BMAD format

• You need a PRD, Architecture doc, Epics, or UX spec generated from code analysis

Trigger Phrases:

• "Generate BMAD artifacts from reverse-engineering docs"

• "Create PRD from the codebase analysis"

• "Auto-generate BMAD planning documents"

• "Synthesize BMAD artifacts"

• "Run BMAD auto-pilot"

What This Skill Does

Reads all available reverse-engineering docs (9 core + 2 optional) and maps their content into 4 BMAD planning artifacts:

BMAD Artifact Primary Source Docs Coverage (11 docs) Coverage (9 docs) Fallback Sources for Optional Docs

prd.md

functional-specification, business-context [OPTIONAL], technical-debt-analysis, integration-points ~90% ~80% business-context fallback: functional-specification (Executive Summary, User Stories, Success Criteria) + visual-design-system (persona UX context)

architecture.md

data-architecture, integration-points, operations-guide, decision-rationale [OPTIONAL], configuration-reference, observability-requirements ~85% ~75% decision-rationale fallback: configuration-reference (tech stack, framework choices) + data-architecture (schema design decisions) + integration-points (integration choice rationale)

epics.md

functional-specification (FRs grouped by domain), business-context [OPTIONAL] (personas), technical-debt-analysis (migration matrix) ~75% ~70% business-context fallback: functional-specification (User Personas, Product Positioning)

ux-design-specification.md

visual-design-system, business-context [OPTIONAL] (personas), functional-specification (user stories) ~65% ~55% business-context fallback: functional-specification (User Personas) + visual-design-system (user flows, accessibility)

Three Modes

Mode 1: YOLO (Fully Automatic)

Time: ~10 minutes User input: None

• Maps all available docs (9-11) to BMAD artifacts automatically

• For questions the docs can't answer, infers from available context

• Treats [INFERRED] items as accepted

• Resolves [NEEDS USER INPUT] items with best-effort inference

• Generates all 4 artifacts in one shot

Best for: Quick artifact generation, overnight runs, batch processing, when you plan to refine later.

Mode 2: Guided (Recommended)

Time: ~15-20 minutes User input: 5-10 targeted questions

• Auto-populates everything the docs can answer (high confidence)

• Presents targeted questions ONLY for genuinely ambiguous items:

• Business vision refinement (from business-context.md [NEEDS USER INPUT] items)

• Priority trade-offs between competing requirements

• Persona validation (are the inferred personas correct?)

• Architecture preferences not visible in code

• Epic scoping decisions

• Generates all 4 artifacts with user input incorporated

Best for: Most projects. Good balance of speed and quality.

Mode 3: Interactive

Time: ~25-30 minutes User input: Full conversation

• Pre-loads all available docs (9-11) as context (you don't start from zero)

• Walks through each BMAD artifact section by section

• Shows draft content for each section, asks for approval/changes

• Most thorough, but slowest

• Essentially BMAD's collaborative flow with a massive head start

Best for: Critical projects, when precision matters, when you want full control.

Document Mapping (Detailed)

prd.md Generation

Source → BMAD PRD Section ───────────────────────────────────────────────────────────────── business-context.md [OPTIONAL] ├── Product Vision → ## Product Vision ├── Target Users & Personas → ## Target Users ├── Business Goals → ## Success Criteria / ## KPIs ├── Competitive Landscape → ## Market Context ├── Stakeholder Map → ## Stakeholders └── Business Constraints → ## Constraints & Assumptions │ └── [FALLBACK if missing - ~70% coverage for above sections]: functional-specification.md (Executive Summary → Product Vision, User Stories + User Personas → Target Users, Success Criteria → Success Criteria / KPIs, Product Positioning → Market Context) visual-design-system.md (persona UX context → Target Users supplement)

functional-specification.md ├── Functional Requirements → ## FR1: Title, ## FR2: Title, ... ├── Non-Functional Reqs → ## NFR1: Title, ## NFR2: Title, ... ├── User Stories → Embedded in FRs as acceptance criteria ├── Business Rules → ## Business Rules ├── System Boundaries → ## Scope ├── Success Criteria → ## Success Criteria ├── User Personas → Supplements ## Target Users └── Product Positioning → Supplements ## Product Vision

technical-debt-analysis.md ├── Migration Priority Matrix → ## Known Issues & Constraints └── Security Vulnerabilities → ## NFR: Security Requirements

integration-points.md ├── External Services → ## External Dependencies └── Auth Flows → ## NFR: Authentication & Authorization

architecture.md Generation

Source → BMAD Architecture Section ───────────────────────────────────────────────────────────────── data-architecture.md ├── Data Models → ## Data Models ├── API Endpoints → ## API Contracts ├── Database ER Diagram → ## Data Layer ├── JSON/GraphQL Schemas → ## API Contracts (detail) └── Domain Model / Contexts → ## Domain Model

integration-points.md ├── External Services → ## External Integrations ├── Internal Service Deps → ## Service Architecture ├── Data Flow Diagrams → ## System Architecture Diagram ├── Auth Flows → ## Authentication Architecture └── Webhook Integrations → ## Event Architecture

operations-guide.md ├── Deployment Procedures → ## Deployment Architecture ├── Infrastructure Overview → ## Infrastructure ├── Scalability Strategy → ## Scalability & Performance └── Monitoring → ## Observability Architecture

decision-rationale.md [OPTIONAL] ├── Technology Selection → ## Technology Stack ├── ADRs → ## ADR-001: Title, ## ADR-002: Title, ... ├── Design Principles → ## Design Principles └── Trade-offs → ## Trade-offs & Constraints │ └── [FALLBACK if missing - ~60% coverage for above sections]: configuration-reference.md (tech stack, framework choices → Technology Stack) data-architecture.md (schema design decisions → ADRs supplement) integration-points.md (integration choice rationale → ADRs supplement)

configuration-reference.md ├── Environment Variables → ## Configuration Architecture └── Feature Flags → ## Feature Management

observability-requirements.md ├── Logging Strategy → ## Observability Architecture ├── Monitoring Strategy → ## Monitoring & Alerting └── Alerting Rules → ## SLA & SLO Targets

epics.md Generation

Source → BMAD Epics ───────────────────────────────────────────────────────────────── functional-specification.md ├── FRs grouped by domain → ## Epic N: Domain Name ├── User Stories per FR → ### Story N.M: Title └── Acceptance Criteria → Acceptance Criteria per story

business-context.md [OPTIONAL] ├── Personas → "As a [persona]..." in user stories └── Business Goals → Epic priority ordering │ └── [FALLBACK if missing]: functional-specification.md (User Personas → persona names, Product Positioning → priority ordering context)

technical-debt-analysis.md ├── Migration Priority Matrix → ## Epic: Technical Debt Resolution └── Quick Wins → High-priority stories in debt epic

integration-points.md └── External Integrations → ## Epic: Integration & Connectivity

Epic Grouping Strategy:

• Group FRs by domain/feature area (auth, data management, reporting, etc.)

• Each group becomes an Epic

• Each FR within a group becomes a Story

• Add a "Technical Foundation" epic for infrastructure/debt items

• Add an "Integration" epic for external service work

• Priority ordering: P0 epics first, then P1, P2, P3

ux-design-specification.md Generation

Source → BMAD UX Design Section ───────────────────────────────────────────────────────────────── visual-design-system.md ├── Component Library → ## Component Inventory ├── Design Tokens → ## Design Tokens ├── Responsive Breakpoints → ## Responsive Design ├── Accessibility Standards → ## Accessibility Requirements └── User Flows → ## User Flows

business-context.md [OPTIONAL] ├── Personas → ## User Personas (with journey maps) └── Business Constraints → ## Design Constraints │ └── [FALLBACK if missing]: functional-specification.md (User Personas → persona definitions) visual-design-system.md (User Flows, Accessibility → journey context)

functional-specification.md ├── User Stories → ## Key User Journeys └── Business Rules → ## Interaction Patterns

Process

Step 0: Verify Prerequisites

Check that Gear 2 is complete

DOCS_DIR="docs/reverse-engineering"

9 core docs (always produced by reverse-engineer v1.x+)

CORE_DOCS=("functional-specification.md" "integration-points.md" "configuration-reference.md" "data-architecture.md" "operations-guide.md" "technical-debt-analysis.md" "observability-requirements.md" "visual-design-system.md" "test-documentation.md")

2 optional docs (produced by reverse-engineer v2.0+)

OPTIONAL_DOCS=("business-context.md" "decision-rationale.md")

CORE_MISSING=0 OPTIONAL_MISSING=0 OPTIONAL_MISSING_LIST=()

for doc in "${CORE_DOCS[@]}"; do if [ ! -f "$DOCS_DIR/$doc" ]; then echo "MISSING (core): $doc" CORE_MISSING=$((CORE_MISSING + 1)) fi done

for doc in "${OPTIONAL_DOCS[@]}"; do if [ ! -f "$DOCS_DIR/$doc" ]; then echo "MISSING (optional): $doc" OPTIONAL_MISSING=$((OPTIONAL_MISSING + 1)) OPTIONAL_MISSING_LIST+=("$doc") fi done

if [ $CORE_MISSING -gt 0 ]; then echo "ERROR: $CORE_MISSING core docs missing. Run Gear 2 first: /stackshift.reverse-engineer" exit 1 fi

TOTAL_FOUND=$((9 + 2 - OPTIONAL_MISSING))

if [ $OPTIONAL_MISSING -gt 0 ]; then echo "WARNING: $TOTAL_FOUND/11 docs found. Missing optional: ${OPTIONAL_MISSING_LIST[*]}" echo "Proceeding in 9-doc mode (~85% average coverage). Missing content will be inferred from related docs." else echo "All 11 reverse-engineering docs found. Ready to synthesize at full coverage." fi

If core docs are missing: Error. Guide user to run /stackshift.reverse-engineer first. If all 11 exist: Proceed at full coverage. If only 9 core exist: Warn about reduced coverage (~85% average), then proceed to Step 0.5 to infer missing content.

Step 0.5: Infer Missing Documents

Only runs if optional docs are missing. Extracts equivalent content from related core docs.

If business-context.md is missing:

Extract business context from:

• functional-specification.md : Executive Summary (product vision), User Stories (persona behavior), Success Criteria (business goals), User Personas (target users), Product Positioning (market context)

• visual-design-system.md : Persona UX context (user flows, accessibility standards imply target audience)

Map inferred content to the sections that would have come from business-context.md:

• Product Vision → from Executive Summary / Product Positioning

• Target Users & Personas → from User Personas + visual-design-system user flows

• Business Goals → from Success Criteria

• Competitive Landscape → [INFERRED FROM: functional-specification.md - limited data, review recommended]

• Stakeholder Map → [INFERRED FROM: functional-specification.md - limited data, review recommended]

• Business Constraints → from NFRs (performance, security, compliance constraints)

Note: Coverage for sections sourced from business-context.md drops to ~70% (vs ~90% with the full doc). Persona depth and competitive landscape are most affected.

If decision-rationale.md is missing:

Extract technology decisions from:

• configuration-reference.md : Tech stack identification (languages, frameworks, versions from environment variables and config), framework choices (build tools, deployment targets)

• data-architecture.md : Schema design decisions (why certain data models, relationships, indexing strategies)

• integration-points.md : Integration choice rationale (why specific external services, API patterns, auth providers)

Map inferred content to the sections that would have come from decision-rationale.md:

• Technology Stack → from configuration-reference.md environment/config analysis

• ADRs → synthesized from observable choices across all three docs, marked [INFERRED FROM: configuration-reference.md, data-architecture.md, integration-points.md]

• Design Principles → [INFERRED FROM: codebase patterns - review recommended]

• Trade-offs → inferred from technical-debt-analysis.md (debt items imply past trade-offs)

Note: Coverage for sections sourced from decision-rationale.md drops to ~60% (vs ~85% with the full doc). ADR rationale and design principles are most affected since "why" decisions were made is harder to infer than "what" decisions were made.

Step 1: Load All Reverse-Engineering Docs

Read all available docs (9-11) from docs/reverse-engineering/ into memory. If Step 0.5 inferred content for missing optional docs, include that inferred content alongside the core docs. Parse each for structured content:

• Extract all FRs, NFRs, user stories, personas

• Extract all data models, API contracts, integration points

• Extract all ADRs, technology selections, design principles (from docs or inferred in Step 0.5)

• Extract all business context, goals, constraints (from docs or inferred in Step 0.5)

• Note all [INFERRED] , [INFERRED FROM: source-doc] , and [NEEDS USER INPUT] markers

Step 2: Choose Mode

Ask the user which mode to use:

How should BMAD artifacts be generated?

A) YOLO - Fully automatic, no questions asked (~10 min) Best for: Quick generation, batch processing, refine later

B) Guided - Auto-fill + 5-10 targeted questions (~15-20 min) (Recommended) Best for: Most projects, good balance of speed and quality

C) Interactive - Section-by-section review (~25-30 min) Best for: Critical projects, maximum precision

Step 3: Generate Artifacts (Mode-Dependent)

YOLO Mode

• Generate prd.md: Map all source sections per the mapping above. For [NEEDS USER INPUT] items, use best-effort inference and mark with [AUTO-INFERRED - review recommended] .

• Generate architecture.md: Map all technical docs. Generate Mermaid diagrams for system architecture and data flow.

• Generate epics.md: Group FRs into domain-based epics. Create stories with "As a [persona]" format. Set priorities from FR priorities.

• Generate ux-design-specification.md: Map visual design system + persona journey maps.

• Write all artifacts to _bmad-output/planning-artifacts/ .

• Generate a coverage report showing what percentage of each artifact was filled from docs vs inferred.

Guided Mode

• Parse and score: Read all docs, identify [NEEDS USER INPUT] items and low-confidence sections.

• Auto-fill high-confidence sections: Everything that maps cleanly from docs.

• Present targeted questions (5-10 max):

• "The codebase suggests [X] as the primary user persona. Is this accurate, or would you refine it?"

• "Business goals appear to center on [X]. What are the top 3 success metrics?"

• "The architecture uses [X]. For the BMAD architecture doc, should we document the current state or a target state?"

• "FRs group naturally into [N] domains: [list]. Does this epic structure make sense?"

• "The competitive landscape suggests [X]. Any corrections?"

• Incorporate answers into artifacts.

• Write all artifacts.

Interactive Mode

• Create context brief: One-page summary of all available docs (9-11) for quick reference, noting any inferred content from Step 0.5.

• Walk through prd.md section by section:

• Show draft for each section

• Ask: "Approve as-is, or modify?"

• Incorporate changes

• Walk through architecture.md section by section (same approach).

• Walk through epics.md: Present epic groupings, ask for approval, refine stories.

• Walk through ux-design-specification.md: Present design system mapping, ask for approval.

• Write all artifacts.

Step 4: Write Output

Create _bmad-output/planning-artifacts/ directory and write all 4 artifacts:

_bmad-output/ └── planning-artifacts/ ├── prd.md ├── architecture.md ├── epics.md └── ux-design-specification.md

Each artifact includes YAML frontmatter:

stepsCompleted: [1, 2, 3] inputDocuments:

• docs/reverse-engineering/functional-specification.md
• docs/reverse-engineering/business-context.md
• docs/reverse-engineering/integration-points.md

... all source docs used

workflowType: prd # or architecture, epics, ux-design project_name: "<from state file>" date: "<current date>" synthesize_mode: "yolo" # or guided, interactive coverage_score: 92 # percentage of sections filled from docs source_doc_count: 9 # or 11 - how many reverse-engineering docs were available inferred_sections: [] # list of sections that used fallback sources, e.g. ["Product Vision", "ADRs"]

Step 5: Generate Synthesis Report

Output a summary showing:

BMAD Synthesis Complete ═══════════════════════

Mode: Guided Time: 18 minutes

Artifacts Generated: prd.md - 94% from docs, 6% user input architecture.md - 88% from docs, 12% inferred epics.md - 82% from docs, 18% structured from FRs ux-design-specification.md - 68% from docs, 32% inferred

Items Requiring Review:

• prd.md: 2 items marked [AUTO-INFERRED]
• architecture.md: 1 ADR with [INFERRED] rationale
• epics.md: Story priorities may need reordering

Next Steps:

• Review artifacts in _bmad-output/planning-artifacts/
• Install BMAD: npx bmad-method@alpha install
• Run: *workflow-init (BMAD will use these artifacts as starting point)
• Or: Manually refine artifacts before handing off to BMAD

Output Format

prd.md Structure

stepsCompleted: [1, 2, 3, 4, 5] workflowType: prd project_name: "..." date: "..." synthesize_mode: "guided" source_doc_count: 9 # or 11 inferred_sections: ["Product Vision", "Target Users", "Market Context"] # empty if 11 docs

[Product Name] - Product Requirements Document

Product Vision

[From business-context.md Product Vision] [Or INFERRED FROM: functional-specification.md Executive Summary + Product Positioning]

Target Users

[From business-context.md Personas + functional-spec User Personas] [Or INFERRED FROM: functional-specification.md User Personas + visual-design-system.md user flows]

Persona 1: [Name]

• Role: ...
• Goals: ...
• Pain Points: ...

Success Criteria

[From functional-spec Success Criteria + business-context Business Goals]

• Criterion 1
• Criterion 2

Functional Requirements

FR1: [Title]

Priority: P0 Description: [From functional-spec FR-001] Acceptance Criteria:

• Criterion 1
• Criterion 2

FR2: [Title]

...

Non-Functional Requirements

NFR1: [Title]

Priority: P1 Description: [From functional-spec NFR-001]

External Dependencies

[From integration-points.md]

Constraints & Assumptions

[From business-context.md Business Constraints]

Known Issues

[From technical-debt-analysis.md high-priority items]

architecture.md Structure

stepsCompleted: [1, 2, 3] workflowType: architecture source_doc_count: 9 # or 11 inferred_sections: ["Technology Stack", "ADRs", "Design Principles"] # empty if 11 docs

[Product Name] - Technical Architecture

System Architecture Diagram

[Mermaid diagram from integration-points Data Flow Diagrams]

Technology Stack

[From decision-rationale.md Technology Selection] [Or INFERRED FROM: configuration-reference.md tech stack and framework choices]

Domain Model

[From data-architecture.md Domain Model / Bounded Contexts]

API Contracts

[From data-architecture.md API Endpoints]

GET /api/resource

Description: ... Request: ... Response: ...

Data Models

[From data-architecture.md Data Models]

ModelName

• field1: type - description
• field2: type - description

ADR-001: [Decision Title]

Context: [From decision-rationale.md] [Or INFERRED FROM: configuration-reference.md, data-architecture.md, integration-points.md] Decision: ... Rationale: ...

Deployment Architecture

[From operations-guide.md]

Scalability & Performance

[From operations-guide.md Scalability Strategy]

Observability Architecture

[From observability-requirements.md]

Integration with Existing Workflows

From Spec Kit → BMAD Synthesize

If you already ran Gears 1-5 with Spec Kit and want BMAD artifacts too:

• The reverse-engineering docs are already generated

• Run /stackshift.bmad-synthesize directly

• BMAD artifacts supplement (don't replace) .specify/ structure

From BMAD Synthesize → BMAD Workflow

After generating artifacts:

• Install BMAD: npx bmad-method@alpha install

• Run *workflow-init

• BMAD agents will find and use the pre-generated artifacts

• PM agent refines PRD, Architect agent refines Architecture

• Much faster than starting from scratch

Batch Mode Integration

When running batch processing (/stackshift.batch ):

• Batch session can include synthesize_mode: "yolo" in answers

• Each repo gets BMAD artifacts generated automatically after Gear 2

• Useful for enterprise-scale documentation of many services

Success Criteria

• ✅ All 4 BMAD artifacts generated in _bmad-output/planning-artifacts/

• ✅ prd.md contains FRs, NFRs, personas, success criteria, constraints

• ✅ architecture.md contains data models, API contracts, ADRs, deployment architecture

• ✅ epics.md contains domain-grouped epics with user stories

• ✅ ux-design-specification.md contains design system and user journey maps

• ✅ Each artifact has YAML frontmatter with source tracking

• ✅ Synthesis report shows coverage percentages

• ✅ [AUTO-INFERRED] items clearly marked for review

Next Steps

After BMAD Synthesize:

• Review artifacts in _bmad-output/planning-artifacts/

• Refine manually or hand off to BMAD agents for collaborative refinement

• Install BMAD (if not installed): npx bmad-method@alpha install

• Run BMAD workflow: *workflow-init — agents will use your artifacts as starting point

• Or use directly: Artifacts are valid BMAD format, can be used as-is for implementation

Technical Notes

• Read all available docs (9-11) using the Read tool (parallel reads recommended)

• If only 9 docs present, run Step 0.5 inference before proceeding to artifact generation

• For Mermaid diagrams in architecture.md, generate from integration-points.md data flow descriptions

• Epic grouping uses domain clustering: analyze FR titles and descriptions for common themes

• User story format: "As a [persona from business-context or functional-specification], I want [FR description], so that [business goal]"

• Priority inheritance: Stories inherit priority from their source FR

• ADR numbering: Sequential from decision-rationale.md (or inferred from config/data/integration docs), preserving original order

• All inferred content must be tagged with [INFERRED FROM: source-doc] so users can verify accuracy