@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/testing-strategy.md

@@ -4,9 +4,13 @@ description: Test pyramid, testing patterns, coverage strategy, and quality gate
 topics: [testing, tdd, test-pyramid, quality-gates, coverage, test-data, mocking]
 ---
 
-## Test Pyramid
+# Testing Strategy
 
-The test pyramid organizes tests by scope, speed, and confidence:
+Expert knowledge for test pyramid design, testing patterns, coverage strategy, and quality gates across all test levels.
+
+## Summary
+
+### Test Pyramid
 
 ```
         /  E2E Tests  \         Few, slow, high confidence
@@ -15,7 +19,28 @@ The test pyramid organizes tests by scope, speed, and confidence:
      ________________________
 ```
 
-### Unit Tests
+### Test Level Definitions
+
+- **Unit Tests** — Single function/method/class in isolation. No I/O, deterministic, millisecond execution. Test pure business logic, state machines, edge cases, error handling.
+- **Integration Tests** — Interaction between 2+ components with real infrastructure. Seconds to execute. Test API handlers, DB queries, auth middleware, external service integrations.
+- **E2E Tests** — Complete user flows with real browser/device. Seconds to minutes. Test critical user journeys only (5-15 tests for most apps).
+
+### Basic Patterns
+
+- **Arrange/Act/Assert (AAA)** — Set up conditions, perform action, verify result.
+- **Given/When/Then (BDD)** — Behavior-oriented variant for integration and E2E tests.
+- **Test Doubles** — Stubs (return predetermined data), Mocks (verify interactions), Spies (wrap real implementations), Fakes (simplified working implementations).
+
+### What NOT to Mock
+
+- The thing you're testing
+- Value objects and simple data transformations
+- The database in integration tests
+- Too many things (if 10 mocks needed, refactor the code)
+
+## Deep Guidance
+
+### Unit Tests — Extended
 
 **What they test:** A single function, method, or class in isolation from all external dependencies (database, network, file system, other modules).
 
@@ -62,7 +87,7 @@ describe('calculateOrderTotal', () => {
 });
 ```
 
-### Integration Tests
+### Integration Tests — Extended
 
 **What they test:** The interaction between two or more components, including real infrastructure (database, API calls between layers, message queues).
 
@@ -113,7 +138,7 @@ describe('POST /api/v1/users', () => {
 });
 ```
 
-### End-to-End (E2E) Tests
+### End-to-End (E2E) Tests — Extended
 
 **What they test:** Complete user flows from the user's perspective, using a real browser (for web apps) or real device/emulator (for mobile apps).
 
