name	doc-brd: Create Business Requirements Documents (Layer 1)
description	Create Business Requirements Documents (BRD) following SDD methodology - Layer 1 artifact defining business needs and objectives
tags	sdd-workflow, layer-1-artifact, shared-architecture
custom_fields	[object Object]

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:

List existing upstream artifacts:

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

Reference only existing documents in traceability tags
Use null only when upstream artifact type genuinely doesn't exist
NEVER use placeholders like BRD-XXX or TBD
Do NOT create missing upstream artifacts - skip functionality instead

Before creating a BRD, read:

Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
Template: ai_dev_flow/BRD/BRD-TEMPLATE.md
Creation Rules: ai_dev_flow/BRD/BRD_CREATION_RULES.md
Validation Rules: ai_dev_flow/BRD/BRD_VALIDATION_RULES.md
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:

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

Common Element Types:

Code	Type	Example
01	Functional Requirement	BRD.02.01.01
06	Acceptance Criteria	BRD.02.06.01
23	Business Objective	BRD.02.23.01

⚠️ 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

Does this BRD define infrastructure, technology stack, or cross-cutting concerns?
- Yes → Likely Platform BRD
- No → Continue
Does this BRD describe a specific user-facing workflow or feature?
- Yes → Likely Feature BRD
- No → Continue
Will other BRDs depend on or reference this BRD's architectural decisions?
- Yes → Likely Platform BRD
- No → Likely Feature BRD
Does this BRD establish patterns, standards, or capabilities used across multiple features?
- Yes → Platform BRD
- No → Feature BRD
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:

Executive Summary
Business Context
Stakeholder Analysis
Business Requirements
Success Criteria
Constraints and Assumptions
Architecture Decision Requirements (topics needing ADRs, NOT specific ADR numbers)
Risk Assessment
Traceability (Section 7 format from SHARED_CONTENT.md) 10-16. Additional content sections (see BRD-TEMPLATE.md for full structure)
Glossary - Domain terms and definitions
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:

{project_root}/strategy/README.md - Performance targets, strategy goals
{project_root}/strategy/strategy_overview.md - Strategic framework
{project_root}/strategy/core_algorithm.md - Primary algorithm specifications
{project_root}/strategy/risk_management.md - Risk management policies
{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)

Component	Description	Example
`{DOC_TYPE}`	Document type	`BRD`
`.NN`	Document number (2-9 digits)	`.01` = BRD-01
`.EE`	Element type code (01=Functional Req)	`.01` = functional requirement
`.SS`	Sequential number (2-9 digits)	`.03` = third item

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:

BRD Section 7.2 → Defines business need ({DOC_TYPE}.NN.EE.SS)
PRD Section 18 → Elaborates with technical options (references {DOC_TYPE}.NN.EE.SS)
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:

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR, IPLAN, ICON	Technical artifacts - references to files/documents
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	Hierarchical artifacts - references to elements inside documents

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):

Create folder: docs/BRD/BRD-NN_{slug}/ (folder slug MUST match index file slug)
Create index file: docs/BRD/BRD-NN_{slug}/BRD-NN.0_{section_type}.md (shortened, PREFERRED)
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

Referencing ADR numbers: Don't write "See ADR-033" in Architecture Decision Requirements section (ADRs don't exist yet)
Wrong sections 3.6/3.7 treatment: Platform BRD must populate, Feature BRD must reference Platform BRD
Missing strategy references: Every BRD must cite {project_root}/strategy/ sections
Document Control not first: Must be at very top before all numbered sections
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

This Layer	Required Upstream Tags	Count
BRD (Layer 1)	None (entry point)	0 tags

Auto-Fix Actions (No Confirmation Required)

Issue	Fix Action
Invalid tag format	Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken link	Recalculate path from current location
Missing traceability section	Insert from template

Validation Codes Reference

Code	Description	Severity
XDOC-006	Tag format invalid	ERROR
XDOC-008	Broken internal link	ERROR
XDOC-009	Missing traceability section	ERROR

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:

Standard BRD	BRD-REF
PRD-Ready Score: ✅ Required (≥90%)	PRD-Ready Score: NOT APPLICABLE
Cumulative tags: Required	Cumulative tags: NOT REQUIRED
Quality gates: Full validation	Quality gates: EXEMPT
Format: Structured 18 sections	Format: Free format, business-oriented

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

Install Skill

SKILL.md