@zigrivers/scaffold 2.1.0

package/knowledge/core/user-stories.md

@@ -0,0 +1,337 @@
+---
+name: user-stories
+description: Expert knowledge for translating product requirements into well-formed user stories
+topics: [user-stories, personas, acceptance-criteria, story-splitting, INVEST, epics, traceability]
+---
+
+## Story Anatomy
+
+The standard user story template captures who wants what and why:
+
+**"As a [persona], I want [action], so that [outcome]."**
+
+Each part serves a purpose:
+- **Persona** — the specific user role, not "a user." Personas come from the PRD.
+- **Action** — what the user wants to do, described in their language, not implementation terms.
+- **Outcome** — the value they get. This is the most important part — it answers "why bother?"
+
+**Good stories:**
+- "As a teacher, I want to assign homework to a class, so that students have practice material outside of class."
+- "As a new user, I want to see a guided tour on first login, so that I understand the core features without reading documentation."
+
+**Bad stories:**
+- "As a user, I want the system to work." — No specific persona, no specific action, no testable outcome.
+- "As a developer, I want a REST endpoint for user creation." — Implementation story. The developer is not the user. Rewrite as: "As a new visitor, I want to create an account, so that I can save my preferences."
+- "As a user, I want good performance." — Not actionable. Rewrite with specifics: "As a returning user, I want the dashboard to load within 2 seconds, so that I can start my daily workflow immediately."
+
+**When to deviate from the template:**
+- **System stories** describe behavior with no direct user action: "When a payment fails, the system retries twice with exponential backoff and notifies the user after final failure." These are acceptable for background processes, scheduled jobs, and automated workflows.
+- **Constraint stories** capture non-functional requirements: "All API responses must complete within 500ms at p95 under normal load." These complement functional stories rather than replacing them.
+
+---
+
+## INVEST Criteria
+
+Every story should satisfy INVEST. Use these criteria to evaluate story quality.
+
+### Independent
+
+The story can be developed and delivered without requiring another story to be done first. Stories with hard dependencies should be split or reordered.
+
+- **Pass:** "As a user, I want to search products by name" — works regardless of whether filtering or sorting stories are done.
+- **Fail:** "As a user, I want to edit my profile photo" that silently depends on "As a user, I want to upload files" — if upload isn't done, this story is blocked.
+- **Fix:** Make the dependency explicit and consider whether the stories should be combined or the shared functionality extracted.
+
+### Negotiable
+
+The story describes what and why, not how. Implementation details are negotiated during development, not locked in the story.
+
+- **Pass:** "As a user, I want to receive notifications about order status changes."
+- **Fail:** "As a user, I want to receive WebSocket push notifications rendered as toast components in the bottom-right corner using the Sonner library."
+- **Fix:** Move implementation details to technical notes. The story stays focused on user value.
+
+### Valuable
+
+The story delivers value to a user or stakeholder. Every story should have a clear beneficiary.
+
+- **Pass:** "As a shopper, I want to save items for later, so that I can return and purchase them without searching again."
+- **Fail:** "As a developer, I want to refactor the authentication module." — No user value. This is a technical task, not a story.
+- **Fix:** Frame technical work in terms of user value, or track it as a task rather than a story.
+
+### Estimable
+
+The team (or agent) can estimate the effort. If a story is too vague to estimate, it needs more conversation or splitting.
+
+- **Pass:** "As a user, I want to reset my password via email" — well-understood pattern, estimable.
+- **Fail:** "As a user, I want AI-powered recommendations" — too vague. What data? What algorithm? What UI?
+- **Fix:** Split into smaller, more specific stories until each is estimable.
+
+### Small
+
+A story should be implementable in 1-3 focused agent sessions. Larger stories need splitting.
+
+- **Pass:** "As a user, I want to update my display name."
+- **Fail:** "As a user, I want a complete e-commerce checkout flow with cart, address, payment, confirmation, and order tracking."
+- **Fix:** Split by workflow step: cart management, address entry, payment processing, order confirmation, order tracking.
+
+### Testable
+
+Acceptance criteria have clear pass/fail outcomes. If you can't write a test for it, the story isn't ready.
+
+- **Pass:** "Given a user with items in cart, when they click checkout, then they see the address form with their saved addresses pre-populated."
+- **Fail:** "The checkout should be intuitive." — Not testable.
+- **Fix:** Replace subjective language with observable behavior.
+
+---
+
+## Persona Definition
+
+Personas are extracted from the PRD's user/stakeholder descriptions. Each persona is a specific user type with distinct goals, not a generic role label.
+
+**Goal-driven personas vs. role labels:**
+- Role label: "Admin" — too generic. What does the admin want?
+- Goal-driven: "School Administrator (Ms. Chen) — manages teacher accounts, reviews class assignments, generates progress reports for the district. Goals: minimize time on administrative tasks, ensure compliance with district reporting requirements."
+
+**When personas collapse:**
+- If two personas have identical goals and workflows, they're the same persona. An "Admin" who is also a regular "User" is two personas only if their goals differ when wearing each hat.
+- Don't create personas for system actors (database, scheduler, API consumer) — these are system stories, not persona stories.
+
+**Persona template:**
+- **Name** — a human name for memorability (e.g., "Alex the Admin")
+- **Role** — their relationship to the product
+- **Goals** — what they're trying to accomplish (2-3 primary goals)
+- **Pain points** — what frustrates them today (informs acceptance criteria)
+- **Context** — when, where, how they use the product (informs UX decisions)
+
+---
+
+## Epic Structure
+
+Epics group related stories by user journey, not by system component.
+
+**Group by journey, not by layer:**
+- **Good:** "Account Setup" epic (registration, email verification, profile creation, preferences) — follows the user's path.
+- **Bad:** "API Endpoints" epic (user CRUD, product CRUD, order CRUD) — groups by technical layer, not user value.
+
+**Epic sizing:**
+- A typical epic contains 3-8 stories. Fewer than 3 suggests the epic is too narrow — consider merging with a related epic. More than 8 suggests the epic covers too much — look for natural split points.
+
+**When to split epics:**
+- Different personas drive different parts of the epic
+- The epic spans distinct phases of the user journey (onboarding vs. daily use vs. administration)
+- Half the stories have no dependencies on the other half
+
+**Epic naming:**
+- Use verb phrases that describe the user goal: "Managing Team Members," "Processing Payments," "Onboarding New Users."
+- Avoid technical names: "REST API," "Database Layer," "Auth Module."
+
+---
+
+## Acceptance Criteria Patterns
+
+Acceptance criteria define when a story is done. They are the contract between story and implementation.
+
+### Given/When/Then Format
+
+The standard format for acceptance criteria scenarios:
+
+```
+Given [precondition/context]
+When [action/trigger]
+Then [expected outcome]
+```
+
+**Example:**
+```
+Given a registered user on the login page
+When they enter valid credentials and click "Sign In"
+Then they are redirected to the dashboard and see a welcome message with their name
+```
+
+### Parameterized Scenarios
+
+When the same behavior applies to multiple variations, use parameterized scenarios:
+
+```
+Given a user with role [admin | member | viewer]
+When they access the settings page
+Then they see [all settings | team settings only | read-only view]
+```
+
+### Negative Scenarios
+
+Every happy path should have corresponding error scenarios:
+
+```
+Given a registered user on the login page
+When they enter an incorrect password
+Then they see "Invalid credentials" and the password field is cleared
+And after 5 failed attempts, the account is locked for 15 minutes
+```
+
+### Boundary Conditions
+
+Test edges, not just middles:
+
+```
+Given a user creating a project name
+When they enter exactly 100 characters (the maximum)
+Then the name is accepted
+When they enter 101 characters
+Then they see "Name must be 100 characters or fewer" and the extra character is rejected
+```
+
+### Acceptance Criteria vs. Test Cases
+
+- **Acceptance criteria** define WHAT should happen (business-level behavior)
+- **Test cases** define HOW to verify it (technical-level steps)
+- Stories contain acceptance criteria. Test cases are derived later during implementation.
+
+---
+
+## Story Splitting Heuristics
+
+When a story is too large, use these patterns to split it into smaller, independently valuable stories.
+
+### By Workflow Step
+
+Before: "As a user, I want to complete the checkout process."
+After:
+- "As a shopper, I want to review my cart before checkout."
+- "As a shopper, I want to enter my shipping address."
+- "As a shopper, I want to select a payment method and pay."
+- "As a shopper, I want to see an order confirmation."
+
+### By Data Variation
+
+Before: "As a user, I want to create posts."
+After:
+- "As a user, I want to create text posts."
+- "As a user, I want to create posts with images."
+- "As a user, I want to create posts with embedded videos."
+
+### By Operation (CRUD)
+
+Before: "As an admin, I want to manage users."
+After:
+- "As an admin, I want to invite new users."
+- "As an admin, I want to view the user list with search and filters."
+- "As an admin, I want to edit user roles."
+- "As an admin, I want to deactivate user accounts."
+
+### By User Role
+
+Before: "As a user, I want to access the dashboard."
+After:
+- "As a team member, I want to see my assigned tasks on the dashboard."
+- "As a team lead, I want to see team progress metrics on the dashboard."
+- "As an admin, I want to see system health and usage stats on the dashboard."
+
+### By Happy/Sad Path
+
+Before: "As a user, I want to upload a document."
+After:
+- "As a user, I want to upload a PDF or Word document."
+- "As a user, I want to see clear error messages when upload fails (wrong format, too large, network error)."
+
+---
+
+## Scope Boundaries
+
+Every story should explicitly state what it does NOT include to prevent scope creep.
+
+**Format:**
+```
+**Scope Boundary:** This story does NOT include:
+- Bulk assignment (covered by US-045)
+- Email notifications for assignments (covered by US-023)
+- Grading submitted assignments (separate epic)
+```
+
+**Why scope boundaries matter:**
+- During implementation, agents can confidently stop when they hit a boundary
+- Stories that overlap are discovered early (and consolidated or clarified)
+- Scope boundaries flow downstream into task boundaries
+
+**Relationship to MoSCoW:**
+- "Won't" items in MoSCoW are scope boundaries at the PRD level
+- Story-level scope boundaries are more granular — they clarify what THIS story excludes even if another story covers it
+
+---
+
+## PRD-to-Story Traceability
+
+Every PRD feature must map to at least one user story. This is a non-negotiable coverage requirement.
+
+**How to ensure coverage:**
+1. Extract every distinct feature and requirement from the PRD
+2. For each, identify the corresponding user story or stories
+3. Flag any PRD feature with no story — these are coverage gaps
+4. Flag any story that doesn't trace back to a PRD feature — these may be scope creep
+
+**Handling compound requirements:**
+- PRD: "Users can create, edit, and delete projects." → Split into 3 stories (one per operation).
+- PRD: "The system supports SSO and email/password authentication." → Two stories (one per auth method).
+
+**Surfacing implicit requirements:**
+- Every user action that can fail needs an error handling story or acceptance criteria
+- Every data entry point needs validation acceptance criteria
+- Accessibility requirements (keyboard navigation, screen readers) apply to all UI stories
+- Loading states, empty states, and offline behavior are often implied but not stated
+
+**Traceability notation:**
+- Use IDs to create a traceable chain: PRD-REQ-001 → US-001 → (downstream: Task BD-42)
+- Story IDs (US-001, US-002, ...) are stable — they persist through updates and are referenced by downstream phases
+
+---
+
+## Story Dependencies
+
+Some stories must be implemented before others. Document these explicitly.
+
+**Blocked-by vs. informed-by:**
+- **Blocked-by:** Story B cannot start until Story A is complete. A produces something B requires (a database table, an API endpoint, a shared component).
+- **Informed-by:** Story B benefits from knowing how Story A was implemented, but can proceed independently with reasonable assumptions.
+
+Only blocked-by dependencies should be formal constraints. Informed-by relationships are noted but don't block.
+
+**How dependencies feed into task decomposition:**
+- Story dependencies become task dependencies in the implementation tasks step
+- Chains of 3+ dependent stories should be reviewed — long chains limit parallelization
+- If many stories depend on the same story, that story is on the critical path and should be prioritized
+
+**Keeping dependency chains short:**
+- If Story C depends on B which depends on A, ask: can C depend directly on A instead? Can C's dependency be satisfied with a mock or interface?
+- Extract shared infrastructure into its own story at the front of the chain rather than letting it hide inside a feature story
+
+---
+
+## Common Pitfalls
+
+### Implementation Stories
+- **Problem:** "As a developer, I want a REST endpoint for user CRUD."
+- **Fix:** Rewrite from the user's perspective: "As a new visitor, I want to create an account with my email." The REST endpoint is an implementation detail, not a user story.
+
+### Stories Too Large
+- **Problem:** A story with 10+ acceptance criteria spanning multiple workflows.
+- **Fix:** Split using the heuristics above. Each resulting story should have 3-5 acceptance criteria.
+
+### Vague Acceptance Criteria
+- **Problem:** "The feature works correctly and is user-friendly."
+- **Fix:** Replace with Given/When/Then scenarios. Define "correctly" and "user-friendly" in observable terms.
+
+### Missing Personas
+- **Problem:** Stories reference undefined personas ("a power user," "the operator").
+- **Fix:** Map back to PRD personas. If the PRD doesn't define this persona, either add it to the PRD or use an existing persona.
+
+### Stories Without Value Statements
+- **Problem:** "As a user, I want to click the submit button."
+- **Fix:** Add the "so that" clause: "As a user, I want to submit my feedback form, so that the support team can address my issue."
+
+### Duplicate Stories Across Epics
+- **Problem:** "Upload profile photo" appears in both "Account Setup" and "Profile Management" epics.
+- **Fix:** Choose one epic. Add a scope boundary in the other epic referencing the canonical story.
+
+### Confusing Acceptance Criteria with Implementation Steps
+- **Problem:** "1. Create a POST /api/users endpoint. 2. Validate email format with regex. 3. Hash password with bcrypt."
+- **Fix:** These are implementation steps, not acceptance criteria. Rewrite as: "Given a valid email and password, when the user submits registration, then their account is created and they receive a confirmation email."

