@codihaus/claude-skills 1.6.21 → 1.6.22

package/skills/debrief/references/workflow.md

@@ -0,0 +1,315 @@
+# Workflow Principles
+
+**Mindset**: Business analyst. Focus on WHAT and WHY, defer HOW to /dev-specs.
+
+**Methodology**: Mode detection → Context gathering → Research → Document → Questionnaire
+
+**Expected Outcome**: Market-validated BRD with tiered features, lean use cases, customer questionnaire.
+
+---
+
+## Mode Detection
+
+**Principle**: Behavior changes based on context.
+
+**Detection**:
+- `--answers {file}` → Process Answers mode
+- `--questionnaire-only` → Questionnaire Only mode
+- No `plans/brd/` → New Project mode
+- `plans/brd/` exists → Add Feature mode
+- Modifying confirmed UC → Change Request mode
+
+**Action**: Execute appropriate workflow for detected mode.
+
+---
+
+## New Project Mode
+
+**Goal**: Create initial BRD with market-validated features.
+
+**Mindset**: Discovery mode. Understand context, research market, validate with customer.
+
+### Context Gathering
+
+**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)
+
+**If existing codebase**: Scan for docs + features (Glob, Read)
+
+**Output**: Context understanding, scope alignment
+
+---
+
+### Market Research
+
+**Methodology**: See `research.md` for full process.
+
+**Comparison-first**:
+- Find 2-3 comparison/alternative pages
+- Extract feature matrix
+- Initial tier hypothesis
+
+**Deep validation**:
+- Per feature: cross-validate with ecosystem + user signals
+- Classify tier (MVP/Standard/Advanced)
+- Collect 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)
+
+**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.
+
+**Include**:
+- **Validation questions**: "We found 9/10 competitors offer SSO. Confirm?"
+- **Open questions**: "What's max team size per account?"
+
+**Categories**: Validation, Business, Requirements, Constraints, Integration
+
+**Output**: `features/{feature}/questionnaire-{date}.xlsx`
+
+---
+
+### Summary
+
+**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
+
+**Next steps**:
+- Review BRD with stakeholders
+- Send questionnaire to customer
+- Process with `/debrief --answers {path}`
+- Then `/dev-specs {feature}` for implementation
+
+---
+
+## Add Feature Mode
+
+**Goal**: Extend existing BRD with new feature.
+
+**Mindset**: Continuity mode. Check duplicates, maintain consistency.
+
+### Context Gathering
+
+**Ask 2 questions**:
+1. Feature name
+2. Scope tier (Core/Standard/Full)
+
+**Duplicate check**: Read `docs-graph.json` if exists, warn if similar feature found
+
+**Output**: Feature to add, scope confirmed
+
+---
+
+### Research & Document
+
+**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
+
+**Questionnaire**: Always generate (validation + open questions)
+
+**Output**: Feature added to BRD with research and questionnaire
+
+---
+
+## Process Answers Mode
+
+**Goal**: Update BRD with customer responses.
+
+**Mindset**: Integration mode. Incorporate feedback, resolve gaps.
+
+### Process
+
+**Read questionnaire** (Excel file):
+- Extract answers from "Answer" column
+- Match to source use cases via "Context/Source"
+
+**Update use cases**:
+- Remove questions from "Open Questions" section
+- Add answers to relevant sections (Acceptance Criteria, Business Rules)
+
+**Update feature README**:
+- Log questionnaire as processed
+- Track history
+
+**Check completeness**:
+- If gaps remain → generate new questionnaire (new date)
+- If complete → update UC status to "Confirmed"
+
+**Output**: Updated use cases, questionnaire history, completion status
+
+---
+
+## Change Request Mode
+
+**Goal**: Track modifications to confirmed BRD.
+
+**Mindset**: Traceability mode. Document change rationale and impact.
+
+### Process
+
+**Create CR** (`brd/changes/CR-{NNN}-{slug}.md`):
+- Change description
+- Reason for change
+- Impact analysis (affected UCs)
+
+**If gaps introduced**: Generate questionnaire at `brd/changes/CR-{NNN}-questionnaire-{date}.xlsx`
+
+**Update**: Affected use cases, references, changelog
+
+**Output**: CR document with impact analysis
+
+---
+
+## Questionnaire Only Mode
+
+**Goal**: Generate questions without creating BRD.
+
+**Mindset**: Quick mode. Capture questions for customer.
+
+### Process
+
+**Ask**:
+- Topic/feature name
+- Custom questions (user provides)
+
+**Generate**: `questionnaire-{date}.xlsx` in current directory
+
+**Output**: Excel file ready to send
+
+---
+
+## File Organization Principles
+
+**Scope-based placement**:
+
+**Project-wide** (applies to entire product):
+- Industry landscape → `brd/references.md`
+- Compliance (GDPR, PCI) → `brd/references.md`
+- Competitor companies → `brd/references.md`
+- Use cases → `brd/use-cases/{feature}/`
+
+**Feature-specific** (applies to one feature):
+- Market research → `features/{feature}/references.md`
+- Tier evidence → `features/{feature}/references.md`
+- Questionnaire → `features/{feature}/questionnaire-{date}.xlsx`
+
+**Cross-reference**: Files can link to each other
+
+---
+
+## Use Case Principles
+
+**Lean format** (80/20 rule):
+- ~30 lines max
+- Scannable in 30 seconds
+- Business focus only (no technical details)
+
+**Sequencing**:
+- Dependencies first (create before validate)
+- Logical user journey
+- No forward references
+
+**Wikilinks**: Use [[node-id]] for docs-graph traceability
+
+---
+
+## Research Principles
+
+**See**: `research.md` for full methodology.
+
+**Key principles**:
+- Comparison-first (fast feature extraction)
+- Evidence-based (multiple source types)
+- Tier validation (MVP/Standard/Advanced rules)
+- Always questionnaire (validation + open questions)
+
+---
+
+## Summary
+
+**Workflow adapts to mode**:
+- New Project: Full discovery and research
+- Add Feature: Focused research, duplicate check
+- Process Answers: Integration and validation
+- Change Request: Impact tracking
+- Questionnaire Only: Quick question generation
+
+**Consistent principles**:
+- Business focus (WHAT and WHY)
+- Evidence-based validation
+- Lean documentation (80/20)
+- Scope-based organization
+- Customer validation (questionnaire)

