/debrief - Business Requirements Document (BRD)

Skill Awareness: See skills/_registry.md for all available skills.

Before: Use /dev-scout if existing codebase

After: Use /dev-specs for implementation plans

Related: /diagram for architecture, /docs-graph for relationships

Create and maintain the unified BRD for a project. Handles initial requirements and feature additions.

When to Use

Start a new project (creates initial BRD)
Add new feature to existing project (updates BRD)
Process change requests (tracked separately)

Usage

/debrief "Customer wants a SaaS platform"     # New project
/debrief "Add billing and subscriptions"      # Add feature
/debrief requirements.pdf                      # From document
/debrief                                       # Interactive
/debrief --answers questionnaire.xlsx         # Process customer answers

Output Structure

All output goes to unified plans/ structure:

plans/
├── brd/                         # This skill manages this folder
│   ├── README.md                # Project overview, feature index
│   ├── context.md               # Stakeholders, constraints
│   ├── use-cases/               # ALL use cases, grouped by feature
│   │   ├── auth/                # Auth feature UCs
│   │   │   ├── UC-AUTH-001-login.md
│   │   │   ├── UC-AUTH-002-signup.md
│   │   │   └── UC-AUTH-003-forgot.md
│   │   ├── billing/             # Billing feature UCs
│   │   │   ├── UC-PAY-001-checkout.md
│   │   │   └── UC-PAY-002-refund.md
│   │   └── ...
│   ├── changes/                 # Change requests
│   │   └── CR-001-add-sso.md
│   ├── references.md
│   └── changelog.md
│
├── features/                    # Created per feature
│   ├── auth/                    # /dev-scout and /dev-specs work here
│   ├── billing/
│   └── ...
│
└── scout/                       # /dev-scout project level

Workflow

Mode Detection

On start, detect current mode:

New Project: plans/brd/ doesn't exist
Add Feature: plans/brd/ exists, adding new use cases
Change Request: Modifying existing use cases
Process Answers: --answers flag with questionnaire file

Phase 0: Check Documentation Graph

For Add Feature and Change Request modes, read plans/docs-graph.json:

1. Read plans/docs-graph.json (if exists)
2. List existing use cases and features
3. Check for potential duplicates or overlaps
4. Identify related nodes for impact analysis

How docs-graph helps debrief:

Mode	Graph Provides
Add Feature	Existing UCs to avoid duplicates
Change Request	Nodes affected by the change
New Project	Skip (no graph yet)

Duplicate Detection:

Before creating new UCs, check if similar ones exist:

// User requests: "Add login functionality"
// Graph shows:
{
  "existing": [
    {"id": "uc-auth-001", "label": "Login", "type": "use-case"},
    {"id": "uc-auth-002", "label": "Signup", "type": "use-case"}
  ]
}
// → Warn: "Login already exists as UC-AUTH-001. Create CR instead?"

Impact Analysis for Changes:

For Change Requests, find what links to the affected UC:

// Modifying: uc-auth-001 (Login)
// Graph edges show:
{
  "incoming": ["uc-auth-002", "uc-auth-003", "spec-auth-001"],
  "outgoing": ["feature-auth"]
}
// → Impact: 3 other nodes reference Login, need to update

This prevents:

Duplicate use cases
Orphaned specs (spec without UC)
Missing impact analysis on changes

Phase 1: Context Gathering

Ask using AskUserQuestion:

For New Project:

Q1: Project Type & Source Code

New project (no existing code)
Existing codebase (current folder)
Existing codebase (different folder)

Q2: Industry/Niche

SaaS B2B / SaaS B2C / E-commerce / Marketplace / Enterprise / Other

Q3: Target Users

Business users (B2B) / Consumers (B2C) / Internal / Mixed

Q4: Known Constraints (multi-select)

Timeline / Budget / Compliance / Integration / None

Q5: Scope Tier

Core (3-5 use cases) / Standard (8-12) / Full (15+)

For Add Feature:

Q1: Feature Name

What to call this feature (e.g., "billing", "notifications")

Q2: Scope for this feature

Core / Standard / Full

Phase 1.5: Codebase Discovery (if existing codebase)

See references/file-patterns.md for scan patterns.

Check for docs (README, CLAUDE.md)
Scan frontend files (.vue, .tsx, .jsx)
Infer existing features
Summarize in context.md

Phase 2: Market Research

Search for references (not prescriptions):

Industry patterns
User flows
Compliance requirements
Documentation links

Output to references.md.

Phase 3: Use Case Generation

