@codihaus/claude-skills 1.6.21 → 1.6.23

package/skills/debrief/references/workflow.md

@@ -0,0 +1,340 @@
+# Workflow Principles
+
+**Mindset**: Business analyst. Focus on WHAT and WHY, defer HOW to /dev-specs.
+
+**Methodology**: Mode detection → Context gathering → Research → Document → Questionnaire
+
+**Expected Outcome**: Market-validated BRD with tiered features, lean use cases, customer questionnaire.
+
+---
+
+## Mode Detection
+
+**Principle**: Behavior changes based on context.
+
+**Detection**:
+- `--answers {file}` → Process Answers mode
+- `--generate-brd {file}` → Generate BRD mode
+- `--questionnaire-only` → Questionnaire Only mode
+- No `plans/brd/` → New Project mode
+- `plans/brd/` exists → Add Feature mode
+- Modifying confirmed UC → Change Request mode
+
+**Action**: Execute appropriate workflow for detected mode.
+
+---
+
+## New Project Mode
+
+**Goal**: Create initial BRD with market-validated features.
+
+**Mindset**: Discovery mode. Understand context, research market, validate with customer.
+
+### Context Gathering
+
+**Ask 6 questions** (AskUserQuestion):
+1. Project type (new/existing codebase)
+2. Industry (SaaS/E-commerce/Marketplace/etc.)
+3. Target users (B2B/B2C/Internal)
+4. Constraints (timeline/budget/compliance/integrations)
+5. Scope tier (Core/Standard/Full)
+6. Research depth (Quick 5min / Deep 15-20min)
+
+**If existing codebase**: Scan for docs + features (Glob, Read)
+
+**Output**: Context understanding, scope alignment
+
+---
+
+### Market Research
+
+**Methodology**: See `research.md` for full process.
+
+**Quick** (5 min):
+- Find 2-3 comparison/alternative pages
+- Extract feature matrix
+- Initial tier hypothesis
+
+**Deep** (15-20 min):
+- Comparison pages (initial)
+- Cross-validate with ecosystem + user signals
+- Full tier classification with evidence
+
+**After research, ask output preference**:
+- Summary + Questionnaire (review first)
+- Full BRD (write all files now)
+
+**Output**: Features with tier classification and evidence
+
+---
+
+### Feature Sequencing
+
+**Principle**: Order by dependencies within each tier.
+
+**Common patterns**:
+- Create before operate (signup before login)
+- Auth before features (login before projects)
+- Basic before advanced (CRUD before bulk operations)
+- Data before analytics (tracking before dashboards)
+- Core before extensions (email before templates)
+
+**Validation**: No forward dependencies (UC-001 doesn't depend on UC-002)
+
+**Output**: Sequenced feature list (UC-001, UC-002, UC-003...)
+
+---
+
+### Use Case Generation
+
+**Principle**: Lean 80/20 format (~30 lines).
+
+**Include (20%)**:
+- Story (1 line)
+- Critical acceptance criteria (3-5 bullets)
+- Key business rules (constraints, limits)
+- Open questions (blockers)
+
+**Defer to /dev-specs (80%)**:
+- Detailed flows, integrations, edge cases, UI/UX
+
+**Template**: `templates/use-case.md`
+
+**Output**: Lean use cases in `brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
+
+---
+
+### BRD Structure
+
+**Project-wide** (`brd/`):
+- README.md (all features index)
+- context.md (stakeholders, users, constraints)
+- references.md (industry, compliance, competitor overview)
+- changelog.md
+
+**Feature-specific** (`features/{feature}/`):
+- README.md (feature overview)
+- references.md (market research, tier evidence)
+- questionnaire-{date}.xlsx
+
+**Templates**: `templates/brd-references.md`, `templates/feature-references.md`
+
+**Output**: Organized BRD structure with scope separation
+
+---
+
+### Questionnaire
+
+**Principle**: Always generate. Validate assumptions + fill gaps.
+
+**3 sheets**:
+- **Summary**: Feature count, tier distribution, research stats
+- **Questions**: Validation + open questions
+- **References**: URLs by feature (comparison pages, reviews, ecosystems)
+
+**Output**: `features/{feature}/questionnaire-{date}.xlsx` (permanent reference)
+
+---
+
+### Summary
+
+**Provide**:
+- Files created (brd/, features/)
+- Use case count (lean format)
+- Research summary (comparison pages, evidence sources)
+- Tier distribution (MVP: X, Standard: Y, Advanced: Z)
+- Questionnaire location and question count
+
+**Next steps**:
+- Review BRD with stakeholders
+- Send questionnaire to customer
+- Process with `/debrief --answers {path}`
+- Then `/dev-specs {feature}` for implementation
+
+---
+
+## Add Feature Mode
+
+**Goal**: Extend existing BRD with new feature.
+
+**Mindset**: Continuity mode. Check duplicates, maintain consistency.
+
+### Context Gathering
+
+**Ask 3 questions**:
+1. Feature name
+2. Scope tier (Core/Standard/Full)
+3. Research depth (Quick / Deep)
+
+**Duplicate check**: Read `docs-graph.json` if exists, warn if similar feature found
+
+**Output**: Feature to add, scope confirmed
+
+---
+
+### Research & Document
+
+**Same as New Project**:
+- Market research (comparison-first, see `research.md`)
+- Feature sequencing (dependencies)
+- Lean use cases (templates/use-case.md)
+
+**Update**:
+- `brd/README.md` (add to index)
+- `brd/changelog.md` (log addition)
+- Create `features/{feature}/` folder
+
+**Questionnaire**: Always generate (validation + open questions)
+
+**Output**: Feature added to BRD with research and questionnaire
+
+---
+
+## Process Answers Mode
+
+**Goal**: Update BRD with customer responses.
+
+**Mindset**: Integration mode. Incorporate feedback, resolve gaps.
+
+### Process
+
+**Read questionnaire** (Excel file):
+- Extract answers from "Answer" column
+- Match to source use cases via "Context/Source"
+
+**Update use cases**:
+- Remove questions from "Open Questions" section
+- Add answers to relevant sections (Acceptance Criteria, Business Rules)
+
+**Update feature README**:
+- Log questionnaire as processed
+- Track history
+
+**Check completeness**:
+- If gaps remain → generate new questionnaire (new date)
+- If complete → update UC status to "Confirmed"
+
+**Output**: Updated use cases, questionnaire history, completion status
+
+---
+
+## Change Request Mode
+
+**Goal**: Track modifications to confirmed BRD.
+
+**Mindset**: Traceability mode. Document change rationale and impact.
+
+### Process
+
+**Create CR** (`brd/changes/CR-{NNN}-{slug}.md`):
+- Change description
+- Reason for change
+- Impact analysis (affected UCs)
+
+**If gaps introduced**: Generate questionnaire at `brd/changes/CR-{NNN}-questionnaire-{date}.xlsx`
+
+**Update**: Affected use cases, references, changelog
+
+**Output**: CR document with impact analysis
+
+---
+
+## Generate BRD Mode
+
+**Goal**: Generate full BRD from existing questionnaire research.
+
+**Mindset**: Resumption mode. User reviewed Summary + Questionnaire, ready for full BRD.
+
+### Process
+
+**Read questionnaire**:
+- Summary sheet (features, tiers, research stats)
+- References sheet (source URLs)
+
+**Generate**: Full BRD structure from existing research (no re-research)
+
+**Output**: BRD files + feature folders
+
+---
+
+## Questionnaire Only Mode
+
+**Goal**: Generate questions without creating BRD.
+
+**Mindset**: Quick mode. Capture questions for customer.
+
+### Process
+
+**Ask**:
+- Topic/feature name
+- Custom questions (user provides)
+
+**Generate**: `questionnaire-{date}.xlsx` in current directory
+
+**Output**: Excel file ready to send
+
+---
+
+## File Organization Principles
+
+**Scope-based placement**:
+
+**Project-wide** (applies to entire product):
+- Industry landscape → `brd/references.md`
+- Compliance (GDPR, PCI) → `brd/references.md`
+- Competitor companies → `brd/references.md`
+- Use cases → `brd/use-cases/{feature}/`
+
+**Feature-specific** (applies to one feature):
+- Market research → `features/{feature}/references.md`
+- Tier evidence → `features/{feature}/references.md`
+- Questionnaire → `features/{feature}/questionnaire-{date}.xlsx`
+
+**Cross-reference**: Files can link to each other
+
+---
+
+## Use Case Principles
+
+**Lean format** (80/20 rule):
+- ~30 lines max
+- Scannable in 30 seconds
+- Business focus only (no technical details)
+
+**Sequencing**:
+- Dependencies first (create before validate)
+- Logical user journey
+- No forward references
+
+**Wikilinks**: Use [[node-id]] for docs-graph traceability
+
+---
+
+## Research Principles
+
+**See**: `research.md` for full methodology.
+
+**Key principles**:
+- Comparison-first (fast feature extraction)
+- Evidence-based (multiple source types)
+- Tier validation (MVP/Standard/Advanced rules)
+- Always questionnaire (validation + open questions)
+
+---
+
+## Summary
+
+**Workflow adapts to mode**:
+- New Project: Full discovery and research
+- Add Feature: Focused research, duplicate check
+- Generate BRD: Reads existing questionnaire research
+- Process Answers: Integration and validation
+- Change Request: Impact tracking
+- Questionnaire Only: Quick question generation
+
+**Consistent principles**:
+- Business focus (WHAT and WHY)
+- Evidence-based validation
+- Lean documentation (80/20)
+- Scope-based organization
+- Customer validation (questionnaire)

package/skills/debrief/scripts/generate_questionnaire.py

@@ -10,6 +10,18 @@ questions.json format:
 {
     "project_name": "Project Name",
     "date": "2024-01-20",
+    "research": {
+        "depth": "Deep",
+        "features_count": 12,
+        "tiers": {"MVP": 5, "Standard": 4, "Advanced": 3},
+        "sources_count": 23
+    },
+    "references": {
+        "Authentication": [
+            {"type": "Comparison", "url": "https://..."},
+            {"type": "G2 Reviews", "url": "https://..."}
+        ]
+    },
     "questions": [
         {
             "category": "Requirements",
@@ -119,14 +131,24 @@ def create_questionnaire(output_path: str, questions_data: dict):
 
     # Summary sheet
     ws_summary = wb.create_sheet("Summary", 0)
+    research = questions_data.get('research', {})
+    tiers = research.get('tiers', {})
+
     summary_data = [
         ("Project Questionnaire", ""),
         ("", ""),
         ("Project:", questions_data.get('project_name', '')),
         ("Generated:", questions_data.get('date', '')),
-        ("Total Questions:", len(questions)),
         ("", ""),
-        ("Priority Breakdown:", ""),
+        ("Research Summary:", ""),
+        ("Depth:", research.get('depth', 'N/A')),
+        ("Features:", research.get('features_count', 0)),
+        ("  MVP:", tiers.get('MVP', 0)),
+        ("  Standard:", tiers.get('Standard', 0)),
+        ("  Advanced:", tiers.get('Advanced', 0)),
+        ("Sources:", research.get('sources_count', 0)),
+        ("", ""),
+        ("Questions:", len(questions)),
     ]
 
     # Count priorities
@@ -134,28 +156,8 @@ def create_questionnaire(output_path: str, questions_data: dict):
     optional_count = len(questions) - required_count
 
     summary_data.extend([
-        ("Required:", required_count),
-        ("Optional:", optional_count),
-        ("", ""),
-        ("Categories:", ""),
-    ])
-
-    # Count categories
-    categories = {}
-    for q in questions:
-        cat = q.get('category', 'General')
-        categories[cat] = categories.get(cat, 0) + 1
-
-    for cat, count in sorted(categories.items()):
-        summary_data.append((f"  {cat}:", count))
-
-    summary_data.extend([
-        ("", ""),
-        ("Instructions:", ""),
-        ("1.", "Fill in the 'Answer' column for each question"),
-        ("2.", "Required questions must be answered before proceeding"),
-        ("3.", "Context/Source shows where this question originated"),
-        ("4.", "Save and return this file when complete"),
+        ("  Required:", required_count),
+        ("  Optional:", optional_count),
     ])
 
     for row, (col1, col2) in enumerate(summary_data, 1):
@@ -169,6 +171,29 @@ def create_questionnaire(output_path: str, questions_data: dict):
     ws_summary.column_dimensions['A'].width = 25
     ws_summary.column_dimensions['B'].width = 40
 
+    # References sheet
+    references = questions_data.get('references', {})
+    if references:
+        ws_refs = wb.create_sheet("References")
+        ws_refs.cell(1, 1, "Feature").font = header_font
+        ws_refs.cell(1, 2, "Source Type").font = header_font
+        ws_refs.cell(1, 3, "URL").font = header_font
+        ws_refs.cell(1, 1).fill = header_fill
+        ws_refs.cell(1, 2).fill = header_fill
+        ws_refs.cell(1, 3).fill = header_fill
+
+        row = 2
+        for feature, sources in references.items():
+            for source in sources:
+                ws_refs.cell(row, 1, feature)
+                ws_refs.cell(row, 2, source.get('type', ''))
+                ws_refs.cell(row, 3, source.get('url', ''))
+                row += 1
+
+        ws_refs.column_dimensions['A'].width = 20
+        ws_refs.column_dimensions['B'].width = 20
+        ws_refs.column_dimensions['C'].width = 60
+
     # Save
     wb.save(output_path)
     print(f"Created: {output_path}")

package/skills/debrief/references/file-patterns.md

@@ -1,173 +0,0 @@
-# File Patterns for Codebase Discovery
-
-Patterns for lightweight scanning of existing codebases.
-
-## Frontend File Patterns
-
-### Include
-
-```
-# Vue.js
-**/*.vue
-
-# React / Next.js
-**/*.tsx
-**/*.jsx
-**/pages/**/*.ts
-**/pages/**/*.tsx
-**/app/**/page.tsx
-**/app/**/layout.tsx
-
-# Svelte
-**/*.svelte
-
-# Angular
-**/*.component.ts
-
-# General
-**/views/**/*
-**/screens/**/*
-```
-
-### Exclude
-
-```
-# Dependencies
-node_modules/**
-vendor/**
-bower_components/**
-
-# Build output
-dist/**
-build/**
-.next/**
-.nuxt/**
-.output/**
-out/**
-
-# Bundled files
-*.min.js
-*.bundle.js
-*.chunk.js
-
-# Tests
-__tests__/**
-**/*.test.*
-**/*.spec.*
-**/test/**
-**/tests/**
-
-# Config & misc
-.git/**
-coverage/**
-.cache/**
-```
-
-## Documentation Patterns
-
-Look for existing docs:
-
-```
-# Root docs
-README.md
-CLAUDE.md
-CONTRIBUTING.md
-
-# Doc folders
-docs/**/*.md
-documentation/**/*.md
-plans/**/*.md
-specifications/**/*.md
-specs/**/*.md
-.github/**/*.md
-```
-
-## Feature Inference
-
-Map file/folder names to features:
-
-| Pattern | Feature |
-|---------|---------|
-| `auth/`, `login.*`, `signin.*`, `signup.*` | Authentication |
-| `user/`, `users/`, `profile.*`, `account.*` | User Management |
-| `dashboard.*`, `dashboard/` | Dashboard |
-| `payment/`, `payments/`, `checkout.*`, `billing.*` | Payments |
-| `subscription/`, `subscriptions/`, `plans.*` | Subscriptions |
-| `settings.*`, `settings/`, `preferences.*` | Settings |
-| `admin/`, `admin.*` | Admin Panel |
-| `notification/`, `notifications/`, `alerts/` | Notifications |
-| `search.*`, `search/` | Search |
-| `cart.*`, `cart/`, `basket.*` | Shopping Cart |
-| `order/`, `orders/` | Orders |
-| `product/`, `products/`, `catalog/` | Products |
-| `message/`, `messages/`, `chat/`, `inbox/` | Messaging |
-| `report/`, `reports/`, `analytics/` | Reporting |
-| `upload/`, `files/`, `media/` | File Management |
-| `team/`, `teams/`, `organization/` | Team Management |
-| `onboarding/`, `wizard/`, `setup/` | Onboarding |
-| `help/`, `support/`, `faq/` | Help/Support |
-
-## Tech Stack Detection
-
-### Package Managers
-
-```
-# Check for these files
-package.json      → Node.js / JavaScript
-requirements.txt  → Python
-Gemfile           → Ruby
-go.mod            → Go
-Cargo.toml        → Rust
-composer.json     → PHP
-```
-
-### Framework Detection (from package.json)
-
-| Dependency | Framework |
-|------------|-----------|
-| `next` | Next.js |
-| `nuxt` | Nuxt.js |
-| `vue` | Vue.js |
-| `react` | React |
-| `@angular/core` | Angular |
-| `svelte` | Svelte |
-| `express` | Express.js |
-| `fastify` | Fastify |
-| `nestjs` | NestJS |
-
-## Folder Structure Hints
-
-```
-# Next.js App Router
-app/
-├── page.tsx          → Home page
-├── layout.tsx        → Root layout
-├── (auth)/           → Auth group
-│   ├── login/
-│   └── register/
-└── dashboard/        → Dashboard
-
-# Nuxt.js
-pages/
-├── index.vue         → Home
-├── login.vue         → Login
-└── dashboard/
-    └── index.vue     → Dashboard
-
-# Standard React
-src/
-├── pages/            → Routes
-├── components/       → UI components
-├── hooks/            → Custom hooks
-├── services/         → API calls
-└── utils/            → Helpers
-```
-
-## Scan Strategy
-
-1. **Find package.json** → Detect framework
-2. **Glob for frontend files** → List all pages/components
-3. **Group by folder** → pages/, components/, views/
-4. **Match patterns** → Infer features
-5. **Check for docs** → Read README, CLAUDE.md
-6. **Summarize** → Create feature table

package/skills/debrief/references/group-codes.md

@@ -1,72 +0,0 @@
-# Use Case Group Codes
-
-Standard codes for grouping use cases. Use these for consistency across BRDs.
-
-## Standard Codes
-
-| Code | Domain | Examples |
-|------|--------|----------|
-| **AUTH** | Authentication | Login, logout, password reset, SSO |
-| **USER** | User Management | Registration, profile, settings |
-| **PAY** | Payments | Checkout, refunds, payment methods |
-| **SUB** | Subscriptions | Plans, upgrades, cancellation |
-| **BILL** | Billing | Invoices, receipts, statements |
-| **NOTIF** | Notifications | Email, push, in-app alerts |
-| **ADMIN** | Administration | Dashboard, settings, config |
-| **RPT** | Reporting | Analytics, exports, dashboards |
-| **INTG** | Integrations | API, webhooks, third-party |
-| **SRCH** | Search | Search, filters, browse |
-| **INV** | Inventory | Stock, catalog, products |
-| **ORD** | Orders | Cart, checkout, order history |
-| **SHIP** | Shipping | Delivery, tracking, returns |
-| **MSG** | Messaging | Chat, comments, threads |
-| **FILE** | Files | Upload, storage, sharing |
-| **TEAM** | Teams | Organizations, roles, permissions |
-| **ONBD** | Onboarding | Setup, tutorials, first-run |
-| **SUPP** | Support | Help, tickets, FAQ |
-
-## Choosing Codes
-
-1. **Use existing code** if it fits
-2. **Create new code** if domain is distinct
-3. **Keep codes 3-5 characters**
-4. **Make it obvious** - anyone should guess the domain
-
-## Custom Codes
-
-For project-specific domains, define in BRD README:
-
-```markdown
-## Custom Group Codes
-
-| Code | Domain | Description |
-|------|--------|-------------|
-| PROP | Properties | Real estate listings |
-| BOOK | Bookings | Reservation system |
-```
-
-## Grouping Strategy
-
-**Group by user intent**, not by feature:
-
-Good:
-- `UC-PAY-001-checkout.md` - User paying
-- `UC-PAY-002-refund-request.md` - User requesting money back
-
-Avoid:
-- `UC-STRIPE-001-...` - Implementation detail, not user intent
-- `UC-BUTTON-001-...` - UI element, not user goal
-
-## Cross-Group Dependencies
-
-Note dependencies in use case files:
-
-```markdown
-> **Related**: [UC-AUTH-001](./UC-AUTH-001-login.md), [UC-PAY-001](./UC-PAY-001-checkout.md)
-```
-
-Common patterns:
-- AUTH → all authenticated features
-- USER → TEAM (user creates team)
-- PAY → SUB (payment enables subscription)
-- ORD → SHIP (order triggers shipping)