package/skills/debrief/references/file-patterns.md

@@ -1,173 +0,0 @@
-# File Patterns for Codebase Discovery
-
-Patterns for lightweight scanning of existing codebases.
-
-## Frontend File Patterns
-
-### Include
-
-```
-# Vue.js
-**/*.vue
-
-# React / Next.js
-**/*.tsx
-**/*.jsx
-**/pages/**/*.ts
-**/pages/**/*.tsx
-**/app/**/page.tsx
-**/app/**/layout.tsx
-
-# Svelte
-**/*.svelte
-
-# Angular
-**/*.component.ts
-
-# General
-**/views/**/*
-**/screens/**/*
-```
-
-### Exclude
-
-```
-# Dependencies
-node_modules/**
-vendor/**
-bower_components/**
-
-# Build output
-dist/**
-build/**
-.next/**
-.nuxt/**
-.output/**
-out/**
-
-# Bundled files
-*.min.js
-*.bundle.js
-*.chunk.js
-
-# Tests
-__tests__/**
-**/*.test.*
-**/*.spec.*
-**/test/**
-**/tests/**
-
-# Config & misc
-.git/**
-coverage/**
-.cache/**
-```
-
-## Documentation Patterns
-
-Look for existing docs:
-
-```
-# Root docs
-README.md
-CLAUDE.md
-CONTRIBUTING.md
-
-# Doc folders
-docs/**/*.md
-documentation/**/*.md
-plans/**/*.md
-specifications/**/*.md
-specs/**/*.md
-.github/**/*.md
-```
-
-## Feature Inference
-
-Map file/folder names to features:
-
-| Pattern | Feature |
-|---------|---------|
-| `auth/`, `login.*`, `signin.*`, `signup.*` | Authentication |
-| `user/`, `users/`, `profile.*`, `account.*` | User Management |
-| `dashboard.*`, `dashboard/` | Dashboard |
-| `payment/`, `payments/`, `checkout.*`, `billing.*` | Payments |
-| `subscription/`, `subscriptions/`, `plans.*` | Subscriptions |
-| `settings.*`, `settings/`, `preferences.*` | Settings |
-| `admin/`, `admin.*` | Admin Panel |
-| `notification/`, `notifications/`, `alerts/` | Notifications |
-| `search.*`, `search/` | Search |
-| `cart.*`, `cart/`, `basket.*` | Shopping Cart |
-| `order/`, `orders/` | Orders |
-| `product/`, `products/`, `catalog/` | Products |
-| `message/`, `messages/`, `chat/`, `inbox/` | Messaging |
-| `report/`, `reports/`, `analytics/` | Reporting |
-| `upload/`, `files/`, `media/` | File Management |
-| `team/`, `teams/`, `organization/` | Team Management |
-| `onboarding/`, `wizard/`, `setup/` | Onboarding |
-| `help/`, `support/`, `faq/` | Help/Support |
-
-## Tech Stack Detection
-
-### Package Managers
-
-```
-# Check for these files
-package.json      → Node.js / JavaScript
-requirements.txt  → Python
-Gemfile           → Ruby
-go.mod            → Go
-Cargo.toml        → Rust
-composer.json     → PHP
-```
-
-### Framework Detection (from package.json)
-
-| Dependency | Framework |
-|------------|-----------|
-| `next` | Next.js |
-| `nuxt` | Nuxt.js |
-| `vue` | Vue.js |
-| `react` | React |
-| `@angular/core` | Angular |
-| `svelte` | Svelte |
-| `express` | Express.js |
-| `fastify` | Fastify |
-| `nestjs` | NestJS |
-
-## Folder Structure Hints
-
-```
-# Next.js App Router
-app/
-├── page.tsx          → Home page
-├── layout.tsx        → Root layout
-├── (auth)/           → Auth group
-│   ├── login/
-│   └── register/
-└── dashboard/        → Dashboard
-
-# Nuxt.js
-pages/
-├── index.vue         → Home
-├── login.vue         → Login
-└── dashboard/
-    └── index.vue     → Dashboard
-
-# Standard React
-src/
-├── pages/            → Routes
-├── components/       → UI components
-├── hooks/            → Custom hooks
-├── services/         → API calls
-└── utils/            → Helpers
-```
-
-## Scan Strategy
-
-1. **Find package.json** → Detect framework
-2. **Glob for frontend files** → List all pages/components
-3. **Group by folder** → pages/, components/, views/
-4. **Match patterns** → Infer features
-5. **Check for docs** → Read README, CLAUDE.md
-6. **Summarize** → Create feature table

