@zigrivers/scaffold 2.1.0

package/knowledge/review/review-system-architecture.md

@@ -0,0 +1,296 @@
+---
+name: review-system-architecture
+description: Failure modes and review passes specific to system architecture documents
+topics: [review, architecture, components, data-flow, modules]
+---
+
+# Review: System Architecture
+
+The system architecture document translates domain models and ADR decisions into a concrete component structure, data flows, and module organization. It is the primary reference for all subsequent phases — database schema, API contracts, UX spec, and implementation tasks all derive from it. Errors here propagate everywhere.
+
+This review uses 10 passes targeting the specific ways architecture documents fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Domain Model Coverage
+
+### What to Check
+
+Every domain model (entity, aggregate, bounded context) maps to at least one component or module in the architecture. No domain concept is left without an architectural home.
+
+### Why This Matters
+
+Unmapped domain concepts are features that have nowhere to live. When an implementing agent encounters a domain entity with no architectural home, it either creates an ad hoc module (fragmenting the architecture) or shoehorns it into an existing module (creating a god module). Both outcomes degrade system structure.
+
+### How to Check
+
+1. List every bounded context from domain models
+2. For each context, verify there is a corresponding module, service, or component in the architecture
+3. List every aggregate root within each context
+4. For each aggregate, verify its data and behavior are housed in the identified component
+5. Check that domain relationships (context map) are reflected in component interactions
+6. Verify that domain events map to communication channels between components
+
+### What a Finding Looks Like
+
+- P0: "Bounded context 'Notifications' from domain models has no corresponding component in the architecture. Six domain events reference notification delivery but no component handles them."
+- P1: "Aggregate 'SubscriptionPlan' is in domain models but its behavior is split between 'BillingService' and 'UserService' without clear ownership."
+- P2: "Domain event 'InventoryReserved' is documented but the architecture does not show which component publishes it."
+
+---
+
+## Pass 2: ADR Constraint Compliance
+
+### What to Check
+
+The architecture respects every accepted ADR decision. Technology choices, pattern decisions, and constraints documented in ADRs are reflected in the architecture.
+
+### Why This Matters
+
+ADRs are binding decisions. An architecture that ignores an ADR creates a contradiction that implementing agents must resolve on the fly. If ADR-005 says "PostgreSQL for all persistent data" but the architecture shows a MongoDB component, agents face a contradiction with no resolution path.
+
+### How to Check
+
+1. List every accepted ADR and its core decision
+2. For each ADR, trace its impact on the architecture: which components, data flows, or patterns does it constrain?
+3. Verify the architecture conforms to each constraint
+4. For ADRs with negative consequences, verify the architecture accounts for mitigation strategies
+5. Check that architectural patterns match ADR decisions (if ADR says "hexagonal architecture," verify port/adapter structure)
+6. Verify technology selections in the architecture match ADR technology decisions
+
+### What a Finding Looks Like
+
+- P0: "ADR-007 decides 'event-driven communication between bounded contexts' but the architecture shows synchronous REST calls between Order and Inventory services."
+- P1: "ADR-003 specifies 'monolith-first approach' but the architecture describes five separate services without explaining the planned extraction path."
+- P2: "ADR-011 notes 'caching adds invalidation complexity' as a negative consequence, but the architecture's caching component does not address invalidation strategy."
+
+---
+
+## Pass 3: Data Flow Completeness
+
+### What to Check
+
+Every component appears in at least one data flow. All data flows have a clear source, destination, protocol, and payload description. No orphaned components exist.
+
+### Why This Matters
+
+Components that appear in no data flow are either unnecessary (dead architecture) or have undocumented interactions (hidden coupling). Both are problems. Missing data flows mean the implementing agent does not know how data gets into or out of a component — they must invent the integration at implementation time.
+
+### How to Check
+
+1. List every component in the architecture
+2. For each component, verify it appears as source or destination in at least one data flow
+3. For each data flow, verify: source is a real component, destination is a real component, protocol/mechanism is specified (HTTP, events, database, file), data shape or payload is described
+4. Check for bidirectional flows that are only documented in one direction
+5. Verify error flows: what happens when a data flow fails? Is the error path documented?
+6. Check for external system interactions: are third-party APIs, external databases, or external services documented as data flow endpoints?
+
+### What a Finding Looks Like
+
+- P0: "Component 'AnalyticsEngine' appears in the component diagram but is not referenced in any data flow. It has no documented inputs or outputs."
+- P1: "Data flow from 'OrderService' to 'NotificationService' does not specify the communication mechanism. Is it synchronous HTTP, async events, or direct function calls?"
+- P2: "Error flow for payment processing failure is missing. What happens when the payment gateway returns an error? Where does the error propagate?"
+
+---
+
+## Pass 4: Module Structure Integrity
+
+### What to Check
+
+The module/directory structure has no circular dependencies, reasonable sizes, clear boundaries, and follows the patterns specified in ADRs.
+
+### Why This Matters
+
+Circular module dependencies make the system impossible to build, test, or deploy independently. Overly large modules become maintenance nightmares. Unclear boundaries lead to feature leakage, where functionality drifts into the wrong module because the right one is ambiguous.
+
+### How to Check
+
+1. Trace the import/dependency direction between modules — draw the dependency graph
+2. Check for cycles in the dependency graph (A depends on B depends on C depends on A)
+3. Verify the dependency direction aligns with the domain model's upstream/downstream relationships
+4. Check module sizes: are any modules housing too many responsibilities? (More than one bounded context worth of functionality)
+5. Verify that shared/common modules are minimal — they tend to become dumping grounds
+6. Check that the file/directory structure matches the module boundaries (not split across directories or merged into one)
+
+### What a Finding Looks Like
+
+- P0: "'auth' module imports from 'orders' module, and 'orders' module imports from 'auth'. This circular dependency must be broken — introduce an interface or event."
+- P1: "The 'core' module contains entities from three different bounded contexts. It should be split to maintain domain boundaries."
+- P2: "The 'utils' module has grown to 15 files. Consider whether these utilities belong in the modules that use them."
+
+---
+
+## Pass 5: State Consistency
+
+### What to Check
+
+State management design covers all identified state stores and their interactions. State transitions are consistent with domain events. No state is managed in two places without synchronization.
+
+### Why This Matters
+
+Inconsistent state is the source of the most difficult-to-debug production issues. When the same conceptual state is managed in two places (database and cache, two services, client and server), they drift apart. State management must be explicit about what is the source of truth and how consistency is maintained.
+
+### How to Check
+
+1. List every state store in the architecture (databases, caches, session stores, client-side state, queues)
+2. For each state store, identify what data it holds and which component owns it
+3. Check for the same data appearing in multiple stores — is synchronization documented?
+4. Verify that state transitions correspond to domain events
+5. Check for derived state: is it cached? How is it invalidated?
+6. Look for implicit state: component memory, local files, environment variables that hold state between requests
+
+### What a Finding Looks Like
+
+- P0: "User preferences are stored in both the UserService database and a client-side cache with no documented synchronization mechanism. These will drift."
+- P1: "Order status is derived from the last OrderEvent, but the architecture also shows an 'order_status' column in the orders table. Two sources of truth."
+- P2: "Session state is described as 'in-memory' but the deployment section mentions multiple instances. In-memory session state does not work with horizontal scaling."
+
+---
+
+## Pass 6: Diagram/Prose Consistency
+
+### What to Check
+
+Architecture diagrams and narrative prose describe the same system. Component names match. Relationships match. No components appear in diagrams but not prose, or vice versa.
+
+### Why This Matters
+
+Diagrams and prose inevitably drift when maintained independently. Implementing agents read both and expect them to agree. When a diagram shows four services but the prose describes three, the agent does not know which is correct. Consistent diagram/prose is the minimum bar for a trustworthy architecture document.
+
+### How to Check
+
+1. List every component named in diagrams
+2. List every component named in prose
+3. Verify 1:1 correspondence — every diagrammed component has a prose description, every prose-described component appears in a diagram
+4. Check component names: do diagrams and prose use the same names?
+5. Check relationships: do diagrams and prose describe the same connections between components?
+6. Check directionality: do arrows in diagrams match the dependency/data flow direction described in prose?
+
+### What a Finding Looks Like
+
+- P0: "The component diagram shows a 'Gateway' component that is not mentioned anywhere in the prose sections. Is this the API Gateway described in the 'Request Routing' section under a different name?"
+- P1: "The prose describes data flowing from Frontend to Backend to Database, but the data flow diagram shows Frontend connecting directly to Database for reads."
+- P2: "Component is called 'AuthService' in the diagram and 'Authentication Module' in the prose. Use one name."
+
+---
+
+## Pass 7: Extension Point Integrity
+
+### What to Check
+
+Extension points are designed with concrete interfaces, not merely listed. Each extension point specifies what can be extended, how to extend it, and what the constraints are.
+
+### Why This Matters
+
+"This is extensible" without design details is useless to implementing agents. They need to know the extension mechanism (plugin interface, middleware chain, event hooks, configuration), the contract (what an extension receives, what it returns, what it must not do), and examples of intended extensions.
+
+### How to Check
+
+1. List all claimed extension points in the architecture
+2. For each, check: is there a concrete interface or contract? (Not just "this module is extensible")
+3. Verify the extension mechanism is specified: plugin pattern, event hooks, middleware, strategy pattern, etc.
+4. Check that the extension contract is clear: what inputs, what outputs, what side effects are allowed?
+5. Verify at least one example use case for each extension point
+6. Check that extension points align with likely future requirements from the PRD
+
+### What a Finding Looks Like
+
+- P1: "Architecture says 'the payment system supports multiple payment providers via plugins' but does not define the plugin interface, lifecycle, or registration mechanism."
+- P1: "Authentication extension point lists 'social login providers can be added' but does not specify the provider interface or token exchange contract."
+- P2: "Notification extension point is well-designed but lacks an example of how a new channel (e.g., SMS) would be added."
+
+---
+
+## Pass 8: Invariant Verification
+
+### What to Check
+
+The architecture preserves domain invariants. Invariants identified in domain models are enforceable within the architecture's component and transaction boundaries.
+
+### Why This Matters
+
+An invariant that requires two components to coordinate atomically cannot be enforced if those components are separate services with no transaction mechanism. The architecture must ensure that invariant enforcement boundaries match component boundaries — or provide explicit mechanisms (sagas, compensating transactions) for cross-boundary invariants.
+
+### How to Check
+
+1. List every domain invariant from domain models
+2. For each invariant, identify which architectural component(s) are responsible for enforcing it
+3. If the invariant spans a single component, verify the component has access to all required state
+4. If the invariant spans multiple components, verify a coordination mechanism is documented (distributed transaction, saga, event-driven consistency)
+5. For cross-component invariants, check the consistency model: strong consistency (must be atomic) or eventual consistency (can tolerate temporary violations)?
+6. Verify that the consistency model aligns with the business tolerance stated in domain models
+
+### What a Finding Looks Like
+
+- P0: "Invariant 'order total must equal sum of line items minus discounts' requires Order and Pricing data, but these are in separate services with no documented coordination mechanism."
+- P1: "Invariant 'user cannot have duplicate email' spans UserService and AuthService. Which service enforces this? What happens if both create a user simultaneously?"
+- P2: "Invariant enforcement is documented but the consistency model (strong vs. eventual) is not specified."
+
+---
+
+## Pass 9: Downstream Readiness
+
+### What to Check
+
+Downstream steps (database schema, API contracts, UX spec, implementation tasks) can proceed with this architecture document.
+
+### Why This Matters
+
+Four phases consume the architecture document simultaneously or in rapid succession. Gaps in the architecture create cascading ambiguity across all four downstream phases.
+
+### How to Check
+
+The database schema step needs:
+1. Data storage components identified with their technology and role
+2. Entity-to-storage mapping clear enough to design tables/collections
+3. Data relationships explicit enough to define foreign keys or references
+
+The API contracts step needs:
+1. Component interfaces defined at operation level
+2. Communication protocols specified (REST, GraphQL, gRPC)
+3. Auth/authz architecture clear enough to define per-endpoint requirements
+
+The UX spec step needs:
+1. Frontend component architecture defined
+2. State management approach specified
+3. API integration points identified from the frontend perspective
+
+The implementation tasks step needs:
+1. Module boundaries clear enough to define task scope
+2. Dependencies between modules explicit enough to define task ordering
+3. Component complexity visible enough to estimate task sizing
+
+### What a Finding Looks Like
+
+- P0: "No data storage architecture section. The database schema step cannot begin database design without knowing what databases exist and what data each holds."
+- P1: "Frontend architecture section describes 'a React app' without component structure. The UX spec step needs at least a high-level component hierarchy."
+- P2: "Module dependencies are clear but not explicitly listed in a format that the implementation tasks step can directly use for task dependency ordering."
+
+---
+
+## Pass 10: Internal Consistency
+
+### What to Check
+
+Terminology, cross-references, and structural claims are internally consistent. The document does not contradict itself.
+
+### Why This Matters
+
+Architecture documents are long. Inconsistencies between early and late sections indicate that the document was written incrementally without reconciliation passes. Each inconsistency is a potential source of confusion for implementing agents.
+
+### How to Check
+
+1. Build a terminology list from the document — every component name, pattern name, and technology reference
+2. Check for variant names (same component called different things in different sections)
+3. Verify cross-references: when one section says "as described in the Data Flow section," check that the Data Flow section actually describes it
+4. Check for quantitative consistency: if Section 2 says "three services" and Section 5 describes four, which is correct?
+5. Verify that the module structure section and the component diagram describe the same set of modules
+6. Check that technology versions, library names, and tool references are consistent throughout
+
+### What a Finding Looks Like
+
+- P1: "Section 3 describes the system as having five microservices, but the component diagram shows six. The 'Scheduler' component appears in the diagram but not in the prose."
+- P1: "The architecture uses 'API Gateway' in sections 2-4 and 'Reverse Proxy' in section 6 for what appears to be the same component."
+- P2: "Node.js version is stated as 18 in section 1 and 20 in the deployment section."

