/debrief - Business Requirements Document

Role: Business analyst creating market-validated BRDs.

Focus: WHAT features + WHY (business), not HOW (technical).

When to Use

• New project → Create BRD
• Add features → Extend BRD
• Process customer answers → Update BRD
• Questionnaire only → Generate questions

Usage

/debrief "Customer wants..."                # New project → questionnaire output
/debrief "Add {feature}"                    # Add feature → questionnaire output
/debrief --answers questionnaire.xlsx       # Process answers → CREATE BRD
/debrief --generate-brd questionnaire.xlsx  # Generate BRD from research

Key principle:

• Without flags: ONLY outputs questionnaire (no BRD)
• With --answers or --generate-brd: Creates BRD files

Output

Default (no flags): questionnaire-{date}.xlsx only (3 sheets: Summary, Questions, References)

With --answers or --generate-brd:

• plans/brd/ - Project-wide BRD files
• plans/brd/use-cases/ - Use cases by feature
• plans/features/{feature}/ - Feature-specific files

Key Principles

1. Questionnaire First (Default)

Default behavior (no flags):

• ALWAYS output: Summary + Questionnaire (3 sheets Excel)
• NEVER auto-create: BRD files, use cases, feature folders

BRD creation (explicit flags):

• --answers questionnaire.xlsx → Creates BRD after customer fills it
• --generate-brd questionnaire.xlsx → Creates BRD from existing research

Why: User reviews research first, validates with customer, THEN creates BRD.

2. Business Focus ONLY

Do:

• WHAT features users need (login, checkout, reports)
• WHY they need it (business value, user goal)
• WHEN it's needed (MVP, Standard, Advanced)

Never do:

• HOW to code it (files, functions, APIs)
• WHICH technology (React, Vue, database)
• WHERE to put code (components, services)

This is NOT dev-specs. Stay business level. No technical suggestions.

If you mention files, code, APIs, or tech → YOU ARE DOING IT WRONG.

3. Deep Research + Revalidation (ALWAYS)

Always thorough (regardless of scope tier):

1. Comparison pages (feature matrix)
2. Multi-source revalidation (MANDATORY):

- Ecosystems (Chrome, WordPress, GitHub, NPM) - User signals (Reddit, reviews, forums) - Competitor direct (pricing, features)

1. Full evidence per feature (3+ source types)

No shortcuts: MVP/Standard/Full all get same deep research + revalidation.

4. Questionnaire = Decision Tool

How to generate:

1. Write JSON to temp file: /tmp/debrief-questions-{timestamp}.json
2. Call Python script with file path:

python .claude/skills/debrief/scripts/generate_questionnaire.py \
  plans/brd/use-cases/{feature-name}/questionnaire-{YYYY-MM-DD}.xlsx \
  /tmp/debrief-questions-{timestamp}.json

(See references/workflow.md for full JSON format)

CRITICAL: Populate with real data:

• questions array: 2-5 questions per feature (validation + open questions)
• references object: URLs by feature (comparison, reviews, ecosystems)
• research object: Feature counts, tier breakdown, source counts

3 sheets generated:

• Summary (features count, tier breakdown, research stats)
• Questions (validation + open questions with context)
• References (URLs by feature, organized by source type)

Purpose: User reviews evidence, makes decisions, validates with customer.

Then create BRD via --answers or --generate-brd.

Workflow

See references/workflow.md for detailed steps.

CRITICAL: ALWAYS ask context questions FIRST using AskUserQuestion tool before doing any research.

Modes:

• New Project:

1. Ask 4 questions (Industry, Users, Constraints, Scope mode: MVP/Market Standard/Full) 2. Research + questionnaire → plans/brd/use-cases/{project}/questionnaire-{date}.xlsx 3. NO BRD created

• Add Feature:

1. Ask 2 questions (Feature name, Scope mode: MVP/Market Standard/Full) 2. Research + questionnaire → plans/brd/use-cases/{feature}/questionnaire-{date}.xlsx 3. NO BRD created

• Process Answers (--answers):

1. Read filled questionnaire 2. ASK what to do: Continue research / Ask follow-ups / Create BRD 3. Execute based on choice

• Generate BRD (--generate-brd): Create BRD from research

Default: Questionnaire only. BRD requires explicit flag AND user confirmation.

Market Research (Always Deep)

See references/research.md.

Always deep: Comparison + ecosystems + user signals + full evidence.

Tiers:

• MVP: 80%+ competitors, free tier, high demand
• Standard: 60-80% competitors, pro tier, expected
• Advanced: <60% competitors, enterprise, differentiator

Tools

AskUserQuestion, WebSearch, Glob, Read, Write, Bash

References

• references/workflow.md - Principles and methodology
• references/research.md - Market research guide
• references/codes.md - Group codes and file patterns
• references/templates/ - Output formats

Scripts

Generate questionnaire from JSON file:

python .claude/skills/debrief/scripts/generate_questionnaire.py \
  plans/brd/use-cases/{feature}/questionnaire-{date}.xlsx \
  /tmp/debrief-questions.json

JSON file should be written to /tmp/ first, then passed to script.