@codihaus/claude-skills 1.6.23 → 1.6.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.23",
+  "version": "1.6.25",
   "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: 5.0.0
 ---
 
 # /debrief - Business Requirements Document
@@ -51,51 +51,53 @@ 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. Deep Research (Always)
 
-**Include (20%)**:
-- Story (1 line)
-- Critical acceptance criteria (3-5 bullets)
-- Key business rules (constraints, limits)
-- Open questions
+**Always thorough**:
+- Comparison pages (feature matrix)
+- Ecosystems (Chrome, WordPress, GitHub)
+- User signals (Reddit, reviews, forums)
+- Full evidence per feature
 
-**Defer to /dev-specs (80%)**:
-- Detailed flows
-- Integration points
-- Edge cases
-- UI/UX details
+No quick mode. Always deep.
 
-Keep use cases ~30 lines max. Business stakeholders scan in 30 seconds.
+### 4. Questionnaire = Decision Tool
+
+**3 sheets with evidence**:
+- Summary (features count, tier breakdown, research stats)
+- Questions (validation + open)
+- References (URLs, evidence per feature)
+
+**Purpose**: User reviews evidence, makes decisions, validates with customer.
+
+Then create BRD via `--answers` or `--generate-brd`.
 
 ---
 
@@ -112,11 +114,11 @@ Keep use cases ~30 lines max. Business stakeholders scan in 30 seconds.
 
 ---
 
-## Market Research
+## Market Research (Always Deep)
 
-**See** `references/market-research-methodology.md`.
+**See** `references/research.md`.
 
-**Sources**: Competitors, ecosystems (Chrome, WordPress, GitHub, etc.), user signals (Reddit, reviews).
+**Always deep**: Comparison + ecosystems + user signals + full evidence.
 
 **Tiers**:
 - **MVP**: 80%+ competitors, free tier, high demand

package/skills/debrief/references/workflow.md

@@ -2,9 +2,9 @@
 
 **Mindset**: Business analyst. Focus on WHAT and WHY, defer HOW to /dev-specs.
 
-**Methodology**: Mode detection → Context gathering → Research → Document → Questionnaire
+**Methodology**: Mode detection → Context gathering → Research (deep) → Questionnaire
 
-**Expected Outcome**: Market-validated BRD with tiered features, lean use cases, customer questionnaire.
+**Expected Outcome**: Questionnaire with deep research evidence (Summary + Questions + References).
 
 ---
 
@@ -32,13 +32,17 @@
 
 ### Context Gathering
 
-**Ask 6 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 5 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)
 
@@ -46,110 +50,48 @@
 
 ---
 
-### Market Research
+### Market Research (Always Deep)
 
 **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)
+**Deep research** (always):
+1. Comparison pages (feature matrix extraction)
+2. Ecosystems (Chrome, WordPress, GitHub, etc.)
+3. User signals (Reddit, reviews, forums)
+4. Full tier classification with evidence
 
 **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)
+### Generate Questionnaire (ALWAYS)
 
-**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.
+**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
 
 ---
 
@@ -161,10 +103,9 @@
 
 ### Context Gathering
 
-**Ask 3 questions**:
+**Ask 2 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
 
@@ -172,49 +113,94 @@
 
 ---
 
-### 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
+**Output**: `features/{feature}/questionnaire-{date}.xlsx`
 
-**Questionnaire**: Always generate (validation + open questions)
-
-**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
 
 **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)
+
+---
+
+### 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).
 
-**Update use cases**:
-- Remove questions from "Open Questions" section
-- Add answers to relevant sections (Acceptance Criteria, Business Rules)
+**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`
+
+**Incorporate customer answers**:
+- Update use cases with answers from questionnaire
+- Remove answered questions from "Open Questions"
+- Keep unanswered questions
+
+**Output**: Lean use cases in `brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
 
-**Update feature README**:
-- Log questionnaire as processed
-- Track history
+---
+
+### BRD Structure Creation
+
+**Create project-wide** (`brd/`):
+- README.md (all features index)
+- context.md (stakeholders, users, constraints)
+- references.md (industry, compliance, competitor overview)
+- changelog.md
+
+**Create feature-specific** (`features/{feature}/`):
+- README.md (feature overview)
+- references.md (market research, tier evidence from questionnaire)
+- Move questionnaire here if not already
+
+**Templates**: `templates/brd-references.md`, `templates/feature-references.md`
 
 **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 +233,21 @@
 
 ### Process
 
-**Read questionnaire**:
-- Summary sheet (features, tiers, research stats)
-- References sheet (source URLs)
-
-**Generate**: Full BRD structure from existing research (no re-research)
+**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**:
+- Execute same process as Process Answers mode
+- Read questionnaire sheets
+- Sequence features
+- Generate use cases
+- Create BRD structure
+
+**If fresh**:
+- Ignore questionnaire
+- Run full research flow (New Project or Add Feature mode)
 
 **Output**: BRD files + feature folders