wicked-garden 12.27.0

package/skills/product/requirements-analysis/refs/requirements-output-format-template.md

@@ -0,0 +1,247 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Requirements Output Format: Templates
+
+Standard format template and minimal format for documenting requirements analysis results.
+
+## Overview
+
+This document defines the expected output structure when conducting requirements analysis. The format ensures:
+- Consistency across projects
+- Complete traceability
+- Clear handoff to design and QE
+- Integration with native tasks (TaskCreate/TaskUpdate) and wicked-brain:memory
+
+## Standard Output Structure
+
+```markdown
+# Requirements Analysis: {Project/Feature Name}
+
+**Date**: {YYYY-MM-DD}
+**Analyzed By**: {Name/Role}
+**Stakeholders**: {Comma-separated list}
+**Status**: {Draft/Review/Approved}
+
+## Executive Summary
+
+{2-3 sentence overview of what is being built and why}
+
+## Context
+
+### Business Goals
+- {Goal 1}
+- {Goal 2}
+
+### User Needs
+- {Need 1}
+- {Need 2}
+
+### Constraints
+- {Constraint 1: technical, timeline, budget, etc.}
+- {Constraint 2}
+
+## Personas
+
+### {Persona 1 Name}
+- **Role**: {Title/Description}
+- **Goals**: {What they want to achieve}
+- **Pain Points**: {Current problems}
+- **Technical Proficiency**: {Low/Medium/High}
+
+### {Persona 2 Name}
+- **Role**: {Title/Description}
+- **Goals**: {What they want to achieve}
+- **Pain Points**: {Current problems}
+- **Technical Proficiency**: {Low/Medium/High}
+
+## User Stories
+
+### US-{ID}: {Story Title}
+
+**As a** {persona}
+**I want** {capability}
+**So that** {benefit}
+
+**Priority**: {P0/P1/P2/P3}
+**Complexity**: {S/M/L/XL}
+
+**Acceptance Criteria**:
+1. Given {context}, When {action}, Then {outcome}
+2. Given {error condition}, When {action}, Then {error handling}
+3. Given {edge case}, When {action}, Then {graceful behavior}
+
+**Dependencies**: {List of dependencies}
+**Assumptions**: {List of assumptions}
+**Open Questions**: {List of questions}
+
+{Repeat for each user story}
+
+## Functional Requirements
+
+### {Feature Area 1}
+1. **REQ-{ID}**: {Requirement description}
+   - **Rationale**: {Why this is needed}
+   - **Acceptance**: {How to verify}
+   - **Priority**: {P0/P1/P2/P3}
+
+### {Feature Area 2}
+{Repeat structure}
+
+## Non-Functional Requirements
+
+### Performance
+- **REQ-PERF-{ID}**: {Performance requirement}
+  - Target: {Metric and threshold}
+  - Measured by: {How to measure}
+
+### Security
+- **REQ-SEC-{ID}**: {Security requirement}
+  - Compliance: {Standards/regulations}
+  - Verification: {How to verify}
+
+### Scalability
+- **REQ-SCALE-{ID}**: {Scalability requirement}
+  - Target: {Growth expectations}
+  - Strategy: {How to achieve}
+
+### Usability
+- **REQ-UX-{ID}**: {Usability requirement}
+  - Standard: {WCAG, mobile-first, etc.}
+  - Verification: {User testing, automated checks}
+
+## Scope Definition
+
+### In Scope
+- {Feature/capability 1}
+- {Feature/capability 2}
+
+### Out of Scope
+- {Explicitly excluded item 1}
+- {Explicitly excluded item 2}
+
+### Future Considerations
+- {Nice-to-have for future releases}
+
+## Dependencies
+
+### Internal
+- {Team/system dependency}
+- {Prerequisite work}
+
+### External
+- {Third-party service}
+- {External API}
+
+## Assumptions
+
+1. {Assumption 1}
+2. {Assumption 2}
+
+## Risks
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| {Risk description} | {H/M/L} | {H/M/L} | {Mitigation strategy} |
+
+## Open Questions
+
+- [ ] {Question requiring stakeholder input}
+- [ ] {Technical decision needed}
+- [ ] {Clarification needed}
+
+## Traceability
+
+- **Source Document**: {Link to original brief/request}
+- **Design Phase**: {Link to phases/design/}
+- **Test Scenarios**: {Link to phases/qe/}
+- **Tasks**: {Native task IDs or initiative name}
+- **Memory**: {wicked-brain:memory tags for recall}
+
+## Appendices
+
+### A. Glossary
+- **{Term}**: {Definition}
+
+### B. References
+- {Document/URL}
+
+### C. Revision History
+| Date | Author | Changes |
+|------|--------|---------|
+| {YYYY-MM-DD} | {Name} | {Description} |
+```
+
+## Minimal Output Format
+
+For smaller features or rapid analysis:
+
+```markdown
+# Requirements: {Feature Name}
+
+## Summary
+{1-2 sentence description}
+
+## User Stories
+
+### US-001: {Title}
+**As a** {persona}
+**I want** {capability}
+**So that** {benefit}
+
+**Acceptance Criteria**:
+1. Given {context}, When {action}, Then {outcome}
+
+{Repeat for 3-5 core stories}
+
+## Out of Scope
+- {Excluded item}
+
+## Open Questions
+- [ ] {Question}
+```
+
+## Validation Checklist
+
+Before finalizing requirements document:
+
+- [ ] All user stories have persona, capability, benefit
+- [ ] All stories have at least 3 acceptance criteria
+- [ ] Scope clearly defined (in scope, out of scope)
+- [ ] Dependencies documented
+- [ ] Open questions captured
+- [ ] Traceability links included
+- [ ] Non-functional requirements addressed
+- [ ] Stakeholders identified
+- [ ] Risks assessed
+
+## Output Delivery
+
+Requirements should be saved to:
+- `phases/requirements/analysis.md` (in project workflow)
+- `requirements.md` (standalone project)
+- Linked from `outcome.md`
+- Referenced in native task metadata (initiative field)
+
+## Templates
+
+### Quick Start Template
+```bash
+# Copy minimal template for new requirements
+cp "${CLAUDE_PLUGIN_ROOT}/templates/requirements-minimal.md" \
+   requirements.md
+```
+
+### Full Template
+```bash
+# Copy full template for comprehensive analysis
+cp "${CLAUDE_PLUGIN_ROOT}/templates/requirements-full.md" \
+   requirements.md
+```
+
+## Resources
+
+- **User Story Guide**: `refs/user-story-guide.md`
+- **Acceptance Criteria**: See the `acceptance-criteria` skill
+- **Example Projects**: Search wicked-brain for "requirements-example"

