@codihaus/claude-skills 1.6.26 → 1.6.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.26",
+  "version": "1.6.28",
   "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 → questionnaire (default) or BRD (with --answers flag)
-version: 5.2.0
+version: 5.3.1
 ---
 
 # /debrief - Business Requirements Document
@@ -91,10 +91,21 @@ version: 5.2.0
 
 ### 4. Questionnaire = Decision Tool
 
-**3 sheets with evidence**:
+**How to generate**:
+```bash
+python .claude/skills/debrief/scripts/generate_questionnaire.py questionnaire-{YYYY-MM-DD}.xlsx -
+```
+Pipe JSON to stdin with research data (see `references/workflow.md` for full JSON format).
+
+**CRITICAL: Populate with real data**:
+- **questions array**: 2-5 questions per feature (validation + open questions)
+- **references object**: URLs by feature (comparison, reviews, ecosystems)
+- **research object**: Feature counts, tier breakdown, source counts
+
+**3 sheets generated**:
 - Summary (features count, tier breakdown, research stats)
-- Questions (validation + open)
-- References (URLs, evidence per feature)
+- Questions (validation + open questions with context)
+- References (URLs by feature, organized by source type)
 
 **Purpose**: User reviews evidence, makes decisions, validates with customer.
 
@@ -106,13 +117,24 @@ Then create BRD via `--answers` or `--generate-brd`.
 
 **See** `references/workflow.md` for detailed steps.
 
-**Modes**:
-- New Project: Research + questionnaire (no BRD)
-- Add Feature: Research + questionnaire (no BRD)
-- Process Answers (`--answers`): Create BRD from filled questionnaire
-- Generate BRD (`--generate-brd`): Create BRD from research
+**CRITICAL**: ALWAYS ask context questions FIRST using AskUserQuestion tool before doing any research.
 
-**Default**: Questionnaire only. BRD requires explicit flag.
+**Modes**:
+- **New Project**:
+  1. Ask 4 questions (Industry, Users, Constraints, Scope mode: MVP/Market Standard/Full)
+  2. Research + questionnaire → `plans/brd/use-cases/{project}/questionnaire-{date}.xlsx`
+  3. NO BRD created
+- **Add Feature**:
+  1. Ask 2 questions (Feature name, Scope mode: MVP/Market Standard/Full)
+  2. Research + questionnaire → `plans/brd/use-cases/{feature}/questionnaire-{date}.xlsx`
+  3. NO BRD created
+- **Process Answers** (`--answers`):
+  1. Read filled questionnaire
+  2. **ASK what to do**: Continue research / Ask follow-ups / Create BRD
+  3. Execute based on choice
+- **Generate BRD** (`--generate-brd`): Create BRD from research
+
+**Default**: Questionnaire only. BRD requires explicit flag AND user confirmation.
 
 ---
 

package/skills/debrief/references/research.md

@@ -185,19 +185,33 @@ Per feature, collect:
 
 ## Questionnaire Strategy
 
-**Always generate questionnaire** with:
-
-**Validation questions** (customer confirms research):
-- "We found 9/10 competitors offer {feature}. Confirm you need this?"
-- "Market shows {feature} is {tier}. Agree with priority?"
-
-**Open questions** (genuine unknowns):
-- Business rules needing clarification
-- Integration requirements
-- Constraints and limits
+**Always generate questionnaire** with **2-5 questions per feature**:
+
+**Type 1: Validation questions** (customer confirms research):
+- Category: "Validation"
+- Priority: "Required"
+- Examples:
+  - "We found 9/10 competitors offer {feature}. Do you need this?"
+  - "Market shows {feature} is {tier}. Agree with priority?"
+  - "80% of {category} tools include {feature} in free tier. Include in MVP?"
+
+**Type 2: Open questions** (genuine unknowns from research):
+- Category: "Requirements" / "Business Rules" / "Integrations" / "Constraints"
+- Priority: "Required" (blockers) or "Optional" (nice to know)
+- Examples:
+  - "What is the expected user load?" (Requirements)
+  - "Should users be able to delete their account?" (Business Rules)
+  - "Which third-party services must integrate?" (Integrations)
+  - "Are there compliance requirements (GDPR, HIPAA)?" (Constraints)
 
 **Purpose**: Customer validates assumptions + fills gaps
 