Determine feature folder from context (e.g., billing, auth, notifications).

Determine group code from feature (e.g., billing → PAY, auth → AUTH).

Create feature subfolder in use-cases if not exists:

plans/brd/use-cases/{feature}/

For each use case, create file in the feature subfolder:

Path: plans/brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md

# UC-{GROUP}-{NNN}: {Title}

> **Feature**: [[feature-{feature}]]
> **Related**: [[uc-xxx-nnn]]
> **Status**: Draft

## User Story
As a {role}, I want {goal}, so that {benefit}.

## Acceptance Criteria
- [ ] Given {context}, when {action}, then {result}

## Business Rules
- {Rule}

## Integration Notes
{How this connects to existing features}

## Open Questions
- {Question}

## References
- [{Link}]({url})

Phase 4: Generate/Update BRD Files

For New Project:

Create plans/brd/ structure:

README.md:

# {Project Name}

> **Created**: {date}
> **Status**: Active
> **Codebase**: New | Existing

## Overview
{Project description}

## Overview Flow

```mermaid
flowchart LR
    A[User] --> B{Action}
    B --> C[Feature 1]
    B --> D[Feature 2]

Features

Feature	Use Cases	Technical	Status
Auth	UC-AUTH-001 to 003	→	Planning
Billing	UC-PAY-001 to 005	→	Planning

Use Cases

Authentication (→ use-cases/auth/)

ID	Title	Priority	Status
UC-AUTH-001	Login	Must	Draft
UC-AUTH-002	Signup	Must	Draft

Billing (→ use-cases/billing/)

ID	Title	Priority	Status
UC-PAY-001	Checkout	Must	Draft

Change History

No changes yet

Quick Links


**context.md:**
```markdown
# Context

## Stakeholders
| Role | Responsibility |
|------|----------------|

## Users / Personas
| Persona | Description | Key Needs |
|---------|-------------|-----------|

## Current State
{How things work today}

## Existing Features
{From codebase discovery, if applicable}

| Feature | Evidence | Status |
|---------|----------|--------|

## Constraints
| Type | Description | Impact |
|------|-------------|--------|

## Assumptions
-

## Dependencies
-

For Add Feature:

Read existing plans/brd/README.md
Check BRD status:
- If any use cases are "Confirmed" → Create CR first (see Phase 6)
- If all use cases are "Draft" → Add directly
Add new feature to Features table
Add new use case group
Create feature folder: plans/features/{feature}/
Update changelog
Link CR to feature if created

Why CR for confirmed BRDs: Once stakeholders have approved use cases, any addition is a scope change that needs tracking.

changelog.md addition:

## {date} - Added {Feature}
- Added {X} use cases: UC-{GROUP}-001 to {NNN}
- Created feature folder: features/{feature}/

Phase 5: Create Feature Folder

For each feature mentioned, create:

plans/features/{feature}/
├── README.md       # Feature overview, links to use cases
└── .gitkeep        # Placeholder for scout/specs

Feature README.md:

# {Feature Name}

> **Use Cases**: UC-{GROUP}-001 to {NNN}
> **Status**: Planning

## Related Use Cases
| ID | Title |
|----|-------|
| [UC-XXX-001](../../brd/use-cases/UC-XXX-001-slug.md) | Title |

## Technical (pending)
- [ ] Scout: Run `/dev-scout {feature}`
- [ ] Impact: Analyze integration points
- [ ] Specs: Run `/dev-specs {feature}`

Phase 6: Handle Change Requests

If modifying existing use cases:

Create plans/brd/changes/CR-{NNN}-{slug}.md
Update README.md Change History
Update affected use cases with reference

CR-{NNN}-{slug}.md:

# CR-{NNN}: {Title}

> **Date**: {date}
> **Status**: Draft | Approved | Implemented
> **Requestor**: {who requested}

## Request
{What is being requested}

## Reason
{Why this change is needed}

## Impact

### New Use Cases
| ID | Title |
|----|-------|

### Modified Use Cases
| ID | Change |
|----|--------|
| UC-XXX-001 | {What changes} |

### Affected Features
- {feature}: {how affected}

## Notes
{Additional context}

Phase 7: Collect Open Questions

Gather all open questions from:

