debrief

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

```

/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

```

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

```

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:

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

```json

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

```json

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

```markdown

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

> Feature: [[feature-{feature}]]

> Related: [[uc-xxx-nnn]]

> Status: Draft

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

• [ ] Given {context}, when {action}, then {result}

• {Rule}

{How this connects to existing features}

• {Question}

• [{Link}]({url})

```

Phase 4: Generate/Update BRD Files

#### For New Project:

Create plans/brd/ structure:

README.md:

```markdown

# {Project Name}

> Created: {date}

> Status: Active

> Codebase: New | Existing

{Project description}

```mermaid

flowchart LR

A[User] --> B{Action}

B --> C[Feature 1]

B --> D[Feature 2]

```

| Feature | Use Cases | Technical | Status |

|---------|-----------|-----------|--------|

| Auth | UC-AUTH-001 to 003 | [→](../features/auth/) | Planning |

| Billing | UC-PAY-001 to 005 | [→](../features/billing/) | Planning |

Authentication ([→ use-cases/auth/](./use-cases/auth/))

| ID | Title | Priority | Status |

|----|-------|----------|--------|

| [UC-AUTH-001](./use-cases/auth/UC-AUTH-001-login.md) | Login | Must | Draft |

| [UC-AUTH-002](./use-cases/auth/UC-AUTH-002-signup.md) | Signup | Must | Draft |

Billing ([→ use-cases/billing/](./use-cases/billing/))

| ID | Title | Priority | Status |

|----|-------|----------|--------|

| [UC-PAY-001](./use-cases/billing/UC-PAY-001-checkout.md) | Checkout | Must | Draft |

_No changes yet_

• [Context](./context.md)
• [References](./references.md)
• [Changelog](./changelog.md)

```

context.md:

```markdown

# Context

| Role | Responsibility |

|------|----------------|

| Persona | Description | Key Needs |

|---------|-------------|-----------|

{How things work today}

{From codebase discovery, if applicable}

| Feature | Evidence | Status |

|---------|----------|--------|

| Type | Description | Impact |

|------|-------------|--------|

-

-

```

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

```markdown

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

```markdown

# {Feature Name}

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

> Status: Planning

| ID | Title |

|----|-------|

| [UC-XXX-001](../../brd/use-cases/UC-XXX-001-slug.md) | Title |

• [ ] 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:

```markdown

# CR-{NNN}: {Title}

> Date: {date}

> Status: Draft | Approved | Implemented

> Requestor: {who requested}

{What is being requested}

{Why this change is needed}

New Use Cases

| ID | Title |

|----|-------|

Modified Use Cases

| ID | Change |

|----|--------|

| UC-XXX-001 | {What changes} |

Affected Features

• {feature}: {how affected}

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

```json

{

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

```bash

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

---

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:

```markdown

| Date | Status | Questions |

|------|--------|-----------|

| 2024-01-15 | Processed | 8 answered |

| 2024-01-22 | Processed | 3 answered |

```

In CR file (if applicable):

```markdown

• [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

| Tool | Purpose |

|------|---------|

| AskUserQuestion | Context gathering |

| Glob | Find existing files, codebase scan |

| Read | Read existing BRD, docs |

| Write | Create/update BRD files |

| WebSearch | Market research |

Customer Questionnaire

Generate dynamic questionnaire based on open questions identified during debrief:

```bash

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:

```bash

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