@codihaus/claude-skills 1.6.7 → 1.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {

package/skills/debrief/SKILL.md

@@ -61,468 +61,287 @@ plans/
 └── scout/                       # /dev-scout project level
 ```
 
-## Workflow
+## Expected Outcome
 
-### Mode Detection
+Depending on mode:
 
-On start, detect current mode:
+**New Project:**
+- BRD with use cases grouped by feature
+- Context document (stakeholders, constraints, users)
+- Market research (MVP/Standard/Advanced feature tiers)
+- Feature folders created
+- Architecture feasibility validated
+- Questionnaire for customer gaps
 
-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
+**Add Feature:**
+- New use cases added to BRD
+- Feature folder created
+- Links to existing features
+- Change request (if BRD confirmed)
 
-### Phase 0: Check Documentation Graph
+**Change Request:**
+- CR document tracking the change
+- Affected use cases updated
+- Impact analysis
 
-For Add Feature and Change Request modes, read `plans/docs-graph.json`:
+**Process Answers:**
+- Use cases updated with answers
+- Open questions resolved
+- Status updated to "Confirmed" if complete
 
-```
-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
-```
+## Success Criteria
 
-**How docs-graph helps debrief:**
+- Use cases are testable (clear acceptance criteria)
+- No duplicate features (checked via docs-graph if exists)
+- Open questions captured for customer
+- Architecture can support requirements (validated by /dev-arch)
+- Proper mode detected and handled
+- Naming conventions followed (UC-{GROUP}-{NNN}-{slug})
 
-| Mode | Graph Provides |
-|------|----------------|
-| Add Feature | Existing UCs to avoid duplicates |
-| Change Request | Nodes affected by the change |
-| New Project | Skip (no graph yet) |
+## Modes
 
-**Duplicate Detection:**
+Detect automatically on start:
 
-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?"
-```
+| Condition | Mode | Behavior |
+|-----------|------|----------|
+| `plans/brd/` doesn't exist | **New Project** | Create full BRD structure |
+| `plans/brd/` exists, adding features | **Add Feature** | Add to existing BRD, check for duplicates |
+| Modifying confirmed use cases | **Change Request** | Create CR first, then update |
+| `--answers` flag provided | **Process Answers** | Update use cases with customer responses |
 
-**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
-```
+## Context Gathering
 
-This prevents:
-- Duplicate use cases
-- Orphaned specs (spec without UC)
-- Missing impact analysis on changes
+Use `AskUserQuestion` to understand project context and scope preferences.
 
-### Phase 1: Context Gathering
+### For New Project
 
-Ask using `AskUserQuestion`:
-
-**For New Project:**
+Ask 5 key questions using `AskUserQuestion`:
 
 **Q1: Project Type & Source Code**
+Options:
 - 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
+Options:
+- SaaS B2B
+- SaaS B2C
+- E-commerce
+- Marketplace
+- Enterprise
+- Other
 
 **Q3: Target Users**
-- Business users (B2B) / Consumers (B2C) / Internal / Mixed
+Options:
+- Business users (B2B)
+- Consumers (B2C)
+- Internal users
+- 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
+Options:
+- Timeline constraint
+- Budget constraint
+- Compliance requirements
+- Integration requirements
+- None
 
-### 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 |
+**Q5: Scope Tier Preference**
+Options:
+- **Core (3-5 use cases)** - MVP, essential features only
+- **Standard (8-12 use cases)** - Competitive parity, market standard
+- **Full (15+ use cases)** - Advanced features, differentiation
 
-### 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 |
+This helps align on MVP vs market standard vs advanced features upfront.
 
-## Change History
-_No changes yet_
+### For Add Feature
 
-## 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:**
+Ask 2 questions:
 
+**Q1: Feature Name**
+What to call this feature (e.g., "billing", "notifications", "analytics")
+
+**Q2: Scope for This Feature**
+Options:
+- **Core** - MVP/essential only
+- **Standard** - Competitive parity
+- **Full** - Advanced/differentiation features
+
+### For Existing Codebase
+
+**If user indicates existing codebase:**
+- Scan for docs (CLAUDE.md, README, CONTRIBUTING)
+- Scan frontend files (.vue, .tsx, .jsx) to infer existing features
+- Use `references/file-patterns.md` for scan patterns
+- Summarize findings in `context.md`
+
+This codebase discovery informs which features already exist and what gaps remain.
+
+## Duplicate Prevention
+
+**Use docs-graph** (if exists) to check for duplicates:
+- List existing use cases and features
+- Check for potential overlaps
+- Identify related nodes for impact analysis
+
+**Before creating use cases:**
+- Check if similar UC already exists
+- If modifying confirmed UC → Create CR instead
+
+## Use Case Generation
+
+**Output location:** `plans/brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
+
+**Each use case includes:**
+- User story (As a X, I want Y, so that Z)
+- Acceptance criteria (testable)
+- Business rules
+- Integration notes
+- Open questions
+- References from market research
+
+## Market Research
+
+**Why research:** Understand feature tiers and competitive landscape to inform scope decisions.
+
+**Combines with user's scope preference:**
+- User chose "Core" → Focus research on MVP features
+- User chose "Standard" → Research MVP + market standard features
+- User chose "Full" → Research all tiers including advanced/differentiation
+
+**What to research:**
+- Industry patterns (what similar products do)
+- User flows (standard UX patterns in this domain)
+- Compliance requirements (regulations, standards, must-haves)
+- Documentation links (references for engineers)
+
+**Expected insights organized by tier:**
+- **MVP Features (Must-Have):** Minimum to be viable product
+  - Example: Login, basic CRUD, core workflows
+- **Market Standard (Competitive Parity):** What competitors offer
+  - Example: SSO, notifications, exports
+- **Advanced Features (Differentiation):** What sets apart top products
+  - Example: AI suggestions, real-time collaboration, advanced analytics
+
+**Output:**
+- `references.md` - Organized by feature tier with links and notes
+- Use insights to:
+  - Validate user's scope choice (Core/Standard/Full)
+  - Prioritize use cases (Must/Should/Could)
+  - Guide customer conversations ("This is standard" vs "This is premium")
+
+**Format for references.md:**
 ```markdown
-## Architecture Feasibility
+## {Feature} - Market Research
 
-### Assessment: {Feasible | Needs Work | Blocked}
+### MVP (Must-Have)
+- Login/Signup - Industry standard: email + password + OAuth
+  - Reference: [Auth0 best practices](link)
+- Profile management - Every product has this
 
-### Current Support
-| Requirement | Support | Gap |
-|-------------|---------|-----|
-| User auth | ✓ Exists | None |
-| Payments | ✗ New | Need Stripe integration |
-| Real-time | ✗ New | Need WebSocket |
+### Market Standard (Competitive Parity)
+- SSO integration - 80% of competitors offer this
+  - Reference: [SAML guide](link)
+- Email notifications - User expectation
 
-### Recommended Actions
-1. {Action 1}
-2. {Action 2}
-
-### Architecture Decisions Needed
-- [ ] Payment provider selection
-- [ ] Real-time architecture
+### Advanced (Differentiation)
+- AI-powered recommendations - Only Competitor X has this
+  - Reference: [ML recommendation patterns](link)
+- Real-time collaboration - Top-tier feature
 ```
 
-This ensures architecture is considered early, not as an afterthought.
-
-### Phase 6: Handle Change Requests
+**How it guides use case creation:**
+- User chose "Core" → Create use cases for MVP tier only
+- User chose "Standard" → Create use cases for MVP + Market Standard tiers
+- User chose "Full" → Create use cases for all tiers
 
-If modifying existing use cases:
+This alignment ensures use cases match the agreed scope.
 
-1. Create `plans/brd/changes/CR-{NNN}-{slug}.md`
-2. Update README.md Change History
-3. Update affected use cases with reference
+## BRD Structure
 
-**CR-{NNN}-{slug}.md:**
-```markdown
-# CR-{NNN}: {Title}
+**Create/Update:**
+- `README.md` - Project overview, feature index, use case tables
+- `context.md` - Stakeholders, users, constraints, existing features
+- `references.md` - Market research links
+- `changelog.md` - Track all BRD updates
+- `changes/` - Change requests (if modifying confirmed BRD)
 
-> **Date**: {date}
-> **Status**: Draft | Approved | Implemented
-> **Requestor**: {who requested}
+**Feature folders:**
+- `plans/features/{feature}/README.md` - Feature overview, links to use cases
 
-## Request
-{What is being requested}
+## Architecture Validation
 
-## Reason
-{Why this change is needed}
+**After creating use cases**, call `/dev-arch` to validate feasibility:
 
-## Impact
+**dev-arch checks:**
+- Can current architecture support this?
+- What new architecture decisions needed?
+- Any blockers or major concerns?
 
-### New Use Cases
-| ID | Title |
-|----|-------|
+**dev-arch returns:**
+- Feasible with existing patterns → Continue
+- Feasible with additions → Note what's needed
+- Requires architecture work → Create architecture.md first
 
-### Modified Use Cases
-| ID | Change |
-|----|--------|
-| UC-XXX-001 | {What changes} |
+## Open Questions & Questionnaire
 
-### Affected Features
-- {feature}: {how affected}
+**Collect open questions from:**
+- Use case "Open Questions" sections
+- Context gaps
+- Integration uncertainties
+- Business rules needing clarification
 
-## Notes
-{Additional context}
+**If gaps exist, generate questionnaire:**
+```bash
+python .claude/skills/debrief/scripts/generate_questionnaire.py {output_path} questions.json
 ```
 
-### 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"
-        }
-    ]
-}
-```
+**Output location:**
+- New feature: `plans/features/{feature}/questionnaire-{YYYY-MM-DD}.xlsx`
+- Change request: `plans/brd/changes/CR-{NNN}-questionnaire-{YYYY-MM-DD}.xlsx`
 
-**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
+**Categories:** Business, Requirements, Constraints, Integration, Technical
+**Priority:** Required (blocks UC), Optional (nice to clarify)
 
-**Priority:**
-- `Required` - Blocks use case completion
-- `Optional` - Nice to clarify, not blocking
+## Change Requests
 
-### Phase 8: Generate Questionnaire
+**Create CR when:**
+- Modifying confirmed use cases
+- BRD status is "Confirmed" and adding features
+- Scope expansion discovered
 
-If open questions exist, generate customer questionnaire:
+**CR includes:**
+- Request description
+- Reason for change
+- Impact analysis (new/modified UCs, affected features)
+- Questionnaire (if questions exist)
 
-```bash
-python .claude/skills/debrief/scripts/generate_questionnaire.py {output_path} questions.json
-```
+## Process Answers Workflow
 
-**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`
+**When customer returns questionnaire:**
 
-**Note**: No questionnaire at BRD root level. New project questions are associated with specific features or tracked via initial CR.
+1. **Read questionnaire** - Extract answers from Excel
+2. **Update use cases** - Add answers to relevant sections, remove from open questions
+3. **Update feature README** - Note questionnaire processed
+4. **Check completeness** - If gaps remain, generate new questionnaire with new date
+5. **Update status** - Mark UCs as "Confirmed" if complete
 
-Creates Excel file with:
-- Summary sheet (project info, question counts)
-- Questions sheet (categorized, with context/source)
-- Answer column for customer to fill
+**Keep questionnaire files** for revision history with date stamps.
 
-### Phase 9: Summary
+## Summary Output
 
-Output summary:
-- Use cases created/updated
+Provide summary with:
+- Use cases created/updated (count)
 - Features created
 - Change requests (if any)
 - Open questions count
-- Questionnaire generated (if applicable)
-- Next steps
-
-**Next steps suggestions:**
-- Send questionnaire to customer (if generated)
-- Review use cases with stakeholders
-- For new projects: Run `/dev-specs {feature}` (will auto-scout)
-- For existing codebases:
-  - First time: Run `/dev-scout` (project-level analysis) OR let `/dev-specs` auto-scout
-  - Subsequent: Run `/dev-specs {feature}` directly (auto-scouts feature if needed)
-
-**Note**: `/dev-specs` automatically runs both project-level and feature-level scouts if they don't exist, so you typically don't need to run `/dev-scout` manually unless you want to review the codebase analysis separately first.
+- Questionnaire location (if generated)
+- Next steps:
+  - Send questionnaire to customer
+  - Review with stakeholders
+  - Run `/dev-specs {feature}` (auto-scouts if needed)
+  - OR run `/dev-scout` first for project overview
 
 ---