@codihaus/claude-skills 1.6.26 → 1.6.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.26",
+  "version": "1.6.27",
   "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.0
 ---
 
 # /debrief - Business Requirements Document
@@ -91,7 +91,13 @@ 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 JSON format).
+
+**3 sheets generated**:
 - Summary (features count, tier breakdown, research stats)
 - Questions (validation + open)
 - References (URLs, evidence per feature)
@@ -106,13 +112,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/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.
 
@@ -65,16 +69,52 @@
 
 ---
 
-### Generate Questionnaire (ALWAYS)
-
-**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
+
+**JSON format**:
+```json
+{
+  "project_name": "Project Name",
+  "date": "2026-01-25",
+  "research": {
+    "depth": "Deep",
+    "features_count": 12,
+    "tiers": {"MVP": 5, "Standard": 4, "Advanced": 3},
+    "sources_count": 23
+  },
+  "references": {
+    "Feature Name": [
+      {"type": "Comparison", "url": "https://..."},
+      {"type": "G2 Reviews", "url": "https://..."}
+    ]
+  },
+  "questions": [
+    {
+      "category": "Requirements",
+      "question": "Question text?",
+      "priority": "Required",
+      "context": "Why we're asking",
+      "source": "UC-XXX-NNN"
+    }
+  ]
+}
+```
+
+**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 +141,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 +173,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 +186,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 +219,7 @@
 
 ---
 
-### Use Case Generation
+### STEP 4: Use Case Generation (ONLY if user chose "Create BRD")
 
 **Principle**: Lean 80/20 format (~30 lines).
 
@@ -183,9 +243,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)