@@ -139,60 +164,19 @@ describe('POST /api/v1/users', () => {
 - Each tests a complete user journey, not a single interaction
 - If an E2E test breaks, it reveals a real user-facing problem
 
-## Testing Patterns
-
-### Arrange / Act / Assert (AAA)
-
-Every test follows three phases:
-
-```typescript
-it('calculates discount for premium members', () => {
-  // Arrange: set up the test conditions
-  const member = createMember({ tier: 'premium' });
-  const order = createOrder({ items: [{ price: 10000 }] });
-
-  // Act: perform the action being tested
-  const discount = calculateDiscount(member, order);
-
-  // Assert: verify the result
-  expect(discount).toBe(1000);  // 10% discount
-});
-```
-
-### Given / When / Then (BDD)
-
-Behavior-oriented variant, often used for integration and E2E tests:
-
-```typescript
-describe('Order submission', () => {
-  it('sends confirmation email when order is submitted', async () => {
-    // Given: a draft order with valid items
-    const order = await createDraftOrder({ customerId, items: validItems });
-
-    // When: the order is submitted
-    await orderService.submit(order.id);
-
-    // Then: a confirmation email is queued
-    expect(emailQueue.messages).toContainEqual(
-      expect.objectContaining({
-        to: customer.email,
-        template: 'order-confirmation',
-        data: { orderId: order.id }
-      })
-    );
-  });
-});
-```
+### Test Doubles — Detailed Patterns
 
-### Test Doubles
+#### Stubs
 
-**Stubs:** Return predetermined responses. Use when you need to control what a dependency returns.
+Return predetermined responses. Use when you need to control what a dependency returns.
 
 ```typescript
 const userRepo = { findById: jest.fn().mockResolvedValue({ id: '1', name: 'Alice' }) };
 ```
 
-**Mocks:** Record calls and verify interactions. Use when you need to verify that a dependency was called correctly.
+#### Mocks
+
+Record calls and verify interactions. Use when you need to verify that a dependency was called correctly.
 
 ```typescript
 const emailService = { send: jest.fn() };
@@ -203,17 +187,22 @@ expect(emailService.send).toHaveBeenCalledWith({
 });
 ```
 
-**Spies:** Wrap real implementations and record calls. Use when you want real behavior but also want to verify calls.
+#### Spies
+
+Wrap real implementations and record calls. Use when you want real behavior but also want to verify calls.
+
+#### Fakes
 
-**Fakes:** Working implementations with simplified behavior. Use for expensive dependencies in tests (in-memory database instead of real database).
+Working implementations with simplified behavior. Use for expensive dependencies in tests (in-memory database instead of real database).
+
+#### When to Use Which
 
-**When to use which:**
 - Stub external services (HTTP APIs, email, payment)
 - Mock side-effect-producing dependencies (to verify they're called)
 - Spy on internal functions (to verify call patterns without changing behavior)
 - Fake databases in unit tests (in-memory implementations of repository interfaces)
 
-### What NOT to Mock
+### What NOT to Mock — Extended
 
 - **The thing you're testing.** If you mock the function under test, you're testing the mock, not the code.
 - **Value objects and simple data transformations.** Use real instances; they're fast and deterministic.
@@ -243,9 +232,9 @@ Verify that a service provider and its consumers agree on the API contract:
 
 Best for: microservices, separate frontend/backend teams, or any system where the API producer and consumer are developed independently.
 
-## Coverage Strategy
+### Coverage Strategy — In Depth
 
-### Coverage Targets by Layer
+#### Coverage Targets by Layer
 
 Coverage targets should vary by the criticality and testability of each layer:
 
@@ -257,7 +246,7 @@ Coverage targets should vary by the criticality and testability of each layer:
 | Infrastructure (adapters, config) | 50-70% line | Low logic density; over-testing adds maintenance burden |
 | Generated code | 0% | Don't test generated code; test the generator |
 
-### Meaningful vs. Vanity Coverage
+#### Meaningful vs. Vanity Coverage
 
 **Meaningful coverage** tests behavior that could break:
 - Branch coverage (both sides of every `if` statement)
@@ -283,9 +272,9 @@ Tools: Stryker (JavaScript/TypeScript), mutmut (Python), PITest (Java).
 
 Use mutation testing periodically (not on every CI run — it's slow) to assess test suite quality.
 
-## Quality Gates
+### Quality Gates — Detailed
 
-### Pre-Commit Checks
+#### Pre-Commit Checks
 
 Run on every commit (should complete in <10 seconds):
 
@@ -295,7 +284,7 @@ Run on every commit (should complete in <10 seconds):
 
 These are fast, catch obvious mistakes, and prevent noisy diffs in PRs.
 
-### CI Pipeline Checks
+#### CI Pipeline Checks
 
 Run on every push and PR (should complete in <5 minutes):
 
@@ -305,7 +294,7 @@ Run on every push and PR (should complete in <5 minutes):
 - **Build verification** (the application compiles and builds successfully)
 - **Security audit** (dependency vulnerability scan)
 
-### Pre-Merge Requirements
+#### Pre-Merge Requirements
 
 Before a PR can be merged:
 
@@ -314,7 +303,7 @@ Before a PR can be merged:
 - No merge conflicts
 - Branch is up-to-date with main (or rebased)
 
-### Performance Benchmarks (Optional)
+#### Performance Benchmarks (Optional)
 
 For performance-critical applications:
 
@@ -323,9 +312,9 @@ For performance-critical applications:
 - Significant regressions (>10% degradation) block merge
 - Baselines updated when intentional changes affect performance
 
-## Test Data
+### Test Data Management
 
-### Fixtures
+#### Fixtures
 
 Static test data stored in files or constants. Best for:
 - Reference data (country lists, category hierarchies, status enums)
@@ -347,7 +336,7 @@ export const adminUser = {
 };
 ```
 
-### Factories
+#### Factories
 
 Functions that generate test data with sensible defaults and selective overrides. Best for:
 - Creating many variations of the same entity
@@ -370,7 +359,7 @@ function createUser(overrides: Partial<User> = {}): User {
 const suspendedUser = createUser({ status: 'suspended' });
 ```
 
-### Seeds
+#### Seeds
 
 Initial data loaded into the test database for integration tests. Rules:
 - Seed data represents realistic scenarios (not just one record per table)
@@ -378,7 +367,7 @@ Initial data loaded into the test database for integration tests. Rules:
 - Seed data is minimal (only what tests need; don't replicate production)
 - Seed data includes edge cases (user with no orders, order with many items)
 
-### Test Database Management
+#### Test Database Management
 
 **Transaction rollback pattern:** Each test runs inside a database transaction that is rolled back after the test. Fast, clean, but doesn't test commit behavior.
 
@@ -388,7 +377,7 @@ Initial data loaded into the test database for integration tests. Rules:
 
 **Recommendation:** Use transaction rollback for unit-level database tests. Use truncate-and-seed for integration test suites. Use dedicated databases for CI.
 
-## Common Pitfalls
+### Common Pitfalls
 
 **Testing implementation details.** "Verify that `_processPayment` was called with exactly these parameters." This test breaks whenever the internal implementation changes, even if the observable behavior is unchanged. Fix: test the observable outcome, not the internal mechanism.
 
@@ -407,3 +396,7 @@ Initial data loaded into the test database for integration tests. Rules:
 **Skipped tests accumulate.** Tests marked as `skip` or `xit` that are never re-enabled. They represent either dead code or known bugs that nobody addresses. Fix: skipped tests are technical debt. Set a policy: fix or delete within one sprint.
 
 **No test naming convention.** Test descriptions like "test 1," "works correctly," or "handles the thing." Uninformative when tests fail. Fix: test names should describe the scenario and expected outcome: "returns 404 when user does not exist," "applies 10% discount for premium members."
+
+## See Also
+
+- [api-design](../core/api-design.md) — Contract testing patterns

package/knowledge/core/user-stories.md

@@ -4,16 +4,47 @@ description: Expert knowledge for translating product requirements into well-for
 topics: [user-stories, personas, acceptance-criteria, story-splitting, INVEST, epics, traceability]
 ---
 
-## Story Anatomy
+# User Stories
 
-The standard user story template captures who wants what and why:
+Expert knowledge for translating product requirements into well-formed user stories with acceptance criteria, epic structure, and traceability.
+
+## Summary
+
+### Story Anatomy
 
 **"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?"
+- **Persona** — the specific user role from the PRD, not "a user"
+- **Action** — what the user wants to do, in their language
+- **Outcome** — the value they get (the most important part)
+
+Deviations: **System stories** for background processes ("When a payment fails, the system retries twice...") and **Constraint stories** for NFRs ("All API responses within 500ms at p95").
+
+### INVEST Criteria
+
+- **Independent** — can be developed without requiring another story first
+- **Negotiable** — describes what/why, not how
+- **Valuable** — delivers value to a user or stakeholder
+- **Estimable** — specific enough to estimate effort
+- **Small** — implementable in 1-3 focused agent sessions
+- **Testable** — acceptance criteria have clear pass/fail outcomes
+
+### Acceptance Criteria Format
+
+Use Given/When/Then for scenarios:
+```
+Given [precondition/context]
+When [action/trigger]
+Then [expected outcome]
+```
+
+Include parameterized scenarios for role variations, negative scenarios for every happy path, and boundary conditions at edges.
+
+**AC vs. Test Cases**: ACs define WHAT should happen (business-level). Test cases define HOW to verify (technical-level, derived during implementation).
+
+## Deep Guidance
+
+### Story Anatomy — Extended
 
 **Good stories:**
 - "As a teacher, I want to assign homework to a class, so that students have practice material outside of class."
@@ -28,13 +59,9 @@ Each part serves a purpose:
 - **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
+### INVEST Criteria — Deep Dive
 
-Every story should satisfy INVEST. Use these criteria to evaluate story quality.
-
-### Independent
+#### 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.
 
@@ -42,7 +69,7 @@ The story can be developed and delivered without requiring another story to be d
 - **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
+#### Negotiable
 
 The story describes what and why, not how. Implementation details are negotiated during development, not locked in the story.
 
@@ -50,7 +77,7 @@ The story describes what and why, not how. Implementation details are negotiated
 - **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
+#### Valuable
 
 The story delivers value to a user or stakeholder. Every story should have a clear beneficiary.
 
@@ -58,7 +85,7 @@ The story delivers value to a user or stakeholder. Every story should have a cle
 - **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
+#### Estimable
 
 The team (or agent) can estimate the effort. If a story is too vague to estimate, it needs more conversation or splitting.
 
@@ -66,7 +93,7 @@ The team (or agent) can estimate the effort. If a story is too vague to estimate
 - **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
+#### Small
 
 A story should be implementable in 1-3 focused agent sessions. Larger stories need splitting.
 
@@ -74,7 +101,7 @@ A story should be implementable in 1-3 focused agent sessions. Larger stories ne
 - **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
+#### Testable
 
 Acceptance criteria have clear pass/fail outcomes. If you can't write a test for it, the story isn't ready.
 
@@ -82,9 +109,7 @@ Acceptance criteria have clear pass/fail outcomes. If you can't write a test for
 - **Fail:** "The checkout should be intuitive." — Not testable.
 - **Fix:** Replace subjective language with observable behavior.
 
----
-
-## Persona Definition
+### 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.
 
@@ -103,9 +128,7 @@ Personas are extracted from the PRD's user/stakeholder descriptions. Each person
 - **Pain points** — what frustrates them today (informs acceptance criteria)
 - **Context** — when, where, how they use the product (informs UX decisions)
 
----
-
-## Epic Structure
+### Epic Structure
 
 Epics group related stories by user journey, not by system component.
 
@@ -125,13 +148,9 @@ Epics group related stories by user journey, not by system component.
 - 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 Patterns — Extended
 
-Acceptance criteria define when a story is done. They are the contract between story and implementation.
-
-### Given/When/Then Format
+#### Given/When/Then Format
 
 The standard format for acceptance criteria scenarios:
 
@@ -148,7 +167,7 @@ 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
+#### Parameterized Scenarios
 
 When the same behavior applies to multiple variations, use parameterized scenarios:
 
@@ -158,7 +177,7 @@ When they access the settings page
 Then they see [all settings | team settings only | read-only view]
 ```
 
-### Negative Scenarios
+#### Negative Scenarios
 
 Every happy path should have corresponding error scenarios:
 
@@ -169,7 +188,7 @@ 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
+#### Boundary Conditions
 
 Test edges, not just middles:
 
@@ -181,19 +200,17 @@ 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 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
+### Story Splitting Heuristics
 
 When a story is too large, use these patterns to split it into smaller, independently valuable stories.
 
-### By Workflow Step
+#### By Workflow Step
 
 Before: "As a user, I want to complete the checkout process."
 After:
@@ -202,7 +219,7 @@ After:
 - "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
+#### By Data Variation
 
 Before: "As a user, I want to create posts."
 After:
@@ -210,7 +227,7 @@ After:
 - "As a user, I want to create posts with images."
 - "As a user, I want to create posts with embedded videos."
 
-### By Operation (CRUD)
+#### By Operation (CRUD)
 
 Before: "As an admin, I want to manage users."
 After:
@@ -219,7 +236,7 @@ After:
 - "As an admin, I want to edit user roles."
 - "As an admin, I want to deactivate user accounts."
 
-### By User Role
+#### By User Role
 
 Before: "As a user, I want to access the dashboard."
 After:
@@ -227,16 +244,14 @@ After:
 - "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
+#### 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
+### Scope Boundaries
 
 Every story should explicitly state what it does NOT include to prevent scope creep.
 
@@ -257,9 +272,7 @@ Every story should explicitly state what it does NOT include to prevent scope cr
 - "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
+### PRD-to-Story Traceability
 
 Every PRD feature must map to at least one user story. This is a non-negotiable coverage requirement.
 
@@ -283,9 +296,7 @@ Every PRD feature must map to at least one user story. This is a non-negotiable
 - 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
+### Story Dependencies
 
 Some stories must be implemented before others. Document these explicitly.
 
@@ -304,34 +315,32 @@ Only blocked-by dependencies should be formal constraints. Informed-by relations
 - 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
+### Common Pitfalls
 
-### Implementation Stories
+#### 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
+#### 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
+#### 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
+#### 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
+#### 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
+#### 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
+#### 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

@@ -4,6 +4,19 @@ description: Techniques for discovering UX enhancements and innovation opportuni
 topics: [innovation, ux-enhancements, user-stories, gap-analysis, differentiators]
 ---
 
+# User Story Innovation
+
+## Summary
+
+- **Scope**: UX-level improvements to existing features only (smart defaults, error handling, accessibility, progressive disclosure, AI-native enhancements). Feature-level innovation belongs in PRD innovation.
+- **High-value low-effort patterns**: Smart defaults, inline validation, keyboard shortcuts, progressive disclosure, leveraging existing data, undo/redo, and batch operations.
+- **Differentiators**: "Wow" moments, AI-native features (natural language search, auto-categorization, smart suggestions), and personalization without configuration.
+- **Defensive gaps**: Accessibility (WCAG AA minimum), mobile responsiveness, offline/degraded mode, performance under load, error recovery, and empty states.
+- **Evaluation framework**: Assess cost (trivial/moderate/significant) and impact (nice-to-have/noticeable/differentiator). Must-have for v1 = high impact + trivial or moderate cost.
+- **Integration**: Approved innovations become additional acceptance criteria, new stories, or modified story scope. All must be traceable to PRD requirements.
+
+## Deep Guidance
+
 ## 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.
@@ -169,3 +182,60 @@ Group related suggestions for efficient decision-making. For each group:
 2. State the cost (trivial/moderate/significant)
 3. State your recommendation (must-have/backlog/reject)
 4. Wait for approval before integrating into stories
+
+### Example Innovation Finding
+
+When documenting an innovation suggestion, use a structured format that makes the enhancement, its cost, and its impact immediately clear:
+
+```markdown
+## Innovation Finding: Smart Defaults for Checkout Address
+
+**Category:** High-Value Low-Effort Enhancement — Smart Defaults
+**Applies to:** Story 4.2 "As a returning customer, I want to enter my shipping address"
+
+**Current behavior:** User must re-enter full shipping address on every order, even
+if it has not changed since their last purchase.
+
+**Proposed enhancement:** Pre-fill shipping address from the user's most recent order.
+Show a "Same as last order" toggle that auto-populates all address fields. User can
+still edit any field after pre-fill.
+
+**User benefit:** Reduces a 6-field manual entry to a single click for repeat customers,
+which account for 65% of orders per the PRD's user research.
+
+**Cost:** Trivial — requires reading the most recent order's address (data already exists)
+and pre-populating form fields. No new API endpoints, no new database tables.
+
+**Impact:** Noticeable improvement — reduces checkout friction for the majority of users.
+Directly supports the PRD success metric "reduce checkout abandonment from 72% to 45%."
+
+**Recommendation:** Must-have for v1. High impact, trivial cost, directly tied to a
+success metric.
+
+**Acceptance criteria addition:**
+- Given a returning customer with a previous order,
+  when they reach the shipping address step,
+  then all address fields are pre-filled with their most recent shipping address
+- Given a new customer with no previous orders,
+  when they reach the shipping address step,
+  then all address fields are empty (current behavior)
+```
+
+---
+
+## Integration With User Stories
+
+When approved innovations are integrated into the story set, they modify stories in one of three ways:
+
+**Adding acceptance criteria** — The most common integration for trivial-cost enhancements. The innovation becomes additional acceptance criteria on an existing story.
+
+**Adding a new story** — For moderate-cost enhancements that warrant their own story. The new story should reference the innovation finding and include a clear "why" tying it back to the PRD.
+
+**Modifying an existing story's scope** — For enhancements that change how a feature works rather than adding to it. The original story's description and acceptance criteria are updated to reflect the enhanced behavior.
+
+### Traceability
+
+Every innovation that gets integrated must be traceable:
+- The innovation finding should reference the PRD requirement it enhances
+- The modified or new story should reference the innovation finding
+- The innovation decision (must-have/backlog/reject) should be recorded for audit