doc-brd: Create Business Requirements Documents (Layer 1)

doc-brd

Purpose

Create Business Requirements Documents (BRD) - Layer 1 artifact in the SDD workflow that defines high-level business needs, strategic objectives, and success criteria.

Layer: 1 (Entry point - no upstream dependencies)

Downstream Artifacts: PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

   ls docs/​BRD/ docs/​PRD/ docs/​EARS/ docs/​BDD/ docs/​ADR/ docs/​SYS/ docs/​REQ/ 2>/​dev/​null
   

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn't exist

4. NEVER use placeholders like BRD-XXX or TBD

5. Do NOT create missing upstream artifacts - skip functionality instead

Before creating a BRD, read:

1. Shared Standards: .claude/​skills/​doc-flow/​SHARED_CONTENT.md
2. Template: ai_dev_flow/​BRD/​BRD-TEMPLATE.md
3. Creation Rules: ai_dev_flow/​BRD/​BRD_CREATION_RULES.md
4. Validation Rules: ai_dev_flow/​BRD/​BRD_VALIDATION_RULES.md
5. Platform vs Feature Guide: ai_dev_flow/​PLATFORM_VS_FEATURE_BRD.md

For New Projects: Use project-init skill first to initialize project structure.

Pre-Flight Check (MANDATORY)

Before creating ANY BRD section, confirm:

1. ✅ Read ai_dev_flow/​ID_NAMING_STANDARDS.md - Element Type Codes table
2. ✅ Element ID format: BRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dots)

Common Element Types:

⚠️ Removed Patterns: Do NOT use AC-XXX, FR-XXX, BC-XXX, BO-XXX formats.

When to Use This Skill

Use doc-brd when:

• Starting a new project or feature
• Defining business requirements and objectives
• Documenting strategic alignment and market context
• Establishing success criteria and stakeholder needs
• You are at Layer 1 of the SDD workflow

BRD Categorization: Platform vs Feature

CRITICAL DECISION: Before creating a BRD, determine if it's a Platform BRD or Feature BRD.

Questionnaire

1. Does this BRD define infrastructure, technology stack, or cross-cutting concerns?

   • Yes → Likely Platform BRD
   • No → Continue

2. Does this BRD describe a specific user-facing workflow or feature?

   • Yes → Likely Feature BRD
   • No → Continue

3. Will other BRDs depend on or reference this BRD's architectural decisions?

   • Yes → Likely Platform BRD
   • No → Likely Feature BRD

4. Does this BRD establish patterns, standards, or capabilities used across multiple features?

   • Yes → Platform BRD
   • No → Feature BRD

5. Does this BRD implement functionality on top of existing platform capabilities?

   • Yes → Feature BRD
   • No → Platform BRD

Auto-Detection Logic

• Title contains "Platform", "Architecture", "Infrastructure", "Integration" → Platform BRD
• Title contains specific workflow names, user types (B2C, B2B), or feature names → Feature BRD
• References/​depends on BRD-01 or foundation ADRs → Feature BRD
• Establishes technology choices or system-wide patterns → Platform BRD

Workflow Differences

Platform BRD Path:

1. Create Platform BRD (populate sections 3.6 and 3.7)
2. Create ADRs for critical technology decisions (identified in BRD sections 3.6/​3.7)
3. Create PRD referencing Platform BRD and ADRs
4. Create additional ADRs for implementation details
5. Continue to SPEC

Feature BRD Path:

1. Create Feature BRD (reference Platform BRD in sections 3.6 and 3.7)
2. Create PRD for feature
3. Create ADRs for implementation decisions (if needed)
4. Continue to SPEC

Section 3.6 & 3.7 Rules

Platform BRD:

• MUST populate Section 3.6 (Technology Stack Prerequisites) with detailed technology choices
• MUST populate Section 3.7 (Mandatory Technology Conditions) with non-negotiable constraints

Feature BRD:

• MUST mark Section 3.6 as "N/​A - See Platform BRD-NN Section 3.6" and reference specific items
• MUST mark Section 3.7 as "N/​A - See Platform BRD-NN Section 3.7" and reference specific conditions

Reference: ai_dev_flow/​PLATFORM_VS_FEATURE_BRD.md for detailed guidance

BRD-Specific Guidance

1. Template Selection

Primary Template:

BRD-TEMPLATE.md - Comprehensive business requirements (general purpose)

• Use for: All business requirements documents
• Sections: Complete 18-section structure
• Best for: Complex projects, regulatory compliance needs
• Location: ai_dev_flow/​BRD/​BRD-TEMPLATE.md

