Generate Product Requirements Documents (PRD) for existing systems through systematic codebase analysis, feature extraction, and gap identification with confidence scoring for validation-needed areas. Use when documenting existing systems that lack requirements documentation or preparing for system modernization/migration.
Generate Product Requirements Documents (PRD) for existing systems through systematic codebase analysis, feature extraction, and gap identification with confidence scoring for validation-needed areas. Use when documenting existing systems that lack requirements documentation or preparing for system modernization/migration.
acceptance
[{"prd_generated":"Brownfield PRD document created documenting current state"},{"features_extracted":"All major features identified and categorized (core/secondary/legacy)"},{"confidence_scored":"All extracted information includes confidence scores (High/Medium/Low)"},{"gaps_identified":"Known limitations, technical debt, and gaps documented"},{"modernization_roadmap":"Modernization opportunities and priorities identified"}]
inputs
{"project_root":{"type":"string","required":true,"description":"Absolute path to project root directory"},"existing_docs":{"type":"string","required":false,"description":"Path to existing documentation (README, wikis, etc.)"},"business_context":{"type":"string","required":false,"description":"Business context, target users, and objectives (if known)"},"tech_stack":{"type":"string","required":false,"description":"Known technology stack information"},"analysis_depth":{"type":"string","required":false,"description":"quick | standard | comprehensive (default: standard)","default":"standard"}}
outputs
{"prd_created":{"type":"boolean","description":"Whether brownfield PRD was successfully created"},"prd_location":{"type":"string","description":"File path to created PRD (docs/brownfield-prd.md)"},"feature_count":{"type":"number","description":"Number of features identified and documented"},"confidence_score":{"type":"number","description":"Overall confidence in analysis (0-100, weighted average)"},"validation_needed":{"type":"array","description":"List of areas requiring human validation"}}
Generate Product Requirements Documents (PRD) for existing systems by analyzing codebases, extracting features, reconstructing user flows, and identifying modernization opportunities. Unlike greenfield PRDs (starting from scratch), brownfield PRDs document what exists today and plan evolution paths.
Core Principles:
Evidence-based analysis (code is source of truth)
Confidence scoring (highlight areas needing validation)
Feature categorization (core/secondary/legacy)
Gap identification (what's missing, what's broken)
Modernization roadmap (prioritized improvements)
Prerequisites
Access to project codebase (read permissions)
document-project skill available for architecture analysis
Basic understanding of project's domain/purpose
workspace/ directory exists for PRD storage
Workflow
Step 1: Codebase Analysis
Action: Analyze project structure, architecture, and technical implementation using systematic discovery.
Key Activities:
Use document-project Skill
# Leverage existing brownfield analysis skill
@bmad Use document-project skill to analyze [project_root]
Extract from document-project output:
Project structure and organization
Technology stack details
Architecture patterns used
Data models and entities
API endpoints and routes
Integration points
Configuration and environment
Supplement with Targeted Analysis
Entry Points: Identify how users access the system (web routes, CLI commands, API endpoints)
Core Workflows: Map main user flows from routes/controllers
Data Models: Extract entities and relationships from database schemas
Business Logic: Identify key algorithms, calculations, validations
HIGH (90-100%): Clear code, good naming, documented
MEDIUM (60-89%): Understandable code, decent structure, some gaps
LOW (0-59%): Unclear code, poor naming, no documentation
Example Analysis:
PROJECT: E-commerce Platform (Node.js/React)
STRUCTURE (Confidence: HIGH):
- Backend: Express.js API (src/api/)
- Frontend: React SPA (src/client/)
- Database: PostgreSQL (9 tables identified)
- Clear separation of concerns
FEATURES IDENTIFIED (Preliminary):
1. User Authentication (routes: /api/auth/*)
2. Product Catalog (routes: /api/products/*)
3. Shopping Cart (routes: /api/cart/*)
4. Checkout Process (routes: /api/checkout/*)
5. Order Management (routes: /api/orders/*)
CONFIDENCE: 85% overall (good structure, decent naming)
VALIDATION NEEDED: Business rules (need to understand pricing, taxes, shipping logic)
Output: Comprehensive technical analysis with confidence scores
See:references/codebase-analysis-guide.md for detailed analysis techniques
Step 2: Feature Extraction
Action: Transform technical components into user-facing features with categorization.
Key Activities:
Map Code to Features
Routes/Endpoints → User Capabilities
Example:
/api/auth/login, /api/auth/signup → "User Authentication"
/api/products GET → "Browse Products"
/api/products/:id GET → "View Product Details"
/api/cart POST → "Add to Cart"
/api/checkout POST → "Complete Purchase"
Categorize Features
Core (Business-Critical): Essential to product value, frequently used
Secondary (Important): Valuable but not critical, moderately used
Legacy (Deprecated/Unused): Old features, low usage, technical debt
Infer User Value
What problem does each feature solve?
What user goal does it enable?
How does it contribute to overall product value?
Estimate Usage Patterns
Frequency indicators (from code):
Many routes/components → Likely core feature
Complex logic → Important business capability
Simple CRUD → Possibly secondary feature
Dead code/commented out → Legacy feature
Document Feature Details
### Feature: User Authentication**Category:** Core
**Confidence:** High (95%)
**Description:** Users can create accounts, log in, and manage sessions
**Technical Implementation:**- Routes: /api/auth/signup, /api/auth/login, /api/auth/logout
- Authentication: JWT tokens (stored in httpOnly cookies)
- Password hashing: bcrypt
- Session management: Redis cache
**User Capabilities:**- Sign up with email/password
- Log in with credentials
- Log out (invalidate session)
- Password reset (inferred from /forgot-password route)
**Validation Needed:**- OAuth/social login support? (no code found, may be planned)
- Two-factor authentication? (no implementation found)
Categorization Criteria:
CORE FEATURES:
- Directly enables primary user goals
- Frequently accessed routes/components
- Complex business logic
- Multiple database tables involved
- Recent updates/commits (actively maintained)
SECONDARY FEATURES:
- Enhances but doesn't enable core value
- Moderate route/component complexity
- Support/utility functions
- Less frequent updates
LEGACY FEATURES:
- Commented-out code
- Old routes with no recent changes
- Feature flags marked deprecated
- TODO comments suggesting removal
- No test coverage
Output: Categorized feature list with confidence scores
See:references/feature-extraction-patterns.md for extraction strategies
Step 3: User Flow Reconstruction
Action: Reconstruct end-to-end user journeys from code structure.
Key Activities:
Map User Journeys from Routes
Journey: New Customer Purchase
1. Browse Products
Route: GET /products
Page: ProductListPage.jsx
2. View Product Details
Route: GET /products/:id
Page: ProductDetailPage.jsx
3. Add to Cart
Route: POST /cart
Action: addToCart() in CartService
4. Proceed to Checkout
Route: GET /checkout
Page: CheckoutPage.jsx
5. Enter Shipping Info
Form: ShippingForm.jsx
API: POST /checkout/shipping
6. Enter Payment
Form: PaymentForm.jsx
API: POST /checkout/payment
Integration: Stripe.js
7. Confirm Order
Route: POST /orders
Email: sendOrderConfirmation()
Identify User Personas (Inferred)
Based on features and flows, infer user types:
PERSONA 1: Customer (End User)
- Features used: Browse, Purchase, Order History
- Entry points: Homepage, Product pages
- Goals: Find and buy products
PERSONA 2: Admin (Staff)
- Features used: Product Management, Order Management
- Entry points: /admin dashboard
- Goals: Manage catalog, fulfill orders
EDGE CASES FOUND:
- Out of stock products (handled: show "Unavailable" message)
- Invalid payment (handled: error message, no order created)
- Duplicate cart items (handled: increment quantity)
GAPS IN ERROR HANDLING:
- Network timeouts (no retry logic found)
- Race conditions (concurrent cart updates not handled)
- Session expiration (unclear behavior, validation needed)
Confidence Scoring for Flows:
HIGH: Complete flow with clear steps, well-documented
MEDIUM: Flow identifiable but some gaps or unclear logic
LOW: Incomplete flow, significant inference required
Output: Reconstructed user journeys with confidence scores
See:references/user-flow-reconstruction.md for reconstruction techniques
Step 4: PRD Generation
Action: Compile analysis into comprehensive brownfield PRD document.
Document Structure:
Section 1: Executive Summary
## Executive Summary**Product:** [Product Name] (Existing System)
**Analysis Date:** [Date]
**Codebase Version:** [Git commit, version, or "current"]
**Overall Confidence:** [X%] (High/Medium/Low)
### Current State Overview
[1-2 paragraphs: What the product does today, who uses it, core value proposition]
### Key Findings- X core features identified and documented
- Y secondary features catalogued
- Z legacy features marked for deprecation
- [Confidence: HIGH/MEDIUM/LOW areas highlighted]
### Modernization Priorities
[Top 3-5 improvement opportunities ranked by impact]
Section 2: Product Overview (As-Is)
## Product Overview### What It Does
[Clear description of product functionality based on code analysis]
### Current Users (Inferred)
[User personas reconstructed from features and flows]
### Technology Stack
[Extracted from codebase: languages, frameworks, databases, tools]
### System Architecture
[High-level architecture diagram and description from document-project]
Section 3: Feature Inventory
## Feature Inventory### Core Features (Business-Critical)
[List of core features with descriptions, confidence scores, technical details]
### Secondary Features
[List of secondary features]
### Legacy Features (Deprecated/Unused)
[Features marked for potential removal]
### Feature Details Template:**Feature Name:** [Name]
**Category:** Core | Secondary | Legacy
**Confidence:** [%] - High | Medium | Low
**Description:** [What it does]
**User Value:** [Why users care]
**Technical Implementation:** [How it works]
**Usage Indicators:** [Evidence of usage/importance]
**Validation Needed:** [Areas requiring confirmation]
Section 4: User Flows
## User Flows (Reconstructed)
[Document key user journeys with confidence scores]
### Flow 1: [Flow Name]**Confidence:** [%]
**Steps:** [Numbered steps]
**Validation Needed:** [Unclear areas]
Section 5: Known Limitations & Technical Debt
## Known Limitations & Technical Debt### Functional Gaps
[Features that should exist but don't]
### Technical Debt
[Code quality issues, outdated dependencies, architectural problems]
### Performance Issues
[Identified bottlenecks or scalability concerns]
### Security Concerns
[Potential security issues observed]
### UX Issues
[User experience problems inferred from code]
Section 6: Modernization Opportunities
## Modernization Opportunities### Priority 1 (High Impact, High Confidence)
[Improvements with clear value and high certainty]
### Priority 2 (High Impact, Medium Confidence)
[Improvements requiring validation]
### Priority 3 (Medium Impact)
[Nice-to-have improvements]
### Technology Upgrades
[Outdated dependencies, framework versions]
### Feature Enhancements
[Existing features that could be improved]
### New Feature Opportunities
[Gaps that could become new features]
Section 7: Integration Map
## Integration Map### External Integrations
[Third-party services, APIs, SaaS tools]
### Internal Systems
[Databases, caches, message queues, microservices]
### Data Flows
[How data moves through the system]
