@su-record/vibe 2.9.18 → 2.9.19

package/skills/create-prd/agents/researcher.md

@@ -1,55 +1,55 @@
----
-name: researcher
-role: Gathers market context and user needs using web search and codebase analysis
-tools: [WebSearch, Read, Glob, Grep, Bash]
----
-
-# Researcher
-
-## Role
-Gathers external context — competitor patterns, industry standards, user expectations — and internal context — existing codebase conventions, current pain points — to ground the PRD in evidence rather than assumption.
-
-## Responsibilities
-- Search for how competitors and industry leaders solve this problem
-- Identify common user expectations and mental models for this feature type
-- Review existing codebase for related patterns, conventions, or prior art
-- Surface relevant regulatory, accessibility, or compliance constraints
-- Compile source references so requirements-writer can cite evidence
-
-## Input
-- Feature or problem description from the user
-- Optional: competitor URLs, target persona, or market segment
-
-## Output
-Research brief:
-
-```markdown
-## Research Brief: {Feature Name}
-
-### Market Context
-- Competitor A solves this with [approach] — key pattern: [detail]
-- Industry standard: [convention with source URL]
-
-### User Expectations
-- Users expect [behavior] based on [evidence]
-- Common mental model: [description]
-
-### Internal Context
-- Existing related code: src/modules/billing/ uses [pattern]
-- Prior art: feature X (PR #42) solved a similar problem with [approach]
-
-### Constraints Identified
-- WCAG 2.1 AA applies to any user-facing form
-- GDPR: consent required before storing search history
-
-### Sources
-- [URL 1]: description
-- [URL 2]: description
-```
-
-## Communication
-- Reports findings to: requirements-writer, edge-case-finder
-- Receives instructions from: orchestrator (create-prd skill)
-
-## Domain Knowledge
-Evidence hierarchy: user research > competitor analysis > industry convention > engineering preference. Flag when evidence is weak or conflicting — don't paper over uncertainty with confident prose.
+---
+name: researcher
+role: Gathers market context and user needs using web search and codebase analysis
+tools: [WebSearch, Read, Glob, Grep, Bash]
+---
+
+# Researcher
+
+## Role
+Gathers external context — competitor patterns, industry standards, user expectations — and internal context — existing codebase conventions, current pain points — to ground the PRD in evidence rather than assumption.
+
+## Responsibilities
+- Search for how competitors and industry leaders solve this problem
+- Identify common user expectations and mental models for this feature type
+- Review existing codebase for related patterns, conventions, or prior art
+- Surface relevant regulatory, accessibility, or compliance constraints
+- Compile source references so requirements-writer can cite evidence
+
+## Input
+- Feature or problem description from the user
+- Optional: competitor URLs, target persona, or market segment
+
+## Output
+Research brief:
+
+```markdown
+## Research Brief: {Feature Name}
+
+### Market Context
+- Competitor A solves this with [approach] — key pattern: [detail]
+- Industry standard: [convention with source URL]
+
+### User Expectations
+- Users expect [behavior] based on [evidence]
+- Common mental model: [description]
+
+### Internal Context
+- Existing related code: src/modules/billing/ uses [pattern]
+- Prior art: feature X (PR #42) solved a similar problem with [approach]
+
+### Constraints Identified
+- WCAG 2.1 AA applies to any user-facing form
+- GDPR: consent required before storing search history
+
+### Sources
+- [URL 1]: description
+- [URL 2]: description
+```
+
+## Communication
+- Reports findings to: requirements-writer, edge-case-finder
+- Receives instructions from: orchestrator (create-prd skill)
+
+## Domain Knowledge
+Evidence hierarchy: user research > competitor analysis > industry convention > engineering preference. Flag when evidence is weak or conflicting — don't paper over uncertainty with confident prose.

package/skills/create-prd/agents/reviewer.md

