@codihaus/claude-skills 1.6.22 → 1.6.24

package/package.json

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

package/skills/debrief/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: debrief
 description: Customer requirements → market-validated BRD with tiered features
-version: 4.0.0
+version: 4.2.0
 ---
 
 # /debrief - Business Requirements Document
@@ -24,10 +24,11 @@ version: 4.0.0
 ## Usage
 
 ```bash
-/debrief "Customer wants..."           # New project
-/debrief "Add {feature}"               # Add feature
-/debrief --answers questionnaire.xlsx  # Process answers
-/debrief --questionnaire-only          # Questions only
+/debrief "Customer wants..."                # New project
+/debrief "Add {feature}"                    # Add feature
+/debrief --answers questionnaire.xlsx       # Process answers
+/debrief --generate-brd questionnaire.xlsx  # Generate BRD from existing research
+/debrief --questionnaire-only               # Questions only
 ```
 
 ---
@@ -50,51 +51,49 @@ version: 4.0.0
 
 ## Key Principles
 
-### 1. Comparison-First Discovery
+### 1. Default Output: Questionnaire Only
 
-**Don't** scan competitors one-by-one.
-**Do** use comparison/alternative pages first:
-- `"{category} comparison"` → feature matrices from 10+ competitors
-- `"best {category} alternatives"` → what features matter
-- `"{competitor A} vs {competitor B}"` → deal-breaker features
+**ALWAYS output**: Summary + Questionnaire (3 sheets Excel)
+**NEVER auto-create**: BRD files, use cases, feature folders
 
-Then deep revalidation per feature (ecosystem, user signals).
+**BRD creation only via**:
+- `--answers questionnaire.xlsx` (after customer fills it)
+- `--generate-brd questionnaire.xlsx` (from existing research)
 
-### 2. Always Generate Questionnaire
+**Why**: User reviews research first, validates with customer, then creates BRD.
 
-Include both:
-- **Validation questions**: "We found 9/10 competitors offer SSO. Confirm this is needed?"
-- **Open questions**: "What's max team size per account?"
+### 2. Business Focus ONLY
 
-Customer validates assumptions + fills gaps.
+**Do**:
+- WHAT features users need (login, checkout, reports)
+- WHY they need it (business value, user goal)
+- WHEN it's needed (MVP, Standard, Advanced)
 
-### 3. Scope-Based Organization
+**Never do**:
+- HOW to code it (files, functions, APIs)
+- WHICH technology (React, Vue, database)
+- WHERE to put code (components, services)
 
-**Project-wide** (brd/references.md):
-- Industry landscape
-- Compliance (GDPR, PCI)
-- Competitor company profiles
+**This is NOT dev-specs**. Stay business level. No technical suggestions.
 
-**Feature-specific** (features/{name}/references.md):
-- Market research for THIS feature
-- Tier validation evidence (MVP/Standard/Advanced)
-- Sequenced features with dependencies
+**If you mention files, code, APIs, or tech → YOU ARE DOING IT WRONG.**
 
-### 4. Lean Use Cases (80/20)
+### 3. Comparison-First Research
 
-**Include (20%)**:
-- Story (1 line)
-- Critical acceptance criteria (3-5 bullets)
-- Key business rules (constraints, limits)
-- Open questions
+Use comparison pages first (5-10 competitors in one page):
+- `"{category} comparison"`
+- `"best {category} alternatives"`
 
-**Defer to /dev-specs (80%)**:
-- Detailed flows
-- Integration points
-- Edge cases
-- UI/UX details
+Then validate per feature (Quick or Deep).
 
-Keep use cases ~30 lines max. Business stakeholders scan in 30 seconds.
+### 4. Questionnaire = Research Output
+
+**3 sheets**:
+- Summary (stats, tiers)
+- Questions (validation + open)
+- References (URLs)
+
+Customer reviews, answers, returns file. Then create BRD via `--answers`.
 
 ---
 
@@ -106,6 +105,7 @@ Keep use cases ~30 lines max. Business stakeholders scan in 30 seconds.
 - No `plans/brd/` → New Project
 - `plans/brd/` exists → Add Feature
 - `--answers {file}` → Process Answers
+- `--generate-brd {file}` → Generate BRD from research
 - `--questionnaire-only` → Questions Only
 
 ---

package/skills/debrief/references/workflow.md

@@ -14,6 +14,7 @@
 
 **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
@@ -31,12 +32,18 @@
 
 ### Context Gathering
 
-**Ask 5 questions** (AskUserQuestion):
+**Check for existing questionnaire**:
+- If found: Ask "Found existing research. Use it or start fresh?"
+  - Reuse → Switch to Generate BRD mode
+  - Fresh → Continue with new research
+
+**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)
 
@@ -48,15 +55,15 @@
 
 **Methodology**: See `research.md` for full process.
 
-**Comparison-first**:
+**Quick** (5 min):
 - Find 2-3 comparison/alternative pages
 - Extract feature matrix
 - Initial tier hypothesis
 