Note: Use the comprehensive template for all BRD documents. For simpler requirements, complete only the essential sections and mark others as "N/​A - Not applicable for this scope".

Note: Technical QA standards, testing strategy, and defect management are documented in PRD-TEMPLATE.md Section 21 (product level).

Section Templates (DEFAULT for all BRD documents):

• Structure: docs/​BRD/​BRD-NN_{slug}/​BRD-NN.S_{slug}.md (nested folder per document with descriptive slug)
• Folder Naming: BRD-NN_{slug}/ where slug MUST match the index file slug
• Index template: ai_dev_flow/​BRD/​BRD-SECTION-0-TEMPLATE.md
• Content template: ai_dev_flow/​BRD/​BRD-SECTION-TEMPLATE.md
• Reference: ai_dev_flow/​ID_NAMING_STANDARDS.md (Section-Based File Splitting)
• Note: Monolithic template is OPTIONAL for small documents (<25KB)

2. Required Sections (18 Total)

Document Control (MANDATORY - First section before all numbered sections):

• Project Name
• Document Version
• Date (YYYY-MM-DD)
• Document Owner
• Prepared By
• Status (Draft, In Review, Approved, Superseded)
• Document Revision History table

Core Sections:

1. Executive Summary
2. Business Context
3. Stakeholder Analysis
4. Business Requirements
5. Success Criteria
6. Constraints and Assumptions
7. Architecture Decision Requirements (topics needing ADRs, NOT specific ADR numbers)
8. Risk Assessment
9. Traceability (Section 7 format from SHARED_CONTENT.md) 10-16. Additional content sections (see BRD-TEMPLATE.md for full structure)
10. Glossary - Domain terms and definitions
11. Appendices - Supporting materials and references

Platform BRD Additional Sections:

• 3.6 Technology Stack Prerequisites (MUST populate for Platform BRD)
• 3.7 Mandatory Technology Conditions (MUST populate for Platform BRD)

3. Strategy References (MANDATORY)

ALWAYS START WITH STRATEGY: Read relevant {project_root}/​strategy/ documents FIRST

Reading Order:

1. {project_root}/​strategy/​README.md - Performance targets, strategy goals
2. {project_root}/​strategy/​strategy_overview.md - Strategic framework
3. {project_root}/​strategy/​core_algorithm.md - Primary algorithm specifications
4. {project_root}/​strategy/​risk_management.md - Risk management policies
5. {project_root}/​strategy/​selection_criteria/ - Entry criteria

Every BRD MUST cite specific strategy document sections in Traceability section.

4. Architecture Decision Requirements Section (7.2)

Purpose: Identify architectural topics requiring decisions using business-only content.

Layer Separation Principle:

BRD Section 7.2          →    PRD Section 18         →    ADR
(WHAT & WHY)                  (HOW to evaluate)          (Final decision)
─────────────────────────────────────────────────────────────────────────
Business drivers              Technical options          Selected option
Business constraints          Evaluation criteria        Trade-off analysis

Subsection ID Format: {DOC_TYPE}.NN.EE.SS (unified 4-segment format)

Format (business-only content):

## 7.2 Architecture Decision Requirements

### BRD.01.01.01: API Communication Protocol

**Business Driver**: Real-time market data integration requires low-latency, bidirectional communication for competitive trading execution.

**Business Constraints**:
- Must maintain <100ms latency for order execution
- Must support reconnection without data loss during market hours
- Must comply with broker API terms of service

**PRD Requirements**: [What PRD must elaborate for THIS topic]

Business-Only Content Rules:

• Business Driver: WHY this decision matters to business outcomes
• Business Constraints: Non-negotiable business rules (not technical constraints)
• Do NOT include: Technical options, implementation approaches, or evaluation criteria (those belong in PRD Section 18)

