@codihaus/claude-skills 1.6.23 → 1.6.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.23",
+  "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.1.0
+version: 4.2.0
 ---
 
 # /debrief - Business Requirements Document
@@ -51,51 +51,49 @@ version: 4.1.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`.
 
 ---
 

package/skills/debrief/references/workflow.md

@@ -32,6 +32,11 @@
 
 ### Context Gathering
 
+**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.)
@@ -60,10 +65,6 @@
 - 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
 
 ---
@@ -123,33 +124,34 @@
 
 ---
 
-### Questionnaire
+### Generate Questionnaire (ALWAYS)
 
-**Principle**: Always generate. Validate assumptions + fill gaps.
+**Principle**: Default output. No BRD files created yet.
 
 **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)
+**Output**: `questionnaire-{date}.xlsx` in current directory
+
+**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
 
 ---
 
@@ -172,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)
-
-**Update**:
-- `brd/README.md` (add to index)
-- `brd/changelog.md` (log addition)
-- Create `features/{feature}/` folder
+- Generate questionnaire (validation + open questions)
 
-**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
 
 ---
 
@@ -247,11 +246,19 @@
 
 ### Process
 
-**Read questionnaire**:
-- Summary sheet (features, tiers, research stats)
-- References sheet (source URLs)
+**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)
 
-**Generate**: Full BRD structure from existing research (no re-research)
+**If fresh**:
+- Ignore questionnaire
+- Run full research flow (New Project or Add Feature mode)
 
 **Output**: BRD files + feature folders