-**Deep validation**:
-- Per feature: cross-validate with ecosystem + user signals
-- Classify tier (MVP/Standard/Advanced)
-- Collect evidence
+**Deep** (15-20 min):
+- Comparison pages (initial)
+- Cross-validate with ecosystem + user signals
+- Full tier classification with evidence
 
 **Output**: Features with tier classification and evidence
 
@@ -117,34 +124,34 @@
 
 ---
 
-### Questionnaire
+### Generate Questionnaire (ALWAYS)
 
-**Principle**: Always generate. Validate assumptions + fill gaps.
+**Principle**: Default output. No BRD files created yet.
 
-**Include**:
-- **Validation questions**: "We found 9/10 competitors offer SSO. Confirm?"
-- **Open questions**: "What's max team size per account?"
+**3 sheets**:
+- **Summary**: Feature count, tier distribution, research stats
+- **Questions**: Validation + open questions
+- **References**: URLs by feature (comparison pages, reviews, ecosystems)
 
-**Categories**: Validation, Business, Requirements, Constraints, Integration
+**Output**: `questionnaire-{date}.xlsx` in current directory
 
-**Output**: `features/{feature}/questionnaire-{date}.xlsx`
+**NO BRD files created**. User reviews questionnaire first.
 
 ---
 
-### Summary
+### Summary Output
 
 **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
+- Questionnaire location: `questionnaire-{date}.xlsx`
+- Question count (validation + open)
 
 **Next steps**:
-- Review BRD with stakeholders
-- Send questionnaire to customer
-- Process with `/debrief --answers {path}`
-- Then `/dev-specs {feature}` for implementation
+1. Review questionnaire
+2. Send to customer for answers
+3. After answers: `/debrief --answers questionnaire-{date}.xlsx`
+4. BRD will be created from answers
 
 ---
 
@@ -156,9 +163,10 @@
 
 ### Context Gathering
 
-**Ask 2 questions**:
+**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
 
@@ -166,49 +174,46 @@
 
 ---
 
-### Research & Document
+### Research & Generate Questionnaire
 
 **Same as New Project**:
 - Market research (comparison-first, see `research.md`)
-- Feature sequencing (dependencies)
-- Lean use cases (templates/use-case.md)
+- Generate questionnaire (validation + open questions)
 
-**Update**:
-- `brd/README.md` (add to index)
-- `brd/changelog.md` (log addition)
-- Create `features/{feature}/` folder
-
-**Questionnaire**: Always generate (validation + open questions)
+**Output**: `features/{feature}/questionnaire-{date}.xlsx`
 
-**Output**: Feature added to BRD with research and questionnaire
+**NO BRD files created**. User reviews questionnaire, gets answers, then runs `--answers`.
 
 ---
 
 ## Process Answers Mode
 
-**Goal**: Update BRD with customer responses.
+**Goal**: Create BRD from customer-answered questionnaire.
 
-**Mindset**: Integration mode. Incorporate feedback, resolve gaps.
+**Mindset**: BRD creation mode. Customer validated research, now create structure.
 
 ### Process
 
 **Read questionnaire** (Excel file):
-- Extract answers from "Answer" column
-- Match to source use cases via "Context/Source"
+- Summary sheet (features, tiers, research)
+- Questions sheet (customer answers)
+- References sheet (source URLs)
 
-**Update use cases**:
-- Remove questions from "Open Questions" section
-- Add answers to relevant sections (Acceptance Criteria, Business Rules)
+**Create BRD structure**:
+- `brd/` files (README, context, references, changelog)
+- `features/{feature}/` folders
+- Use cases (lean format, sequenced)
 
-**Update feature README**:
-- Log questionnaire as processed
-- Track history
+**Incorporate answers**:
+- Update use cases with customer answers
+- Remove questions that were answered
+- Keep unanswered questions in "Open Questions"
 
 **Check completeness**:
-- If gaps remain → generate new questionnaire (new date)
-- If complete → update UC status to "Confirmed"
+- If gaps remain → note in use cases
+- If complete → mark UC status "Confirmed"
 
-**Output**: Updated use cases, questionnaire history, completion status
+**Output**: Full BRD structure + use cases
 
 ---
 
@@ -233,6 +238,32 @@
 
 ---
 
+## Generate BRD Mode
+
+**Goal**: Generate full BRD from existing questionnaire research.
+
+**Mindset**: Resumption mode. User reviewed Summary + Questionnaire, ready for full BRD.
+
+### Process
+
+**Check questionnaire validity**:
+- Ask: "Found existing research in questionnaire. Use it or start fresh?"
+  - Reuse (generate from questionnaire)
+  - Fresh (ignore questionnaire, do new research)
+
+**If reuse**:
+- Read Summary sheet (features, tiers, research stats)
+- Read References sheet (source URLs)
+- Generate BRD structure (no re-research)
+
+**If fresh**:
+- Ignore questionnaire
+- Run full research flow (New Project or Add Feature mode)
+
+**Output**: BRD files + feature folders
+
+---
+
 ## Questionnaire Only Mode
 
 **Goal**: Generate questions without creating BRD.
@@ -303,6 +334,7 @@
 **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

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}")