package/knowledge/review/review-testing-strategy.md

@@ -0,0 +1,176 @@
+---
+name: review-testing-strategy
+description: Failure modes and review passes specific to testing and quality strategy artifacts
+topics: [review, testing, quality, coverage, test-pyramid]
+---
+
+# Review: Testing Strategy
+
+The testing strategy defines how the system will be verified at every layer. It must cover unit tests through end-to-end tests, address domain-specific invariants, align with the architecture's component boundaries, and define quality gates for CI/CD. This review uses 6 passes targeting the specific ways testing strategies fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Coverage Gaps by Layer
+
+### What to Check
+
+Each architectural layer (domain logic, application services, API, database, frontend, integration points) has test coverage defined. The test pyramid is balanced — not top-heavy (too many E2E tests) or bottom-heavy (unit tests only, no integration).
+
+### Why This Matters
+
+Missing test coverage at any layer creates a blind spot where bugs hide. Too many E2E tests create slow, flaky test suites that developers disable. Too few integration tests mean components work in isolation but fail when connected. The testing strategy must specify what gets tested at which level with clear rationale.
+
+### How to Check
+
+1. List every architectural layer from the system architecture
+2. For each layer, verify the testing strategy specifies: what types of tests, what the tests verify, approximate coverage expectations
+3. Check the test pyramid balance: unit tests should be most numerous, integration tests fewer, E2E tests fewest
+4. Verify that each layer's test scope matches its architectural responsibility
+5. Check for layers with no test coverage defined — these are the blind spots
+6. Verify that the testing strategy addresses external dependencies: how are third-party APIs, databases, and services handled in tests? (Mocks, test doubles, contract tests, testcontainers)
+
+### What a Finding Looks Like
+
+- P0: "The database layer has no test coverage defined. No mention of schema validation tests, migration tests, or query correctness tests."
+- P1: "Testing strategy defines unit tests and E2E tests but no integration tests. Components are tested in isolation and in full-system context, but never at the boundary — this misses component integration bugs."
+- P1: "External API dependencies (payment gateway, email service) have no test approach defined. Are they mocked? Stubbed? Is there a contract test?"
+- P2: "Test pyramid is inverted: 50 E2E tests, 20 integration tests, 15 unit tests. This will produce a slow, flaky test suite."
+
+---
+
+## Pass 2: Domain Invariant Test Cases
+
+### What to Check
+
+Every domain invariant from the domain models has at least one corresponding test scenario defined. Invariants are the highest-value test targets because they define business correctness.
+
+### Why This Matters
+
+Domain invariants are the rules the business cannot tolerate being violated. If the invariant "order total must equal sum of line items minus discounts" is not tested, a calculation bug could ship to production. Invariant violations are often the most expensive production bugs — they corrupt data, break financial calculations, or violate regulatory requirements.
+
+### How to Check
+
+1. List every domain invariant from the domain models
+2. For each invariant, find at least one test scenario in the testing strategy
+3. Check that test scenarios cover both the positive case (invariant holds) and negative case (invariant is violated — system rejects the operation)
+4. Verify that edge cases are considered: boundary values, null/empty inputs, concurrent modifications
+5. Check for invariants that span multiple aggregates — these need integration-level tests, not just unit tests
+6. Verify that invariant tests are classified at the correct pyramid level: aggregate-internal invariants at unit level, cross-aggregate invariants at integration level
+
+### What a Finding Looks Like
+
+- P0: "Domain invariant 'account balance cannot be negative' has no corresponding test scenario. This is a financial correctness requirement that must be tested."
+- P1: "Invariant 'email must be unique per tenant' has a unit test scenario but no integration test. The unit test mocks the uniqueness check — only an integration test against the real database can verify the constraint."
+- P2: "Invariant 'order must have at least one line item' has a positive test but no negative test (what happens when creating an order with zero items)."
+
+---
+
+## Pass 3: Test Environment Assumptions
+
+### What to Check
+
+The test environment described in the strategy matches production constraints. Database versions, service configurations, and external dependency behavior in tests reflect what will exist in production.
+
+### Why This Matters
+
+Tests that pass against SQLite but fail against PostgreSQL. Tests that mock a payment gateway's happy path but never test the timeout behavior that will happen in production. Test environment mismatches are the primary reason "tests pass, production breaks." The testing strategy must be explicit about how the test environment relates to production.
+
+### How to Check
+
+1. Compare the test database to the production database: same engine? Same version? Same configuration?
+2. Check external service test doubles: do they replicate the real service's behavior, including errors, latency, and edge cases?
+3. Verify that test data represents realistic production conditions: data volumes, data shapes, edge case values
+4. Check for environment-specific behavior: timezone handling, locale, file system paths, network configuration
+5. Verify that CI/CD test environment is specified and matches local test environment
+6. Check for assumptions about test ordering or test isolation — are tests truly independent?
+
+### What a Finding Looks Like
+
+- P0: "Tests run against SQLite but production uses PostgreSQL. SQLite and PostgreSQL have different type systems, different locking behavior, and different SQL dialect support. Tests will pass locally and fail in production."
+- P1: "Payment gateway is mocked to always return success. No test scenario covers timeout, network error, or declined payment — all common production scenarios."
+- P2: "Test data uses 5 records per table but production will have millions. Performance-sensitive queries are not tested at scale."
+
+---
+
+## Pass 4: Performance Test Coverage
+
+### What to Check
+
+Performance-critical paths identified in the PRD or architecture have benchmarks defined. Load testing, stress testing, and latency requirements have corresponding test scenarios.
+
+### Why This Matters
+
+Performance requirements stated in the PRD ("sub-200ms API response," "handle 1000 concurrent users") are meaningless without tests that verify them. Performance regressions are invisible to functional tests — the system still returns correct results, just slowly. By the time performance issues are discovered in production, the fix often requires architectural changes.
+
+### How to Check
+
+1. List performance requirements from the PRD and architecture (response time, throughput, concurrent users, data volume)
+2. For each requirement, find a corresponding performance test scenario
+3. Verify that benchmarks have specific thresholds (not "should be fast" but "95th percentile response time < 200ms")
+4. Check for load testing: is the expected concurrent user load tested?
+5. Check for stress testing: what happens beyond expected load? (Graceful degradation vs. crash)
+6. Verify that performance tests run in an environment representative of production (not a developer laptop)
+7. Check for performance regression detection: are benchmarks tracked over time?
+
+### What a Finding Looks Like
+
+- P0: "PRD requires 'sub-200ms response time for search queries' but no performance test scenario exists. There is no way to verify this requirement is met."
+- P1: "Load testing scenario exists for 100 concurrent users, but the PRD targets 10,000. The test does not verify the actual requirement."
+- P2: "Performance tests exist but have no regression tracking. A performance degradation from a code change will not be detected until it reaches production."
+
+---
+
+## Pass 5: Integration Boundary Coverage
+
+### What to Check
+
+All component integration points have integration tests defined. Every API call between services, every database query pattern, every message queue interaction has a test at the integration level.
+
+### Why This Matters
+
+Integration boundaries are where bugs hide. Each component may work perfectly in isolation (unit tests pass) but fail when connected to another component due to serialization mismatches, protocol errors, authentication failures, or contract violations. Integration tests catch these by testing real component interactions.
+
+### How to Check
+
+1. List every integration point from the architecture: service-to-service calls, database queries, message queue producers/consumers, external API integrations
+2. For each integration point, verify a test scenario exists at the integration level
+3. Check that integration tests use real (or realistic) dependencies, not mocks (that is what unit tests are for)
+4. Verify that contract tests exist for external APIs: when the external API changes, do tests catch the break?
+5. Check for async integration points (message queues, webhooks): are these tested with real async behavior, including ordering, retry, and failure scenarios?
+6. Verify that database integration tests cover actual query execution (not mocked repositories)
+
+### What a Finding Looks Like
+
+- P0: "OrderService calls InventoryService to reserve stock, but no integration test verifies this interaction. If the request format changes, the break is undetected."
+- P1: "Database repository tests mock the database connection. There are no tests that execute actual SQL against a real database — schema errors, query syntax errors, and constraint violations are invisible."
+- P2: "Event consumer integration tests verify message processing but not message ordering or duplicate handling."
+
+---
+
+## Pass 6: Quality Gate Completeness
+
+### What to Check
+
+The CI pipeline quality gates catch all intended issues before code reaches production. Gates cover linting, type checking, unit tests, integration tests, security scanning, and any project-specific checks.
+
+### Why This Matters
+
+A quality gate that exists in documentation but not in CI is not a gate. If the testing strategy says "all code must pass linting" but the CI pipeline does not run a linter, the gate is aspirational. Quality gates must be concrete: what tool, what configuration, what threshold, what happens on failure.
+
+### How to Check
+
+1. List every quality requirement from the testing strategy (code coverage thresholds, linting rules, type checking, security scanning)
+2. For each requirement, verify it maps to a specific CI pipeline step
+3. Check that gate failure blocks deployment (not just warns)
+4. Verify code coverage thresholds are specified and enforced: what percentage? Per file or overall? Is it a gate or a report?
+5. Check for security scanning: dependency vulnerability scanning, static analysis, secrets detection
+6. Verify that the gate order is correct: fast checks first (lint, type check), slow checks later (integration tests, E2E tests)
+7. Check for missing gates: database migration validation, API contract validation (schema against implementation), documentation generation
+
+### What a Finding Looks Like
+
+- P0: "Testing strategy requires 80% code coverage but the CI pipeline has no coverage reporting or enforcement. The requirement is unverifiable."
+- P1: "Security scanning is listed as a quality requirement but no specific tool or CI pipeline step implements it."
+- P2: "Quality gates run linting, unit tests, and integration tests, but do not validate database migrations. A broken migration would pass all gates and fail in production."