package/skills/product/requirements-analysis/refs/user-story-guide.md

@@ -0,0 +1,296 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# User Story Writing Guide
+
+Comprehensive guide to writing effective user stories.
+
+## The User Story Format
+
+```
+As a [persona]
+I want [capability]
+So that [benefit]
+```
+
+### Components
+
+1. **Persona**: Who is the user?
+   - Specific role, not generic "user"
+   - Represents real user segment
+   - Example: "customer", "admin", "support agent"
+
+2. **Capability**: What do they want to do?
+   - Action or feature
+   - From user's perspective
+   - Example: "log in with email", "export report"
+
+3. **Benefit**: Why do they want it?
+   - Business value
+   - User goal or outcome
+   - Example: "so that I can access my account", "so that I can analyze trends"
+
+## INVEST Criteria
+
+Good user stories are:
+
+### Independent
+- Can be developed separately
+- Minimal dependencies on other stories
+- Deliverable on its own
+
+**Bad**: "As a user, I want to see part 2 of the registration flow"
+**Good**: "As a new user, I want to create an account so that I can save my preferences"
+
+### Negotiable
+- Details can be discussed
+- Not a contract
+- Room for collaboration
+
+**Bad**: "As a user, I want a dropdown with exactly 5 options using Select2 library"
+**Good**: "As a user, I want to select my country so that I see localized content"
+
+### Valuable
+- Delivers user/business value
+- Clear benefit stated
+- Not technical tasks
+
+**Bad**: "As a developer, I want to refactor the database schema"
+**Good**: "As a user, I want faster search results so that I can find information quickly"
+
+### Estimable
+- Team can estimate effort
+- Enough detail to size
+- Complexity understood
+
+**Bad**: "As a user, I want a better experience"
+**Good**: "As a customer, I want to filter products by price so that I can find items in my budget"
+
+### Small
+- Completable in one iteration
+- Not too big to manage
+- Can be broken down if needed
+
+**Bad**: "As a user, I want a complete e-commerce platform"
+**Good**: "As a customer, I want to add items to cart so that I can purchase multiple products"
+
+### Testable
+- Clear acceptance criteria
+- Can verify completion
+- Observable outcome
+
+**Bad**: "As a user, I want a nice-looking UI"
+**Good**: "As a user, I want to see my order history so that I can track past purchases"
+
+## Common Personas
+
+**External**: Customer, Visitor, Subscriber, Partner
+**Internal**: Admin, Support Agent, Manager, Developer
+**System**: System (automated), API Consumer (external integration)
+
+## Examples by Domain
+
+### Authentication
+```
+As a new customer
+I want to register with email and password
+So that I can create an account and save my preferences
+
+As a returning customer
+I want to log in with my email
+So that I can access my account
+
+As a user who forgot password
+I want to reset my password via email
+So that I can regain access to my account
+```
+
+### E-commerce
+```
+As a customer
+I want to search for products by keyword
+So that I can find items I'm interested in
+
+As a customer
+I want to add items to my cart
+So that I can purchase multiple products at once
+
+As a customer
+I want to view my order history
+So that I can track past purchases and reorder items
+```
+
+### Data Management
+```
+As an admin
+I want to export user data to CSV
+So that I can analyze trends in Excel
+
+As a support agent
+I want to search for customer by email
+So that I can quickly help with their inquiry
+
+As a manager
+I want to view monthly sales reports
+So that I can make informed business decisions
+```
+
+### API/Integration
+```
+As an API consumer
+I want to authenticate with API keys
+So that I can securely access protected resources
+
+As a system
+I want to retry failed webhook deliveries
+So that I ensure reliable event delivery
+
+As a developer
+I want comprehensive API documentation
+So that I can integrate with the service quickly
+```
+
+## Story Sizing
+
+| Size | Time | Example |
+|---|---|---|
+| S | 1-2 days | Update email address |
+| M | 3-5 days | Search products with filters |
+| L | 1-2 weeks | Complete checkout process — should be broken down |
+
+## Breaking Down Large Stories
+
+### Original (Too Large)
+```
+As a customer
+I want a complete user profile system
+So that I can manage my account
+```
+
+### Broken Down
+```
+US1: As a customer, I want to view my profile
+     So that I can see my current information
+
+US2: As a customer, I want to edit my profile details
+     So that I can keep my information current
+
+US3: As a customer, I want to upload a profile picture
+     So that I can personalize my account
+
+US4: As a customer, I want to change my password
+     So that I can maintain account security
+
+US5: As a customer, I want to delete my account
+     So that I can remove my data from the system
+```
+
+## Common Mistakes
+
+### Mistake 1: Technical Story
+**Bad**: "As a developer, I want to upgrade to React 18"
+**Fix**: "As a user, I want faster page loads so that I have a better experience"
+
+### Mistake 2: Missing Benefit
+**Bad**: "As a user, I want to export data to CSV"
+**Fix**: "As a user, I want to export data to CSV so that I can analyze it in Excel"
+
+### Mistake 3: Too Generic
+**Bad**: "As a user, I want to use the system"
+**Fix**: "As a customer, I want to track my order status so that I know when to expect delivery"
+
+### Mistake 4: Implementation Details
+**Bad**: "As a user, I want a Redux store for state management"
+**Fix**: "As a user, I want my cart to persist across sessions so that I don't lose my selections"
+
+### Mistake 5: Multiple Capabilities
+**Bad**: "As a user, I want to log in, update profile, and delete account"
+**Fix**: Split into 3 separate stories
+
+## Acceptance Criteria Template
+
+Every user story should have acceptance criteria:
+
+```
+As a [persona]
+I want [capability]
+So that [benefit]
+
+Acceptance Criteria:
+1. Given [context], When [action], Then [outcome]
+2. Given [error condition], When [action], Then [error handling]
+3. Given [edge case], When [action], Then [graceful behavior]
+```
+
+## Full Example
+
+```markdown
+### US-123: Customer Registration
+
+**As a** new customer
+**I want to** register with email and password
+**So that** I can create an account and save my preferences
+
+**Priority**: P0
+**Complexity**: M (3-5 days)
+
+**Acceptance Criteria**:
+1. Given valid email and password (8+ chars)
+   When I submit registration form
+   Then account is created and confirmation email sent
+
+2. Given email already registered
+   When I submit registration form
+   Then error "Email already registered" is shown
+
+3. Given password less than 8 characters
+   When I submit registration form
+   Then error "Password must be at least 8 characters" is shown
+
+4. Given malformed email address
+   When I submit registration form
+   Then error "Please enter valid email" is shown
+
+**Dependencies**: Email service integration (US-100)
+**Assumptions**: Email verification required before full access
+**Open Questions**: Social registration (Google, GitHub)?
+
+**Test Data Requirements**:
+- Valid/invalid emails
+- Various password lengths and patterns
+- Existing registered emails
+
+**Notes**: Consider GDPR compliance for EU users
+```
+
+## Template for New Stories
+
+Use this template when creating new user stories:
+
+```markdown
+### US-XXX: [Story Title]
+
+**As a** [specific persona]
+**I want** [specific capability]
+**So that** [specific benefit/value]
+
+**Priority**: [P0/P1/P2]
+**Complexity**: [S/M/L]
+
+**Acceptance Criteria**:
+1. Given [context], When [action], Then [outcome]
+2. Given [error], When [action], Then [handling]
+
+**Dependencies**: [Other stories or systems]
+**Assumptions**: [What we're assuming]
+**Open Questions**: [Needs clarification]
+**Test Data**: [Required for testing]
+**Notes**: [Additional context]
+```
+
+## Resources
+
+- Domain-specific examples: `skills/requirements-analysis/refs/story-examples/`
+- Generate template: `sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/user-story-template.sh"`
+- Validate against INVEST criteria checklist above

