debrief（debrief 搜索）

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

1. New Project: plans/brd/ doesn't exist
2. Add Feature: plans/brd/ exists, adding new use cases
3. Change Request: Modifying existing use cases
4. 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:

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.

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

Phase 2: Market Research

Search for references (not prescriptions):

1. Industry patterns
2. User flows
3. Compliance requirements
4. 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

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 | [→](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/../features/auth/) | Planning |
| Billing | UC-PAY-001 to 005 | [→](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/../features/billing/) | Planning |

## Use Cases

### Authentication ([→ use-cases/auth/](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./use-cases/auth/))

| ID | Title | Priority | Status |
| --- | --- | --- | --- |
| [UC-AUTH-001](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./use-cases/auth/UC-AUTH-001-login.md) | Login | Must | Draft |
| [UC-AUTH-002](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./use-cases/auth/UC-AUTH-002-signup.md) | Signup | Must | Draft |

### Billing ([→ use-cases/billing/](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./use-cases/billing/))

| ID | Title | Priority | Status |
| --- | --- | --- | --- |
| [UC-PAY-001](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./use-cases/billing/UC-PAY-001-checkout.md) | Checkout | Must | Draft |

## Change History

*No changes yet*

## Quick Links

- [Context](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./context.md)
- [References](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./references.md)
- [Changelog](https://github.com/codihaus/claude-skills/blob/HEAD/.claude/skills/debrief/./changelog.md)

context.md:

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

1. Read existing plans/brd/README.md
2. Check BRD status:

- If any use cases are "Confirmed" → Create CR first (see Phase 6) - If all use cases are "Draft" → Add directly

1. Add new feature to Features table
2. Add new use case group
3. Create feature folder: plans/features/{feature}/
4. Update changelog
5. 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:

1. Create plans/brd/changes/CR-{NNN}-{slug}.md
2. Update README.md Change History
3. 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:

1. Use case files (## Open Questions section)
2. Context gaps (unknowns from Phase 1)
3. Integration uncertainties
4. 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:

1. Find source use case file
2. Update use case:

- Remove question from ## Open Questions - Add answer to relevant section (Acceptance Criteria, Business Rules, etc.)

1. Update feature README with new information
2. 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

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