Do NOT write: "See ADR-033" or "Reference ADR-045" (ADRs don't exist yet)

Cross-Reference Flow:

1. BRD Section 7.2 → Defines business need ({DOC_TYPE}.NN.EE.SS)
2. PRD Section 18 → Elaborates with technical options (references {DOC_TYPE}.NN.EE.SS)
3. ADR Section 4.1 → Records final decision (references both)

5. Document Control Section Positioning

CRITICAL: Document Control MUST be the first section at the very top of the BRD (before all numbered sections).

Correct Structure:

# BRD-01: Project Name

## Document Control
[All metadata fields here]

## 1. Executive Summary
[Content here]

Cumulative Tagging Requirements

Layer 1 (BRD): No upstream tags required (entry point)

Tag Count: 0 tags

Format: BRD has no @ tags since it's Layer 1 (top of hierarchy)

Downstream artifacts will tag BRD (using unified format):

• PRD will include: @brd: BRD.01.01.30 (TYPE.NN.TT.SS format)
• EARS will include: @brd: BRD.01.01.30
• All downstream artifacts inherit BRD tags

Tag Format Convention (By Design)

The SDD framework uses two distinct notation systems for cross-references:

Key Distinction:

• @adr: ADR-033 → Points to the document ADR-033_risk_limit_enforcement.md
• @brd: BRD.17.01.01 → Points to element 01.01 inside document BRD-017.md

Unified Element ID Format (MANDATORY)

For hierarchical requirements (BRD, PRD, EARS, BDD, SYS, REQ):

• Always use: TYPE.NN.TT.SS (dot separator, 4-segment unified format)
• Never use: TYPE-NN:NNN (colon separator - DEPRECATED)
• Never use: TYPE.NN.TT (3-segment format - DEPRECATED)

Examples:

• @brd: BRD.17.01.01 ✅
• @brd: BRD.017.001 ❌ (old 3-segment format)

Upstream/​Downstream Artifacts

Upstream Sources (what drives BRD creation):

• Strategy documents ({project_root}/​strategy/)
• Business owner requirements
• Market analysis
• Stakeholder inputs

Downstream Artifacts (what BRD drives):

• PRD (Layer 2) - Product requirements derived from BRD
• EARS (Layer 3) - Formal requirements from BRD business needs
• BDD (Layer 4) - Test scenarios validating BRD objectives
• ADR (Layer 5) - Architecture decisions for topics identified in BRD Section "Architecture Decision Requirements"

Same-Type Document Relationships (conditional):

• @related-brd: BRD-NN - BRDs sharing business domain context
• @depends-brd: BRD-NN - BRD that must be implemented first (e.g., platform BRD before feature BRD)

Creation Process

Step 1: Determine BRD Type

Use questionnaire above to determine Platform vs Feature BRD.

Step 2: Read Strategy Documents

Read relevant {project_root}/​strategy/ sections to understand business logic.

Step 3: Select Template

Choose appropriate template (comprehensive, simplified, or domain-specific).

Step 4: Reserve ID Number

Check docs/​BRD/ for next available ID number (e.g., BRD-01, BRD-02).

Step 5: Create BRD Folder and Files

Folder structure (DEFAULT - nested folder per document with descriptive slug):

1. Create folder: docs/​BRD/​BRD-NN_{slug}/ (folder slug MUST match index file slug)
2. Create index file: docs/​BRD/​BRD-NN_{slug}/​BRD-NN.0_{section_type}.md (shortened, PREFERRED)
3. Create section files: docs/​BRD/​BRD-NN_{slug}/​BRD-NN.S_{section_type}.md (shortened, PREFERRED)

Example (Shortened Pattern - PREFERRED):

docs/​BRD/​BRD-01_platform_architecture/
├── BRD-01.0_index.md
├── BRD-01.1_executive_summary.md
├── BRD-01.2_business_context.md
└── BRD-01.3_requirements.md

Note: Folder contains descriptive slug, so filenames can omit it. Full pattern (BRD-01.0_platform_architecture_index.md) also accepted for backward compatibility.

OPTIONAL (for small documents <25KB): docs/​BRD/​BRD-NN_{slug}.md (monolithic)

Step 6: Fill Document Control Section

Complete all required metadata fields and initialize Document Revision History table.

Step 7: Complete Core Sections

Fill all 18 required sections following template structure.

Platform BRD: Populate sections 3.6 and 3.7 with technology details Feature BRD: Mark sections 3.6 and 3.7 as "N/​A - See Platform BRD-NN"

Step 8: Document Architecture Decision Requirements

List topics needing architectural decisions (do NOT reference specific ADR numbers).

Step 9: Add Strategy References

In Traceability section, link to specific {project_root}/​strategy/ sections.

Step 10: Create/​Update Traceability Matrix

MANDATORY: Create or update docs/​BRD/​BRD-000_TRACEABILITY_MATRIX.md

• Use template: ai_dev_flow/​BRD/​BRD-000_TRACEABILITY_MATRIX-TEMPLATE.md
• Add BRD entry with upstream sources and downstream artifacts
• Update traceability matrix in same commit after BRD validation passes (see SHARED_CONTENT.md Traceability Matrix Update Workflow)

Step 11: Validate BRD

Run validation scripts:

# BRD structure validation
./​ai_dev_flow/​scripts/​validate_brd_template.sh docs/​BRD/​BRD-01_*.md

# Link integrity
./​ai_dev_flow/​scripts/​validate_links.py --path docs/​BRD/

Step 12: Commit Changes

Commit BRD file and traceability matrix together.

Validation

Automated Validation

BRD-Specific Validation:

./​ai_dev_flow/​scripts/​validate_brd_template.sh docs/​BRD/​BRD-01_platform.md

Quality Gates Validation:

./​scripts/​validate_quality_gates.sh docs/​BRD/​BRD-01_platform.md

Manual Checklist

• Document Control section at top (before all numbered sections)
• All required metadata fields completed
• Document Revision History table initialized
• BRD type determined (Platform vs Feature)
• Sections 3.6 & 3.7 handled correctly for BRD type
• Architecture Decision Requirements listed (no ADR numbers referenced)
• Strategy references in Traceability section
• All 18 sections completed
• Traceability matrix created/​updated
• No broken links
• File size <50,000 tokens (standard) or <100,000 tokens (maximum)

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: ai_dev_flow/​DIAGRAM_STANDARDS.md and mermaid-gen skill.

Common Pitfalls

1. Referencing ADR numbers: Don't write "See ADR-033" in Architecture Decision Requirements section (ADRs don't exist yet)
2. Wrong sections 3.6/​3.7 treatment: Platform BRD must populate, Feature BRD must reference Platform BRD
3. Missing strategy references: Every BRD must cite {project_root}/​strategy/ sections
4. Document Control not first: Must be at very top before all numbered sections
5. Skipping traceability matrix: MANDATORY to create/​update matrix

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.