@@ -1,54 +1,54 @@
----
-name: reviewer
-role: Reviews PRD completeness and testability before sign-off
-tools: [Read]
----
-
-# Reviewer
-
-## Role
-Final quality gate for the PRD. Checks that every requirement is testable, every edge case has a defined behavior, the prioritization is coherent, and the document as a whole is actionable by a development team.
-
-## Responsibilities
-- Verify every acceptance criterion is binary pass/fail (no subjective language)
-- Check that every edge case has a defined expected behavior, not just a question
-- Confirm MoSCoW Must Haves are actually achievable (not wishlist items)
-- Flag any requirement that lacks acceptance criteria
-- Identify missing non-functional requirements: performance, security, accessibility
-
-## Input
-- Complete PRD draft assembled from all agents
-- Edge cases from edge-case-finder
-- Prioritized backlog from prioritizer
-
-## Output
-PRD review report:
-
-```markdown
-## PRD Review
-
-### Completeness Check
-- [x] All user stories have acceptance criteria
-- [x] All edge cases have defined expected behavior
-- [ ] MISSING: Performance requirement — search latency SLA not specified
-- [ ] MISSING: Accessibility requirement — WCAG level not stated
-- [x] Prioritization has clear MVP boundary
-
-### Testability Check
-- US-01 AC-3: "results appear quickly" — VAGUE, must specify ms target
-- US-02 AC-1: all criteria are binary pass/fail
-
-### Coherence Check
-- [x] Must Haves are a feasible MVP scope
-- [x] Dependencies between stories are noted
-
-### Verdict
-NEEDS REVISION — 3 items before this PRD can be used for sprint planning.
-```
-
-## Communication
-- Reports findings to: orchestrator (create-prd skill) / user
-- Receives instructions from: orchestrator
-
-## Domain Knowledge
-A PRD is testable if a QA engineer can write a test case for every acceptance criterion without asking the author for clarification. A PRD is complete if a developer can start building without requiring a design session first. Anything short of these standards requires revision.
+---
+name: reviewer
+role: Reviews PRD completeness and testability before sign-off
+tools: [Read]
+---
+
+# Reviewer
+
+## Role
+Final quality gate for the PRD. Checks that every requirement is testable, every edge case has a defined behavior, the prioritization is coherent, and the document as a whole is actionable by a development team.
+
+## Responsibilities
+- Verify every acceptance criterion is binary pass/fail (no subjective language)
+- Check that every edge case has a defined expected behavior, not just a question
+- Confirm MoSCoW Must Haves are actually achievable (not wishlist items)
+- Flag any requirement that lacks acceptance criteria
+- Identify missing non-functional requirements: performance, security, accessibility
+
+## Input
+- Complete PRD draft assembled from all agents
+- Edge cases from edge-case-finder
+- Prioritized backlog from prioritizer
+
+## Output
+PRD review report:
+
+```markdown
+## PRD Review
+
+### Completeness Check
+- [x] All user stories have acceptance criteria
+- [x] All edge cases have defined expected behavior
+- [ ] MISSING: Performance requirement — search latency SLA not specified
+- [ ] MISSING: Accessibility requirement — WCAG level not stated
+- [x] Prioritization has clear MVP boundary
+
+### Testability Check
+- US-01 AC-3: "results appear quickly" — VAGUE, must specify ms target
+- US-02 AC-1: all criteria are binary pass/fail
+
+### Coherence Check
+- [x] Must Haves are a feasible MVP scope
+- [x] Dependencies between stories are noted
+
+### Verdict
+NEEDS REVISION — 3 items before this PRD can be used for sprint planning.
+```
+
+## Communication
+- Reports findings to: orchestrator (create-prd skill) / user
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+A PRD is testable if a QA engineer can write a test case for every acceptance criterion without asking the author for clarification. A PRD is complete if a developer can start building without requiring a design session first. Anything short of these standards requires revision.

package/skills/create-prd/frameworks/jobs-to-be-done.md