Use case files (## Open Questions section)
Context gaps (unknowns from Phase 1)
Integration uncertainties
Business rules needing clarification

Build questions list:

{
    "project_name": "{Project Name}",
    "date": "{YYYY-MM-DD}",
    "questions": [
        {
            "category": "Requirements",
            "question": "What is the expected concurrent user load?",
            "priority": "Required",
            "context": "Needed for capacity planning",
            "source": "UC-PAY-003"
        },
        {
            "category": "Business",
            "question": "What payment methods should be supported?",
            "priority": "Required",
            "context": "Affects integration scope",
            "source": "UC-PAY-001"
        }
    ]
}

Categories:

Business - Business model, stakeholders, priorities
Requirements - Feature details, user needs
Constraints - Timeline, budget, compliance
Integration - Third-party systems, APIs
Technical - Only if blocking business decisions

Priority:

Required - Blocks use case completion
Optional - Nice to clarify, not blocking

Phase 8: Generate Questionnaire

If open questions exist, generate customer questionnaire:

python scripts/generate_questionnaire.py {output_path} questions.json

Output location (contextual, with date for revision tracking):

New feature: plans/features/{feature}/questionnaire-{YYYY-MM-DD}.xlsx
Change request: plans/brd/changes/CR-{NNN}-questionnaire-{YYYY-MM-DD}.xlsx

Note: No questionnaire at BRD root level. New project questions are associated with specific features or tracked via initial CR.

Creates Excel file with:

Summary sheet (project info, question counts)
Questions sheet (categorized, with context/source)
Answer column for customer to fill

Phase 9: Summary

Output summary:

Use cases created/updated
Features created
Change requests (if any)
Open questions count
Questionnaire generated (if applicable)
Next steps

Next steps suggestions:

Send questionnaire to customer (if generated)
Run /dev-scout for codebase analysis
Run /dev-scout {feature} for targeted analysis
Review use cases with stakeholders
Run /dev-specs {feature} when ready

Process Answers Workflow

When customer returns filled questionnaire, run:

/debrief --answers plans/features/billing/questionnaire-2024-01-20.xlsx

Step 1: Read Questionnaire

Read the Excel file and extract answers:

Parse "Answer" column
Match to source use cases via "Context/Source" column
Flag unanswered required questions

Step 2: Update Related Files

For each answered question:

Find source use case file
Update use case:
- Remove question from ## Open Questions
- Add answer to relevant section (Acceptance Criteria, Business Rules, etc.)
Update feature README with new information
Update CR file if questionnaire is CR-related

Step 3: Handle Questionnaire File

Keep the file for revision history:

File stays at original location with date
Add "Processed: {date}" to Summary sheet
If follow-up needed → new questionnaire with new date

Example revision history:

plans/features/billing/
├── questionnaire-2024-01-15.xlsx  # Initial, processed
├── questionnaire-2024-01-22.xlsx  # Follow-up, processed
└── questionnaire-2024-01-28.xlsx  # Final clarifications

Step 4: Check Completeness

After processing:

Count remaining open questions across related use cases
If still gaps → generate new questionnaire with new date
If complete → update use case status to "Confirmed"

Step 5: Update References

Add questionnaire to relevant files for traceability:

In feature README.md:

## Questionnaire History
| Date | Status | Questions |
|------|--------|-----------|
| 2024-01-15 | Processed | 8 answered |
| 2024-01-22 | Processed | 3 answered |

In CR file (if applicable):

## Clarifications
- [Questionnaire 2024-01-20](./CR-001-questionnaire-2024-01-20.xlsx)

Step 6: Summary

Output:

Questions answered: X/Y
Use cases updated: [list]
Files modified: [list]
Remaining gaps: [if any]
Next questionnaire: [path if generated]
Status: Complete | Needs follow-up

Tools Used

Tool	Purpose
`AskUserQuestion`	Context gathering
`Glob`	Find existing files, codebase scan
`Read`	Read existing BRD, docs
`Write`	Create/update BRD files
`WebSearch`	Market research

Scripts

Customer Questionnaire

Generate dynamic questionnaire based on open questions identified during debrief:

python scripts/generate_questionnaire.py output.xlsx questions.json

Input: JSON file with collected open questions (see Phase 7)

Output: Excel file with:

Summary sheet (project info, priority breakdown, category counts)
Questions sheet (categorized questions with context/source)
Answer column for customer to fill
Required vs Optional priority indicators

Example:

# After debrief creates questions.json
python scripts/generate_questionnaire.py plans/brd/questionnaire.xlsx /tmp/questions.json

The questionnaire only contains questions we couldn't answer from:

Customer brief
Existing codebase (if any)
Market research

References

references/research-queries.md - Search templates
references/use-case-template.md - UC file template
references/group-codes.md - Standard group codes
references/file-patterns.md - Codebase scan patterns
references/change-request-template.md - CR template