package/skills/product/requirements-graph/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: requirements-graph
+description: |
+  Graph-based requirements as atomic markdown files with rich frontmatter.
+  Filesystem-as-graph: each AC is a node, directories are groupings,
+  meta.md files are the human interface, frontmatter traces are the edges.
+
+  Use when: defining requirements as a filesystem graph of atomic ACs, eliciting
+  user stories, or laying out acceptance criteria with traceable edges.
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Requirements Graph
+
+Atomic, graph-structured requirements using the filesystem. Each acceptance
+criterion is a file. Each user story is a directory. Traces live in frontmatter.
+`meta.md` files aggregate for humans.
+
+## Why Graph Over Monolith
+
+| Monolith (old) | Graph (new) |
+|----------------|-------------|
+| 200-260 line single file | 10-30 line atomic nodes |
+| Duplicates stories + functional reqs | One node per concept |
+| Traceability in separate store | Traces in frontmatter |
+| Grep for coverage | FTS5 + frontmatter queries |
+| All-or-nothing context load | Progressive: frontmatter, meta.md, or full |
+
+## Directory Layout
+
+```
+requirements/
+  meta.md                             # Project-level summary
+  {area}/                             # Epic/feature area (kebab-case)
+    meta.md                           # Area summary + story table
+    {US-NNN}/                         # User story directory
+      meta.md                         # Story definition + AC table
+      {AC-NNN}-{slug}.md             # Atomic acceptance criterion
+    {NFR-NNN}-{slug}.md              # Non-functional requirements (area-level)
+  _decisions/                         # ADR-style decision records
+    {DEC-NNN}-{slug}.md
+  _scope.md                           # In/out/future scope
+  _risks.md                           # Risk register
+  _questions.md                       # Open questions
+```
+
+## Node Types
+
+Five node types, each a small markdown file with YAML frontmatter:
+
+| Type | Lives at | Required fields |
+|------|----------|----------------|
+| `acceptance-criterion` | `{area}/{US-NNN}/{AC-NNN}-{slug}.md` | id, type, priority, category, story |
+| `user-story` | `{area}/{US-NNN}/meta.md` | id, type, priority, complexity, persona, status |
+| `area` | `{area}/meta.md` | id, type |
+| `nfr` | `{area}/{NFR-NNN}-{slug}.md` | id, type, priority, category, target |
+| `decision` | `_decisions/{DEC-NNN}-{slug}.md` | id, type, status, date |
+| `requirements-root` | `meta.md` | type, project, created, status |
+
+**Minimal AC** (the atomic unit):
+
+```yaml
+---
+id: auth/US-001/AC-001
+type: acceptance-criterion
+priority: P0
+category: happy-path
+story: auth/US-001
+---
+
+Given valid credentials
+When user submits login form
+Then user is redirected to dashboard and session is created
+```
+
+12 lines. See `refs/schema.md` for all fields and `refs/examples.md` for
+complete story, area, NFR, and decision examples.
+
+## Frontmatter Schema
+
+**Required fields** (all node types):
+- `id` — path-derived slug, canonical reference
+- `type` — `acceptance-criterion`, `user-story`, `area`, `nfr`, `decision`, `requirements-root`
+
+**Required for ACs**:
+- `priority` — P0/P1/P2
+- `category` — happy-path, error, edge-case, non-functional
+- `story` — parent story slug
+
+**Required for stories**:
+- `priority`, `complexity`, `persona`, `status`
+
+**Optional (all types)**:
+- `traces` — list of `{target, type}` objects (graph edges)
+- `tags` — keyword list for search
+- `compliance` — regulatory refs (SOC2, HIPAA, GDPR controls)
+
+**Trace types** (edges):
+- `DECOMPOSES_TO` — story to ACs
+- `TRACES_TO` — requirement to design
+- `IMPLEMENTED_BY` — AC to source code
+- `TESTED_BY` — AC to test file
+- `VERIFIES` — test result back to AC
+- `SATISFIES` — evidence to requirement
+- `DEPENDS_ON` — cross-story/cross-area dependency
+
+## Authoring Process
+
+### 1. Initialize graph
+
+Create `requirements/` with root meta.md, _scope.md, _questions.md:
+
+```bash
+mkdir -p requirements
+# Write root meta.md, _scope.md, _risks.md, _questions.md
+```
+
+### 2. Create areas from discovery
+
+For each feature area, create `requirements/{area}/meta.md`.
+
+### 3. Decompose into stories
+
+For each story, create `requirements/{area}/{US-NNN}/meta.md` with
+the As a/I want/So that definition.
+
+### 4. Write atomic ACs
+
+For each acceptance criterion, create individual files:
+`requirements/{area}/{US-NNN}/{AC-NNN}-{slug}.md`
+
+**Keep AC files small**: Given/When/Then + frontmatter. No essays.
+
+### 5. Add traces as work progresses
+
+Update `traces:` frontmatter as code and tests are written.
+Traces are bidirectional by convention — if AC-001 has
+`IMPLEMENTED_BY: src/login.ts`, the navigate skill can reverse-query.
+
+## Crew Integration
+
+| Crew Phase | Graph Action |
+|------------|-------------|
+| clarify | Create requirements/ structure, areas, stories, ACs |
+| design | Add TRACES_TO links from stories to design docs |
+| build | Add IMPLEMENTED_BY links from ACs to code |
+| test | Add TESTED_BY links from ACs to test files |
+| review | Navigate skill generates fresh meta.md, gate checks coverage |
+
+## Progressive Disclosure
+
+- **SKILL.md** (this file): Overview, layout, schema, process
+- **refs/schema.md**: Complete frontmatter reference with all fields
+- **refs/examples.md**: Full worked examples for different project types