@codihaus/claude-skills 1.0.0

package/skills/debrief/SKILL.md

@@ -0,0 +1,647 @@
+---
+name: debrief
+description: Analyze customer requirements and deliver market research, tiered proposals, and recommendations
+version: 3.8.0
+---
+
+# /debrief - Business Requirements Document (BRD)
+
+> **Skill Awareness**: See `skills/_registry.md` for all available skills.
+> - **Before**: Use `/dev-scout` if existing codebase
+> - **During**: Calls `/dev-arch` to validate architecture feasibility
+> - **After**: Use `/dev-specs` for implementation plans
+> - **Utils**: `/utils/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:**
+
+| 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
+
+## 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:**
+```markdown
+# {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 | [→](../features/auth/) | Planning |
+| Billing | UC-PAY-001 to 005 | [→](../features/billing/) | Planning |
+
+## Use Cases
+
+### 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 |
+
+## Change History
+_No changes yet_
+
+## Quick Links
+- [Context](./context.md)
+- [References](./references.md)
+- [Changelog](./changelog.md)
+```
+
+**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:
+
+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
+3. Add new feature to Features table
+4. Add new use case group
+5. Create feature folder: `plans/features/{feature}/`
+6. Update changelog
+7. 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
+## {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:**
+```markdown
+# {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)
+- [ ] Architecture: Run `/dev-arch {feature}`
+- [ ] Scout: Run `/dev-scout {feature}`
+- [ ] Impact: Analyze integration points
+- [ ] Specs: Run `/dev-specs {feature}`
+```
+
+### Phase 5.5: Architecture Feasibility Check
+
+After creating use cases, call `/dev-arch` to validate:
+
+```
+1. Load dev-arch skill
+   → Read skills/dev-arch/SKILL.md
+
+2. Pass context to dev-arch
+   → Feature requirements from use cases
+   → Existing architecture from scout (if exists)
+
+3. dev-arch evaluates:
+   → Can current architecture support this?
+   → What new architecture decisions needed?
+   → Any blockers or major concerns?
+
+4. dev-arch returns:
+   → "Feasible with existing patterns" → Continue
+   → "Feasible with additions" → Note additions needed
+   → "Requires architecture work" → Create architecture.md first
+```
+
+**Output from dev-arch:**
+
+```markdown
+## Architecture Feasibility
+
+### Assessment: {Feasible | Needs Work | Blocked}
+
+### Current Support
+| Requirement | Support | Gap |
+|-------------|---------|-----|
+| User auth | ✓ Exists | None |
+| Payments | ✗ New | Need Stripe integration |
+| Real-time | ✗ New | Need WebSocket |
+
+### Recommended Actions
+1. {Action 1}
+2. {Action 2}
+
+### Architecture Decisions Needed
+- [ ] Payment provider selection
+- [ ] Real-time architecture
+```
+
+This ensures architecture is considered early, not as an afterthought.
+
+### 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}
+
+## 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:**
+```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
+
+---
+
+## 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.)
+3. **Update feature README** with new information
+4. **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
+## Questionnaire History
+| Date | Status | Questions |
+|------|--------|-----------|
+| 2024-01-15 | Processed | 8 answered |
+| 2024-01-22 | Processed | 3 answered |
+```
+
+**In CR file (if applicable):**
+```markdown
+## 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:
+
+```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
+
+- `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