package/knowledge/core/user-story-innovation.md

@@ -0,0 +1,171 @@
+---
+name: user-story-innovation
+description: Techniques for discovering UX enhancements and innovation opportunities in user stories
+topics: [innovation, ux-enhancements, user-stories, gap-analysis, differentiators]
+---
+
+## Scope Boundary
+
+This knowledge covers UX-level improvements only — making existing features better, not adding new features. Feature-level innovation belongs in PRD innovation (`innovate-prd`). If an enhancement requires a new PRD section, it is out of scope for user story innovation.
+
+**In scope:**
+- Smart defaults that reduce user effort on existing features
+- Better error handling and recovery within existing flows
+- Accessibility improvements to existing stories
+- Progressive disclosure within existing interfaces
+- AI-native enhancements to existing workflows
+
+**Out of scope:**
+- New features not covered by any PRD requirement
+- New user personas not defined in the PRD
+- Major architectural additions (new services, new databases)
+- Scope expansion that changes the product's purpose
+
+---
+
+## High-Value Low-Effort Enhancements
+
+These patterns add significant user value for minimal implementation effort. Look for them in every story.
+
+### Smart Defaults
+Pre-fill fields based on context, history, or the most common choice. Users should only need to change what's different, not re-enter what's predictable.
+- Forms pre-populated from user profile or previous submissions
+- Timezone auto-detected from browser
+- Default selections based on user's most frequent choice
+- "Same as billing address" for shipping
+
+### Inline Validation
+Give immediate feedback on input rather than waiting for form submission. Catches errors early and reduces frustration.
+- Email format validation as you type
+- Password strength indicator
+- Username availability check before submission
+- Character count approaching limit
+
+### Keyboard Shortcuts
+Power users want to move fast. Keyboard shortcuts for frequent actions reduce friction.
+- Common patterns: Ctrl/Cmd+S (save), Ctrl/Cmd+K (search), Escape (close/cancel)
+- Arrow keys for list navigation
+- Tab through form fields with logical ordering
+
+### Progressive Disclosure
+Don't overwhelm users on first encounter. Reveal complexity as they need it.
+- "Advanced options" expandable sections
+- Onboarding wizards that introduce features over time
+- Contextual help that appears when users hover or focus
+- Default simple view with "show more" for detail
+
+### Leveraging Existing Data
+Data already being collected that could power useful features without new infrastructure.
+- Activity data → streak tracking, usage insights, "you did X this week" summaries
+- Search history → suggested searches, "recently viewed"
+- Error patterns → proactive warnings ("this field usually causes issues — here's a tip")
+
+### Undo/Redo
+Where destructive actions exist, add undo before requiring confirmation dialogs.
+- Soft delete with "undo" toast (better UX than "are you sure?" dialogs)
+- Undo last edit in text/content editing
+- "Restore defaults" for settings changes
+
+### Batch Operations
+Where users repeat the same single action multiple times, offer batch alternatives.
+- Select multiple items → bulk delete, bulk archive, bulk assign
+- "Apply to all" option in settings
+- Bulk import/export for data entry
+
+---
+
+## Differentiators
+
+These make the product stand out from alternatives. Not every product needs them, but they're worth considering.
+
+### "Wow" Moments
+Small touches that make users want to share the product.
+- Satisfying animations on task completion
+- Personalized empty states that don't feel like error pages
+- Easter eggs for power users who discover hidden features
+- Thoughtful microcopy that shows personality
+
+### AI-Native Features
+Capabilities that wouldn't exist without AI, not AI bolted onto traditional features.
+- Natural language search that understands intent, not just keywords
+- Auto-categorization of user-created content
+- Smart suggestions based on context ("users who did X often do Y next")
+- Draft generation or auto-completion for text-heavy inputs
+
+### Personalization Without Configuration
+The product adapts to the user without them having to set preferences.
+- Recently used items surfaced first
+- Layout adapts to usage patterns
+- Notification frequency auto-tuned based on engagement
+- Content ordering reflects individual priorities
+
+---
+
+## Defensive Gaps
+
+Things users expect but specs often miss. These are especially important for v1 launches.
+
+### Accessibility
+- WCAG AA compliance as minimum baseline
+- Keyboard navigation for all interactive elements
+- Screen reader compatibility with proper ARIA labels
+- Sufficient color contrast (4.5:1 for normal text, 3:1 for large text)
+- Focus indicators visible in all themes
+
+### Mobile Responsiveness (if web)
+- Touch targets minimum 44x44px
+- Readable text without zooming
+- Forms that work with mobile keyboards
+- Navigation patterns that work with one hand
+
+### Offline/Degraded Mode
+- What happens when the network drops mid-action?
+- Queue writes for sync when connection returns
+- Show stale data with "last updated" indicator rather than blank screens
+- Graceful error messages that explain what happened and what to do
+
+### Performance Under Load
+- Loading states for every async operation (never leave users staring at nothing)
+- Pagination or virtual scrolling for large lists
+- Image lazy loading and appropriate sizing
+- Optimistic UI updates where safe
+
+### Error Recovery
+- Never lose user work — auto-save drafts, preserve form state on error
+- Clear error messages that say what happened AND what to do next
+- Retry logic for transient failures with user feedback
+- Graceful degradation when a non-critical feature fails
+
+### Empty States
+- First-time experience should guide, not confuse
+- Empty lists show "here's how to add your first X" rather than blank space
+- Zero-data dashboards show sample data or onboarding steps
+- Search with no results suggests alternatives
+
+---
+
+## Evaluation Framework
+
+For each innovation suggestion, evaluate before proposing to the user.
+
+### Cost Assessment
+- **Trivial** (< 1 task): Can be added to an existing story's acceptance criteria. No new stories needed.
+- **Moderate** (1-3 tasks): Requires new stories or significant additions to existing stories. Scoped to a single epic.
+- **Significant** (4+ tasks): Requires multiple new stories, possibly a new epic. May affect architecture.
+
+### Impact Assessment
+- **Nice-to-have**: Polishes the experience but users wouldn't notice if absent.
+- **Noticeable improvement**: Users would appreciate it. Reduces friction in common workflows.
+- **Significant differentiator**: Sets the product apart. Users would choose this product partly because of this feature.
+
+### Decision Framework
+- **Must-have for v1**: High impact + trivial or moderate cost. Not adding it would be a visible gap.
+- **Backlog for later**: High impact + significant cost, or moderate impact at any cost. Valuable but not blocking launch.
+- **Reject**: Low impact regardless of cost, or out of scope for the PRD.
+
+### Presenting to the User
+Group related suggestions for efficient decision-making. For each group:
+1. Describe the enhancement and its user benefit
+2. State the cost (trivial/moderate/significant)
+3. State your recommendation (must-have/backlog/reject)
+4. Wait for approval before integrating into stories