package/skills/debrief/references/group-codes.md

@@ -1,72 +0,0 @@
-# Use Case Group Codes
-
-Standard codes for grouping use cases. Use these for consistency across BRDs.
-
-## Standard Codes
-
-| Code | Domain | Examples |
-|------|--------|----------|
-| **AUTH** | Authentication | Login, logout, password reset, SSO |
-| **USER** | User Management | Registration, profile, settings |
-| **PAY** | Payments | Checkout, refunds, payment methods |
-| **SUB** | Subscriptions | Plans, upgrades, cancellation |
-| **BILL** | Billing | Invoices, receipts, statements |
-| **NOTIF** | Notifications | Email, push, in-app alerts |
-| **ADMIN** | Administration | Dashboard, settings, config |
-| **RPT** | Reporting | Analytics, exports, dashboards |
-| **INTG** | Integrations | API, webhooks, third-party |
-| **SRCH** | Search | Search, filters, browse |
-| **INV** | Inventory | Stock, catalog, products |
-| **ORD** | Orders | Cart, checkout, order history |
-| **SHIP** | Shipping | Delivery, tracking, returns |
-| **MSG** | Messaging | Chat, comments, threads |
-| **FILE** | Files | Upload, storage, sharing |
-| **TEAM** | Teams | Organizations, roles, permissions |
-| **ONBD** | Onboarding | Setup, tutorials, first-run |
-| **SUPP** | Support | Help, tickets, FAQ |
-
-## Choosing Codes
-
-1. **Use existing code** if it fits
-2. **Create new code** if domain is distinct
-3. **Keep codes 3-5 characters**
-4. **Make it obvious** - anyone should guess the domain
-
-## Custom Codes
-
-For project-specific domains, define in BRD README:
-
-```markdown
-## Custom Group Codes
-
-| Code | Domain | Description |
-|------|--------|-------------|
-| PROP | Properties | Real estate listings |
-| BOOK | Bookings | Reservation system |
-```
-
-## Grouping Strategy
-
-**Group by user intent**, not by feature:
-
-Good:
-- `UC-PAY-001-checkout.md` - User paying
-- `UC-PAY-002-refund-request.md` - User requesting money back
-
-Avoid:
-- `UC-STRIPE-001-...` - Implementation detail, not user intent
-- `UC-BUTTON-001-...` - UI element, not user goal
-
-## Cross-Group Dependencies
-
-Note dependencies in use case files:
-
-```markdown
-> **Related**: [UC-AUTH-001](./UC-AUTH-001-login.md), [UC-PAY-001](./UC-PAY-001-checkout.md)
-```
-
-Common patterns:
-- AUTH → all authenticated features
-- USER → TEAM (user creates team)
-- PAY → SUB (payment enables subscription)
-- ORD → SHIP (order triggers shipping)