Automatic Validation Loop

LOOP:
  1. Run BRD template validation script
  2. IF errors found: Fix issues
  3. IF warnings found: Review and address
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

Validation Command

# BRD structure validation (primary)
./​ai_dev_flow/​scripts/​validate_brd_template.sh docs/​BRD/​BRD-NN_slug.md

# Link integrity validation
./​ai_dev_flow/​scripts/​validate_links.py --path docs/​BRD/

# Quality gates validation
./​scripts/​validate_quality_gates.sh docs/​BRD/​BRD-NN_slug.md

Layer-Specific Upstream Requirements

Auto-Fix Actions (No Confirmation Required)

Validation Codes Reference

Quality Gate

Blocking: YES - Cannot proceed to next document until Phase 1 validation passes with 0 errors.

---

Next Skill

After creating BRD, use:

doc-prd - Create Product Requirements Document (Layer 2)

The PRD will:

• Reference this BRD as upstream source
• Include @brd: BRD.NN.01.SS tags (unified 4-segment format)
• Define product features and KPIs
• Inherit Architecture Decision Requirements topics

Reference Documents

For supplementary documentation related to BRD artifacts:

• Format: BRD-REF-NNN_{slug}.md
• Skill: Use doc-ref skill
• Validation: Reduced (4 checks only)
• Examples: Project overviews, executive summaries, stakeholder guides

BRD-REF Ready-Score Exemption

BRD-REF documents are EXEMPT from ready-scores and quality gates:

Purpose: BRD-REF documents are reference targets that other documents link to. They provide supporting information, context, or external references but do not define formal business requirements.

Reference: See ai_dev_flow/​BRD/​BRD_VALIDATION_RULES.md for validation details.

Related Resources

• Main Guide: ai_dev_flow/​SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
• Platform vs Feature Guide: ai_dev_flow/​PLATFORM_VS_FEATURE_BRD.md
• BRD Creation Rules: ai_dev_flow/​BRD/​BRD_CREATION_RULES.md
• BRD Validation Rules: ai_dev_flow/​BRD/​BRD_VALIDATION_RULES.md
• BRD README: ai_dev_flow/​BRD/​README.md
• Shared Standards: .claude/​skills/​doc-flow/​SHARED_CONTENT.md

Quick Reference

BRD Purpose: Define business needs and objectives

Layer: 1 (Entry point)

Tags Required: None (0 tags)

Key Decision: Platform vs Feature BRD

Critical Sections:

• 3.6 Technology Stack Prerequisites (Platform BRD populates, Feature BRD references)
• 3.7 Mandatory Technology Conditions (Platform BRD populates, Feature BRD references)
• Architecture Decision Requirements (list topics, NOT ADR numbers)

Next: doc-prd