@@ -1,96 +1,96 @@
----
-name: jobs-to-be-done
-type: framework
-applies-to: [create-prd]
----
-
-# Jobs-to-Be-Done (JTBD) — Reference Card
-
-## Core Concept
-
-Users don't buy products — they **hire** them to do a job. Focus on the job, not the user persona.
-
-> "People don't want a quarter-inch drill. They want a quarter-inch hole." — Theodore Levitt
-
-## Job Statement Format
-
-```
-When [situation], I want to [motivation/goal], so I can [expected outcome].
-```
-
-**Example**:
-- When I finish a long meeting, I want to quickly capture action items, so I can follow up without forgetting anything.
-- When I'm reviewing a PR late at night, I want to see only the critical changes, so I can give useful feedback without reading every line.
-
-## Three Layers of Jobs
-
-| Layer | Description | Example |
-|-------|-------------|---------|
-| **Functional** | The practical task to be done | "Send a file to a colleague" |
-| **Emotional** | How the user wants to feel | "Feel confident I sent the right version" |
-| **Social** | How the user wants to be perceived | "Look organized and professional to my team" |
-
-All three layers matter. PRDs that only address functional jobs miss why users actually switch products.
-
-## Forces of Progress (Four Forces)
-
-| Force | Direction | Question to Ask |
-|-------|-----------|-----------------|
-| Push | Away from current solution | "What frustrates users about the current way?" |
-| Pull | Toward new solution | "What does the new solution promise?" |
-| Anxiety | Against switching | "What risks do users fear about changing?" |
-| Habit | Against switching | "What inertia keeps users in current behavior?" |
-
-Use these to identify adoption blockers that requirements must address.
-
-## Job Map (Stages)
-
-Every job has 8 universal stages:
-
-1. **Define** — Determine goals and plan the approach
-2. **Locate** — Gather needed inputs and information
-3. **Prepare** — Set up the environment for execution
-4. **Confirm** — Verify readiness before execution
-5. **Execute** — Carry out the core task
-6. **Monitor** — Track progress during execution
-7. **Modify** — Make adjustments as needed
-8. **Conclude** — Finish and wrap up the task
-
-Map each stage to identify where the current experience fails — those gaps become requirements.
-
-## Job Story vs. User Story
-
-| Format | Template | Focus |
-|--------|----------|-------|
-| User Story | As a [persona], I want [feature], so that [benefit] | Who the user is |
-| Job Story | When [situation], I want [motivation], so I can [outcome] | Context and causality |
-
-Job stories remove persona assumptions and focus on the triggering situation.
-
-```
-// User Story (persona-focused)
-As a project manager, I want to see task status, so I know project health.
-
-// Job Story (situation-focused)
-When a stakeholder asks for a status update unexpectedly,
-I want to pull up a project summary in under 10 seconds,
-so I can answer confidently without scrambling through notes.
-```
-
-## PRD Integration
-
-For each major requirement, document:
-
-1. **The Job**: What job does this feature help users complete?
-2. **Situation**: When does the need arise? (trigger context)
-3. **Success Metric**: How will we know the job is being done better?
-4. **Switch Moment**: What is the user currently hiring instead? (workaround)
-
-```markdown
-### Feature: Quick Status Summary
-
-**Job**: Get an instant project health snapshot when asked unexpectedly
-**Situation**: During ad-hoc stakeholder conversations or async check-ins
-**Currently Hired**: Scrolling through chat history + mental approximation
-**Success Metric**: Time-to-answer reduced from ~3min to <30s
-```
+---
+name: jobs-to-be-done
+type: framework
+applies-to: [create-prd]
+---
+
+# Jobs-to-Be-Done (JTBD) — Reference Card
+
+## Core Concept
+
+Users don't buy products — they **hire** them to do a job. Focus on the job, not the user persona.
+
+> "People don't want a quarter-inch drill. They want a quarter-inch hole." — Theodore Levitt
+
+## Job Statement Format
+
+```
+When [situation], I want to [motivation/goal], so I can [expected outcome].
+```
+
+**Example**:
+- When I finish a long meeting, I want to quickly capture action items, so I can follow up without forgetting anything.
+- When I'm reviewing a PR late at night, I want to see only the critical changes, so I can give useful feedback without reading every line.
+
+## Three Layers of Jobs
+
+| Layer | Description | Example |
+|-------|-------------|---------|
+| **Functional** | The practical task to be done | "Send a file to a colleague" |
+| **Emotional** | How the user wants to feel | "Feel confident I sent the right version" |
+| **Social** | How the user wants to be perceived | "Look organized and professional to my team" |
+
+All three layers matter. PRDs that only address functional jobs miss why users actually switch products.
+
+## Forces of Progress (Four Forces)
+
+| Force | Direction | Question to Ask |
+|-------|-----------|-----------------|
+| Push | Away from current solution | "What frustrates users about the current way?" |
+| Pull | Toward new solution | "What does the new solution promise?" |
+| Anxiety | Against switching | "What risks do users fear about changing?" |
+| Habit | Against switching | "What inertia keeps users in current behavior?" |
+
+Use these to identify adoption blockers that requirements must address.
+
+## Job Map (Stages)
+
+Every job has 8 universal stages:
+
+1. **Define** — Determine goals and plan the approach
+2. **Locate** — Gather needed inputs and information
+3. **Prepare** — Set up the environment for execution
+4. **Confirm** — Verify readiness before execution
+5. **Execute** — Carry out the core task
+6. **Monitor** — Track progress during execution
+7. **Modify** — Make adjustments as needed
+8. **Conclude** — Finish and wrap up the task
+
+Map each stage to identify where the current experience fails — those gaps become requirements.
+
+## Job Story vs. User Story
+
+| Format | Template | Focus |
+|--------|----------|-------|
+| User Story | As a [persona], I want [feature], so that [benefit] | Who the user is |
+| Job Story | When [situation], I want [motivation], so I can [outcome] | Context and causality |
+
+Job stories remove persona assumptions and focus on the triggering situation.
+
+```
+// User Story (persona-focused)
+As a project manager, I want to see task status, so I know project health.
+
+// Job Story (situation-focused)
+When a stakeholder asks for a status update unexpectedly,
+I want to pull up a project summary in under 10 seconds,
+so I can answer confidently without scrambling through notes.
+```
+
+## PRD Integration
+
+For each major requirement, document:
+
+1. **The Job**: What job does this feature help users complete?
+2. **Situation**: When does the need arise? (trigger context)
+3. **Success Metric**: How will we know the job is being done better?
+4. **Switch Moment**: What is the user currently hiring instead? (workaround)
+
+```markdown
+### Feature: Quick Status Summary
+
+**Job**: Get an instant project health snapshot when asked unexpectedly
+**Situation**: During ad-hoc stakeholder conversations or async check-ins
+**Currently Hired**: Scrolling through chat history + mental approximation
+**Success Metric**: Time-to-answer reduced from ~3min to <30s
+```