package/skills/debrief/references/research-queries.md

@@ -1,106 +0,0 @@
-# Research Query Templates
-
-Use these to gather **references for engineers**, not to prescribe solutions.
-
-## Goal
-
-Populate `references.md` with:
-- Official documentation links
-- Industry examples
-- Implementation case studies
-- Compliance/standards resources
-
-## Query Templates
-
-### Documentation
-```
-"{feature} official documentation"
-"{service} API documentation"
-"{feature} developer guide"
-"{service} SDK documentation"
-```
-
-### Industry Examples
-```
-"how {company} implements {feature}"
-"{feature} case study"
-"{industry} {feature} examples"
-"best {feature} implementations"
-```
-
-### User Flows
-```
-"{feature} user flow examples"
-"{feature} UX patterns"
-"{feature} wireframe examples"
-```
-
-### Compliance & Standards
-```
-"{feature} {regulation} compliance"
-"{feature} security requirements"
-"{industry} {feature} standards"
-"GDPR {feature} requirements"
-"PCI DSS {feature}"
-```
-
-### Open Source / Tutorials
-```
-"{feature} open source implementation"
-"{feature} tutorial github"
-"building {feature} from scratch"
-```
-
-## By Domain
-
-### SaaS / B2B
-```
-"enterprise {feature} requirements"
-"B2B SaaS {feature} examples"
-"{feature} multi-tenant considerations"
-```
-
-### E-commerce
-```
-"{feature} e-commerce best practices"
-"shopify {feature} documentation"
-"stripe {feature} guide"
-```
-
-### Marketplace
-```
-"two-sided marketplace {feature}"
-"platform {feature} patterns"
-```
-
-## Search Strategy
-
-1. **Start broad**: "{feature} documentation"
-2. **Get specific**: "{service} {feature} API"
-3. **Find examples**: "how {leader} does {feature}"
-4. **Check compliance**: "{feature} {regulation}"
-5. **Gather tutorials**: "{feature} implementation guide"
-
-## What to Capture
-
-For each useful result, note:
-- **Title**: Page/article title
-- **URL**: Direct link
-- **Why relevant**: 1-line note for engineers
-- **Applies to**: Which use cases benefit
-
-## Example Output
-
-```markdown
-## Documentation
-| Topic | Link | Notes |
-|-------|------|-------|
-| Stripe Billing | [Stripe Subscriptions](https://stripe.com/docs/billing) | Core billing API |
-| Usage metering | [Stripe Usage Records](https://stripe.com/docs/billing/subscriptions/usage-based) | For usage-based billing |
-
-## Industry Examples
-| Company | Link | What to Learn |
-|---------|------|---------------|
-| Notion | [How Notion Prices](https://www.notion.so/pricing) | Freemium + team pricing |
-| Slack | [Slack Billing](https://slack.com/pricing) | Per-seat model |
-```