package/knowledge/review/review-user-stories.md

@@ -0,0 +1,172 @@
+---
+name: review-user-stories
+description: Failure modes and review passes specific to user story artifacts
+topics: [review, user-stories, coverage, acceptance-criteria, INVEST, testability]
+---
+
+# Review: User Stories
+
+User stories translate PRD requirements into user-facing behavior with testable acceptance criteria. Each story must be traceable back to the PRD, specific enough to implement, and consumable by downstream phases (domain modeling, UX specification, task decomposition). This review uses 6 passes targeting the specific ways user story artifacts fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: PRD Coverage
+
+### What to Check
+
+Every PRD feature, flow, and requirement has at least one corresponding user story. No PRD requirement is left without a story to implement it.
+
+### Why This Matters
+
+Missing stories mean missing implementation tasks downstream. A PRD feature with no story will not appear in the implementation tasks, will not be implemented, and will be discovered only during validation or user testing. Coverage gaps are the highest-severity story failure because they propagate silently through the entire pipeline.
+
+### How to Check
+
+1. Extract every distinct feature and requirement from the PRD (including implicit requirements like error handling, validation, accessibility)
+2. For each requirement, find the corresponding user story or stories
+3. Check that every PRD user persona has at least one story
+4. Check that every PRD user journey/flow has stories covering the complete path (not just the happy path)
+5. Flag any PRD requirement with no matching story
+6. Flag compound PRD requirements that should have been split into multiple stories
+
+### What a Finding Looks Like
+
+- P0: "PRD Section 4.2 describes a 'Team Invitation' feature with 3 user flows (invite by email, invite by link, bulk invite). No user stories exist for any of these flows."
+- P1: "PRD describes both SSO and email/password authentication. Stories exist for email/password only — SSO has no coverage."
+- P2: "PRD mentions 'accessibility compliance' as a requirement. No stories have accessibility-specific acceptance criteria."
+
+---
+
+## Pass 2: Acceptance Criteria Quality
+
+### What to Check
+
+Every story has testable, unambiguous acceptance criteria. Criteria should be specific enough that two different agents implementing the same story would produce functionally equivalent results.
+
+### Why This Matters
+
+Vague acceptance criteria produce vague tasks and untestable implementations. An agent reading "the feature should work correctly" has no way to know when it's done. Clear Given/When/Then criteria become test cases during implementation, ensuring the story is verifiably complete.
+
+### How to Check
+
+1. For each story, check that acceptance criteria exist (not blank or placeholder)
+2. Check that criteria use Given/When/Then format (at depth ≥ 3) or are otherwise structured and testable
+3. Check that criteria are specific — no subjective language ("intuitive," "fast," "user-friendly")
+4. Check that criteria cover the primary success path AND at least one error/edge case
+5. Check that criteria include boundary conditions where applicable (max lengths, empty states, concurrent access)
+6. Verify each criterion has a clear pass/fail condition — could an agent write an automated test for it?
+
+### What a Finding Looks Like
+
+- P0: "US-005 has no acceptance criteria at all. Cannot verify when this story is complete."
+- P1: "US-012 acceptance criteria says 'works correctly and is user-friendly' — not testable. Needs Given/When/Then scenarios."
+- P1: "US-018 covers only the happy path. No criteria for: invalid input, network failure, duplicate submission, session timeout."
+- P2: "US-031 criteria mention 'fast response time' without defining what fast means. Add a specific threshold (e.g., < 500ms at p95)."
+
+---
+
+## Pass 3: Story Independence
+
+### What to Check
+
+Stories can be implemented independently without hidden coupling. Dependencies between stories are explicit, not assumed.
+
+### Why This Matters
+
+Coupled stories create false parallelization opportunities. If two stories secretly share state or assume a specific implementation order, assigning them to parallel agents causes conflicts, rework, or subtle bugs. Explicit dependencies flow into task decomposition; hidden dependencies create surprises during implementation.
+
+### How to Check
+
+1. For each story, check if its acceptance criteria reference behavior defined in another story
+2. Check for shared state assumptions — two stories that both read or write the same data entity without acknowledging the overlap
+3. Check for implicit ordering — Story B's acceptance criteria assume Story A's output exists, but no dependency is documented
+4. Check for circular dependencies — Story A depends on B, and B depends on A
+5. Verify that documented dependencies are necessary (not just thematic grouping)
+
+### What a Finding Looks Like
+
+- P1: "US-008 (edit user profile) and US-009 (upload profile photo) both modify user profile state. Neither acknowledges the other. If implemented in parallel, they may conflict on the profile data model."
+- P1: "US-015 acceptance criteria says 'Given the user has completed onboarding' — this implicitly requires US-014 (onboarding flow) to be complete, but no dependency is documented."
+- P2: "US-025 and US-026 are listed as independent but share a 'notification preferences' data structure. Consider documenting the shared dependency."
+
+---
+
+## Pass 4: Persona Coverage
+
+### What to Check
+
+Every PRD-defined persona has stories representing their goals and workflows. Every story maps to a valid, defined persona.
+
+### Why This Matters
+
+Missing persona coverage means entire user segments have no stories, no tasks, and no implementation. Stories referencing undefined personas create confusion — agents don't know who they're building for, and acceptance criteria lack context.
+
+### How to Check
+
+1. List all personas defined in the PRD
+2. For each persona, count the stories attributed to them
+3. Flag personas with zero stories
+4. Flag stories that reference a persona not defined in the PRD
+5. Check that high-priority personas (primary users) have proportionally more stories than secondary personas
+6. Verify that each persona's PRD-defined goals are addressed by their stories
+
+### What a Finding Looks Like
+
+- P1: "PRD defines 4 personas: Student, Teacher, Admin, Parent. The 'Parent' persona has zero stories — their entire journey (viewing student progress, receiving notifications) is unaddressed."
+- P2: "US-020 is written as 'As a power user, I want...' but 'power user' is not a defined persona. Should this be 'Admin' or 'Teacher'?"
+- P2: "The 'Admin' persona has 2 stories, but the PRD describes 6 admin-specific features. 4 features have no admin story."
+
+---
+
+## Pass 5: Sizing & Splittability
+
+### What to Check
+
+No story is too large for a single agent session (1-3 focused sessions). No story is so small it adds unnecessary overhead. Stories that are too large should have obvious split points.
+
+### Why This Matters
+
+Oversized stories produce oversized tasks that exceed an agent's context window or session length. The agent either produces incomplete work or loses context partway through. Undersized stories create coordination overhead — each story needs its own review, testing, and integration cycle.
+
+### How to Check
+
+1. Count acceptance criteria per story — more than 8 suggests the story is too large
+2. Check if a story spans multiple workflows or user journeys — each journey should be its own story
+3. Check if a story covers multiple data variations that could be split (e.g., "create any type of post" → text, image, video)
+4. Check if a story handles both happy path and all error cases in one — consider splitting error handling into its own story
+5. Flag stories with only 1 trivial acceptance criterion — consider combining with a related story
+6. For oversized stories, identify the split heuristic that applies (workflow step, data variation, CRUD operation, user role, happy/sad path)
+
+### What a Finding Looks Like
+
+- P1: "US-003 has 12 acceptance criteria spanning 3 distinct workflows (create, edit, and archive projects). Split by operation into 3 stories."
+- P1: "US-017 covers the entire checkout flow (cart review, address, payment, confirmation) in one story. Split by workflow step."
+- P2: "US-022 ('update display name') and US-023 ('update email address') are trivially small and share the same profile editing context. Consider combining into 'edit profile fields.'"
+
+---
+
+## Pass 6: Downstream Readiness
+
+### What to Check
+
+The domain modeling step can consume these stories productively. Entities, events, and aggregate boundaries should be discoverable from story acceptance criteria without guesswork.
+
+### Why This Matters
+
+Stories are the primary input to domain discovery in the domain modeling step. If acceptance criteria are written at too high a level (no mention of data entities, no state transitions, no business rules), domain modeling has to infer the domain model from vague descriptions. This produces weaker domain models and increases the chance of misalignment between stories and architecture.
+
+### How to Check
+
+1. Sample 3-5 representative stories from different epics
+2. For each, attempt to identify: entities (nouns), domain events (state changes), and aggregate boundaries (transactional consistency requirements) from the acceptance criteria alone
+3. Check that the same entity is named consistently across stories (not "User" in one story and "Account" in another and "Member" in a third)
+4. Check that state transitions are explicit in the acceptance criteria — "when X happens, the order status changes from pending to confirmed" rather than "the order is processed"
+5. Check that business rules (invariants) appear in acceptance criteria — "a class cannot have more than 30 students" is discoverable; "class size is managed" is not
+
+### What a Finding Looks Like
+
+- P1: "US-007 ('As a teacher, I want to manage my classes') — acceptance criteria say 'classes are managed correctly.' No mention of what entities are involved (Class, Enrollment, Student?), what state transitions occur, or what business rules apply. Domain modeling will have to guess."
+- P2: "Cross-story entity naming is inconsistent: US-003 uses 'User,' US-008 uses 'Account,' US-015 uses 'Member.' These may be different bounded context terms or may be accidental inconsistency — clarify before domain modeling."
+- P2: "Stories in the 'Payments' epic mention 'processing a payment' but no acceptance criteria describe the payment lifecycle states (pending → processing → completed/failed). Domain events cannot be discovered from these stories."