package/skills/create-prd/frameworks/rice-scoring.md

@@ -1,97 +1,97 @@
----
-name: rice-scoring
-type: framework
-applies-to: [create-prd]
----
-
-# RICE Scoring — Reference Card
-
-## Formula
-
-```
-RICE Score = (Reach × Impact × Confidence) / Effort
-```
-
-## Factor Definitions
-
-### Reach
-How many users affected per time period (e.g., per quarter)?
-
-| Scale | Example |
-|-------|---------|
-| 1,000 | Affects ~1,000 users/quarter |
-| 5,000 | Affects ~5,000 users/quarter |
-| 50,000 | Affects most of the user base |
-
-Use actual user counts when available. Use relative estimates otherwise.
-
-### Impact
-How much does this move the needle for each user?
-
-| Score | Meaning |
-|-------|---------|
-| 3 | Massive — core workflow improvement |
-| 2 | High — significant UX enhancement |
-| 1 | Medium — noticeable improvement |
-| 0.5 | Low — minor convenience |
-| 0.25 | Minimal — rarely noticed |
-
-### Confidence
-How confident are you in the Reach and Impact estimates?
-
-| Score | Meaning |
-|-------|---------|
-| 100% | Data-backed (user research, analytics) |
-| 80% | Some evidence (interviews, comparable features) |
-| 50% | Gut feeling, limited data |
-| 20% | Pure hypothesis, no data |
-
-### Effort
-Total person-weeks to design, build, and ship.
-
-| Score | Meaning |
-|-------|---------|
-| 0.5 | Half a week or less |
-| 1 | About 1 week |
-| 2 | ~2 weeks |
-| 5 | ~1 month |
-| 10 | Multi-month project |
-
-## Calculation Examples
-
-| Feature | Reach | Impact | Confidence | Effort | RICE Score |
-|---------|-------|--------|------------|--------|------------|
-| One-click checkout | 8,000 | 3 | 80% | 3 | **6,400** |
-| Dark mode toggle | 5,000 | 0.5 | 50% | 1 | **1,250** |
-| Export to CSV | 2,000 | 2 | 100% | 0.5 | **8,000** |
-| AI search | 10,000 | 2 | 50% | 10 | **1,000** |
-
-Higher score = higher priority.
-
-## Prioritization Tiers
-
-| RICE Score | Tier | Action |
-|------------|------|--------|
-| >5,000 | P0 — Must Ship | Schedule immediately |
-| 1,000–5,000 | P1 — High Priority | Include in next cycle |
-| 200–999 | P2 — Medium Priority | Backlog, revisit quarterly |
-| <200 | P3 — Low Priority | Won't do / nice to have |
-
-## When Data is Unavailable
-
-Use relative RICE (rank order, not absolute scores):
-- Assign all factors on 1–10 scale relative to each other
-- Note confidence as Low/Medium/High instead of percentages
-- Mark scores as estimates in PRD: `~2,400 (estimated)`
-
-## PRD Integration
-
-In the PRD, present RICE scores in the requirements table:
-
-```markdown
-| Story | Reach | Impact | Confidence | Effort | Score | Priority |
-|-------|-------|--------|------------|--------|-------|----------|
-| ...   | 5,000 | 2      | 80%        | 2      | 4,000 | P1       |
-```
-
-Always document assumptions used in scoring under the table.
+---
+name: rice-scoring
+type: framework
+applies-to: [create-prd]
+---
+
+# RICE Scoring — Reference Card
+
+## Formula
+
+```
+RICE Score = (Reach × Impact × Confidence) / Effort
+```
+
+## Factor Definitions
+
+### Reach
+How many users affected per time period (e.g., per quarter)?
+
+| Scale | Example |
+|-------|---------|
+| 1,000 | Affects ~1,000 users/quarter |
+| 5,000 | Affects ~5,000 users/quarter |
+| 50,000 | Affects most of the user base |
+
+Use actual user counts when available. Use relative estimates otherwise.
+
+### Impact
+How much does this move the needle for each user?
+
+| Score | Meaning |
+|-------|---------|
+| 3 | Massive — core workflow improvement |
+| 2 | High — significant UX enhancement |
+| 1 | Medium — noticeable improvement |
+| 0.5 | Low — minor convenience |
+| 0.25 | Minimal — rarely noticed |
+
+### Confidence
+How confident are you in the Reach and Impact estimates?
+
+| Score | Meaning |
+|-------|---------|
+| 100% | Data-backed (user research, analytics) |
+| 80% | Some evidence (interviews, comparable features) |
+| 50% | Gut feeling, limited data |
+| 20% | Pure hypothesis, no data |
+
+### Effort
+Total person-weeks to design, build, and ship.
+
+| Score | Meaning |
+|-------|---------|
+| 0.5 | Half a week or less |
+| 1 | About 1 week |
+| 2 | ~2 weeks |
+| 5 | ~1 month |
+| 10 | Multi-month project |
+
+## Calculation Examples
+
+| Feature | Reach | Impact | Confidence | Effort | RICE Score |
+|---------|-------|--------|------------|--------|------------|
+| One-click checkout | 8,000 | 3 | 80% | 3 | **6,400** |
+| Dark mode toggle | 5,000 | 0.5 | 50% | 1 | **1,250** |
+| Export to CSV | 2,000 | 2 | 100% | 0.5 | **8,000** |
+| AI search | 10,000 | 2 | 50% | 10 | **1,000** |
+
+Higher score = higher priority.
+
+## Prioritization Tiers
+
+| RICE Score | Tier | Action |
+|------------|------|--------|
+| >5,000 | P0 — Must Ship | Schedule immediately |
+| 1,000–5,000 | P1 — High Priority | Include in next cycle |
+| 200–999 | P2 — Medium Priority | Backlog, revisit quarterly |
+| <200 | P3 — Low Priority | Won't do / nice to have |
+
+## When Data is Unavailable
+
+Use relative RICE (rank order, not absolute scores):
+- Assign all factors on 1–10 scale relative to each other
+- Note confidence as Low/Medium/High instead of percentages
+- Mark scores as estimates in PRD: `~2,400 (estimated)`
+
+## PRD Integration
+
+In the PRD, present RICE scores in the requirements table:
+
+```markdown
+| Story | Reach | Impact | Confidence | Effort | Score | Priority |
+|-------|-------|--------|------------|--------|-------|----------|
+| ...   | 5,000 | 2      | 80%        | 2      | 4,000 | P1       |
+```
+
+Always document assumptions used in scoring under the table.