@codihaus/claude-skills 1.6.27 → 1.6.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.27",
+  "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.3.0
+version: 5.3.1
 ---
 
 # /debrief - Business Requirements Document
@@ -95,12 +95,17 @@ version: 5.3.0
 ```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).
+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.
 

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

@@ -67,6 +67,13 @@
 
 **Output**: Features with tier classification and multi-source evidence
 
+**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
+
 ---
 
 ### STEP 3: Generate Questionnaire (ALWAYS)
@@ -78,10 +85,28 @@
 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 Name",
+  "project_name": "Project Management Tool",
   "date": "2026-01-25",
   "research": {
     "depth": "Deep",
@@ -90,18 +115,36 @@
     "sources_count": 23
   },
   "references": {
-    "Feature Name": [
+    "Task Management": [
       {"type": "Comparison", "url": "https://..."},
-      {"type": "G2 Reviews", "url": "https://..."}
+      {"type": "G2 Reviews", "url": "https://..."},
+      {"type": "Chrome Extension", "url": "https://..."}
+    ],
+    "Team Collaboration": [
+      {"type": "Comparison", "url": "https://..."}
     ]
   },
   "questions": [
     {
-      "category": "Requirements",
-      "question": "Question text?",
+      "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": "Why we're asking",
-      "source": "UC-XXX-NNN"
+      "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"
     }
   ]
 }