+**CRITICAL**: Every question must have:
+- Clear category
+- Priority (Required/Optional)
+- Context (why we're asking)
+- Source (which feature/UC)
+
 ---
 
 ## Common Patterns

package/skills/debrief/references/workflow.md

@@ -28,26 +28,30 @@
 
 **Mindset**: Discovery mode. Understand context, research market, validate with customer.
 
-### Context Gathering
+### STEP 1: Context Gathering (MANDATORY - DO THIS FIRST)
+
+**CRITICAL**: ALWAYS ask questions BEFORE doing any research. DO NOT skip this step.
 
 **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 4 questions** (AskUserQuestion):
-1. Industry (SaaS/E-commerce/Marketplace/etc.)
-2. Target users (B2B/B2C/Internal)
-3. Constraints (timeline/budget/compliance/integrations)
-4. **Scope tier** (Core/Standard/Full) - determines WHICH features to include
+**ALWAYS ask 4 questions** using AskUserQuestion tool:
+1. **Industry**: SaaS / E-commerce / Marketplace / etc.
+2. **Target users**: B2B / B2C / Internal
+3. **Constraints**: Timeline / Budget / Compliance / Integrations
+4. **Scope mode**: MVP / Market Standard / Full (determines WHICH features to include)
+
+**DO NOT proceed to research until user answers these questions.**
 
 **Output**: Context understanding, scope alignment
 
 ---
 
-### Market Research (ALWAYS Deep + Revalidation)
+### STEP 2: Market Research (ALWAYS Deep + Revalidation)
 
-**CRITICAL**: After scope tier chosen, ALWAYS do deep research + multi-source revalidation.
+**CRITICAL**: After user answers questions and scope tier is chosen, THEN do deep research + multi-source revalidation.
 
 **Methodology**: See `research.md` for full process.
 
@@ -63,18 +67,97 @@
 
 **Output**: Features with tier classification and multi-source evidence
 
----
-
-### Generate Questionnaire (ALWAYS)
+**CRITICAL: Collect URLs during research** for references section:
+- Comparison pages (e.g., "vs Alternative A")
+- G2/Capterra reviews
+- Chrome/WordPress/GitHub ecosystem pages
+- Reddit/forum discussions
+- Competitor feature pages
 
-**Principle**: Default output. No BRD files created yet.
+---
 
-**3 sheets**:
+### STEP 3: Generate Questionnaire (ALWAYS)
+
+**Principle**: After research is complete, generate questionnaire. No BRD files created yet.
+
+**How to generate**:
+1. Create JSON with research data (see format below)
+2. Call Python script: `python .claude/skills/debrief/scripts/generate_questionnaire.py questionnaire-{YYYY-MM-DD}.xlsx -`
+3. Pipe JSON to stdin or save as file
+
+**CRITICAL: Populate questions array with TWO types:**
+
+**Type 1: Validation questions** (confirm research findings):
+- Category: "Validation"
+- Priority: "Required"
+- Question: "We found {X}/10 competitors offer {feature}. Do you need this?"
+- Context: "Tier: {MVP/Standard/Advanced}, Evidence: {brief summary}"
+- Source: Feature name
+
+**Type 2: Open questions** (unknowns from research):
+- Category: "Requirements" / "Business Rules" / "Integrations" / "Constraints"
+- Priority: "Required" (blockers) or "Optional" (nice to know)
+- Question: Specific question needing customer input
+- Context: Why this matters / what it affects
+- Source: Feature name or "General"
+
+**Generate 2-5 questions per feature** (1-2 validation, 1-3 open questions).
+
+**JSON format**:
+```json
+{
+  "project_name": "Project Management Tool",
+  "date": "2026-01-25",
+  "research": {
+    "depth": "Deep",
+    "features_count": 12,
+    "tiers": {"MVP": 5, "Standard": 4, "Advanced": 3},
+    "sources_count": 23
+  },
+  "references": {
+    "Task Management": [
+      {"type": "Comparison", "url": "https://..."},
+      {"type": "G2 Reviews", "url": "https://..."},
+      {"type": "Chrome Extension", "url": "https://..."}
+    ],
+    "Team Collaboration": [
+      {"type": "Comparison", "url": "https://..."}
+    ]
+  },
+  "questions": [
+    {
+      "category": "Validation",
+      "question": "We found 9/10 competitors offer real-time task updates. Do you need this feature?",
+      "priority": "Required",
+      "context": "Tier: MVP, 90% competitor presence, high user demand in reviews",
+      "source": "Task Management"
+    },
+    {
+      "category": "Business Rules",
+      "question": "What is the maximum team size you expect to support?",
+      "priority": "Required",
+      "context": "Affects pricing model and infrastructure planning",
+      "source": "Team Collaboration"
+    },
+    {
+      "category": "Integrations",
+      "question": "Which third-party tools must integrate with this system?",
+      "priority": "Optional",
+      "context": "Common integrations: Slack, Google Calendar, GitHub",
+      "source": "General"
+    }
+  ]
+}
+```
+
+**3 sheets generated**:
 - **Summary**: Feature count, tier distribution, research stats
 - **Questions**: Validation + open questions
 - **References**: URLs by feature (comparison pages, reviews, ecosystems)
 
-**Output**: `questionnaire-{date}.xlsx` in current directory
+**Output location**:
+- New Project: `plans/brd/use-cases/{project-name}/questionnaire-{YYYY-MM-DD}.xlsx`
+- Add Feature: `plans/brd/use-cases/{feature-name}/questionnaire-{YYYY-MM-DD}.xlsx`
 
 **NO BRD files created**. User reviews questionnaire first.
 
@@ -101,25 +184,29 @@
 
 **Mindset**: Continuity mode. Check duplicates, maintain consistency.
 
-### Context Gathering
+### STEP 1: Context Gathering (MANDATORY - DO THIS FIRST)
+
+**CRITICAL**: ALWAYS ask questions BEFORE doing any research. DO NOT skip this step.
 
-**Ask 2 questions**:
-1. Feature name
-2. Scope tier (Core/Standard/Full)
+**ALWAYS ask 2 questions** using AskUserQuestion tool:
+1. **Feature name**: What feature to add?
+2. **Scope mode**: MVP / Market Standard / Full (determines WHICH features to include)
 
 **Duplicate check**: Read `docs-graph.json` if exists, warn if similar feature found
 
+**DO NOT proceed to research until user answers these questions.**
+
 **Output**: Feature to add, scope confirmed
 
 ---
 
-### Research & Generate Questionnaire
+### STEP 2: Research & Generate Questionnaire
 
 **Same as New Project**:
 - Market research (comparison-first, see `research.md`)
 - Generate questionnaire (validation + open questions)
 
-**Output**: `features/{feature}/questionnaire-{date}.xlsx`
+**Output**: `plans/brd/use-cases/{feature}/questionnaire-{YYYY-MM-DD}.xlsx`
 
 **NO BRD files created**. User reviews questionnaire, gets answers, then runs `--answers`.
 
@@ -129,11 +216,11 @@
 
 **Trigger**: `/debrief --answers questionnaire.xlsx`
 
-**Goal**: Create BRD from customer-answered questionnaire.
+**Goal**: Process filled questionnaire and ask what user wants to do next.
 
-**Mindset**: BRD creation mode. Customer validated research, now create structure.
+**Mindset**: Interactive mode. User decides next action based on answers.
 
-### Read Questionnaire
+### STEP 1: Read Questionnaire
 
 **Read questionnaire** (Excel file):
 - Summary sheet (features, tiers, research)
@@ -142,7 +229,23 @@
 
 ---
 
-### Feature Sequencing
+### STEP 2: Ask What To Do (MANDATORY)
+
+**CRITICAL**: ALWAYS ask what user wants to do. DO NOT auto-create BRD.
+
+**Ask using AskUserQuestion tool** - What would you like to do?
+1. **Continue research and revise summary** (do more research based on answers)
+2. **Ask follow-up questions** (generate new questionnaire with deeper questions)
+3. **Create BRD** (generate use cases and BRD files)
+
+**Based on user choice**:
+- Choice 1 → Do additional research, update questionnaire
+- Choice 2 → Generate new questionnaire with follow-up questions
+- Choice 3 → Proceed to Feature Sequencing (below)
+
+---
+
+### STEP 3: Feature Sequencing (ONLY if user chose "Create BRD")
 
 **Principle**: Order by dependencies within each tier.
 
@@ -159,7 +262,7 @@
 
 ---
 
-### Use Case Generation
+### STEP 4: Use Case Generation (ONLY if user chose "Create BRD")
 
 **Principle**: Lean 80/20 format (~30 lines).
 
@@ -183,9 +286,9 @@
 
 ---
 
-### BRD Structure Creation
+### STEP 5: BRD Structure Creation (ONLY if user chose "Create BRD")
 
-**Create project-wide** (`brd/`):
+**Create project-wide** (`plans/brd/`):
 - README.md (all features index)
 - context.md (stakeholders, users, constraints)
 - references.md (industry, compliance, competitor overview)