@zigrivers/scaffold 2.1.0

package/knowledge/product/prd-innovation.md

@@ -0,0 +1,204 @@
+---
+name: prd-innovation
+description: Techniques for discovering feature-level innovation opportunities in product requirements
+topics: [innovation, prd, competitive-analysis, product-thinking, features]
+---
+
+# PRD Innovation
+
+This knowledge covers feature-level innovation — discovering new capabilities, competitive gaps, and defensive product improvements that belong in the PRD. It operates at the product scope level: should this feature exist at all?
+
+This is distinct from user story innovation (`user-story-innovation.md`), which covers UX-level enhancements to existing features. If an idea doesn't require a new PRD section or feature entry, it belongs in user story innovation, not here.
+
+## Scope Boundary
+
+**In scope:**
+- New features users would expect based on competitive norms
+- New user flows that address friction points in existing flows
+- Competitive positioning — capabilities that differentiate the product
+- Defensive product gaps — things users would complain about on day 1
+- AI-native capabilities that wouldn't exist without AI
+
+**Out of scope:**
+- UX polish on existing features (smart defaults, inline validation, progressive disclosure) — belongs in user story innovation
+- Implementation details (technology choices, architecture) — belongs in ADRs
+- Non-functional improvements to existing features — belongs in user story innovation
+
+---
+
+## Competitive & Market Analysis
+
+Research similar products to identify gaps and opportunities. The goal is actionable findings, not an exhaustive market report.
+
+### What to Research
+
+- **Direct competitors** — Products solving the same problem for the same users. What do they do well? What do users complain about?
+- **Adjacent products** — Products in the same space that solve related problems. What patterns do they use that users now expect?
+- **Emerging patterns** — UX conventions that have become table stakes. Users don't request them, but their absence feels like a gap (e.g., dark mode, keyboard shortcuts, real-time collaboration).
+
+### How to Use Findings
+
+For each competitive insight:
+1. Is this a table-stakes feature (users expect it)? → Must-have candidate
+2. Is this a differentiator (competitors don't have it, but users would love it)? → Evaluate cost/impact
+3. Is this a copied feature (competitors have it, but it doesn't serve our users' specific needs)? → Skip
+
+### Anti-Patterns
+
+- **Feature parity obsession** — Copying every competitor feature dilutes focus. Only adopt features that serve your users' specific problem.
+- **Exhaustive matrices** — A 50-row competitor comparison belongs in market research, not the PRD innovation pass. Focus on the 3-5 insights that actually affect product decisions.
+
+## User Experience Gaps
+
+Look at the core user flows described in the PRD and ask: where would a real user get frustrated?
+
+### First 60 Seconds
+
+The onboarding experience determines whether a user keeps the product:
+- Can a new user understand the product's value within 60 seconds?
+- Is there a clear first action? Or does the user land on an empty state with no guidance?
+- How many steps between signup and the first "aha moment" where the product delivers value?
+
+### Flow Friction Points
+
+For each core user flow:
+- How many steps does it take? Can any be eliminated or combined?
+- Are there unnecessary confirmation dialogs? (Prefer undo over "are you sure?")
+- Does the user need to leave the flow to get information required by the flow?
+- What's the "delightful" version of this flow versus the "functional" version?
+
+### Missing Flows
+
+- Are there common user goals that the PRD doesn't address with a dedicated flow?
+- Does the user have to work around the product to accomplish something obvious?
+
+## Missing Expected Features
+
+Features that users would search for and be surprised are absent. These are not innovative — they're expected. Their absence feels like a bug.
+
+### Common Missing Features by Category
+
+**Search & Discovery:**
+- Text search across primary content types
+- Filtering and sorting on list views
+- Recently viewed / recently used items
+
+**Data Management:**
+- Bulk import/export (CSV, JSON)
+- Undo for destructive actions
+- Duplicate/clone for repetitive creation
+
+**Communication:**
+- Notification preferences (what, when, how)
+- Email digests vs. real-time notifications
+- In-app notification center
+
+**Personalization:**
+- User preferences / settings
+- Saved views or filters
+- Customizable dashboard or home screen
+
+### Detection Technique
+
+For each persona in the PRD, walk through their typical week:
+1. What would they do daily? Weekly? Monthly?
+2. For each action, is there a feature that supports it?
+3. For each gap, would the user be surprised it's missing?
+
+## AI-Native Opportunities
+
+Features that would be impractical to build without AI but become natural with it. These are not "AI bolted on" — they are capabilities that fundamentally change the user experience.
+
+### Categories
+
+**Natural language interfaces:**
+- Search that understands intent ("show me overdue invoices from last quarter") rather than requiring structured queries
+- Data entry through conversation rather than forms for complex inputs
+- Commands that understand context ("send the same email I sent to the last batch")
+
+**Auto-categorization and tagging:**
+- Content automatically categorized based on content analysis
+- Suggested tags that learn from user corrections
+- Smart folders or views that organize themselves
+
+**Predictive behavior:**
+- Pre-filled forms based on patterns ("you usually set this to X")
+- Suggested next actions based on workflow patterns
+- Anomaly detection ("this value is unusual — did you mean X?")
+
+**Content generation:**
+- Draft generation for repetitive writing (emails, descriptions, reports)
+- Summarization of long content (meeting notes, documents, threads)
+- Template suggestions based on context
+
+### Evaluation
+
+AI features should pass the "magic vs. gimmick" test:
+- **Magic:** User thinks "how did it know?" and saves meaningful time
+- **Gimmick:** User thinks "that's cool" once and never uses it again
+- Only propose features that pass the magic test
+
+## Defensive Product Thinking
+
+Proactively identify what users would complain about. Fix the most likely complaints before they happen.
+
+### The 1-Star Review Technique
+
+Write the most likely 1-star review for the v1 product. Common templates:
+- "I can't believe it doesn't even have [obvious feature]."
+- "I tried to [common action] and it just [broke/was confusing/lost my data]."
+- "Great concept but unusable on [mobile/slow connection/screen reader]."
+- "I wanted to [goal] but had to [painful workaround] because [missing capability]."
+
+For each plausible 1-star review: is the complaint addressed in the PRD? If not, should it be?
+
+### Abandonment Analysis
+
+Identify the most common reasons a user would try the product and stop using it:
+1. **Complexity barrier** — Too hard to learn. Is onboarding addressed?
+2. **Performance barrier** — Too slow. Are performance NFRs adequate?
+3. **Trust barrier** — Doesn't feel reliable. Is error handling comprehensive?
+4. **Value barrier** — Doesn't deliver on the promise fast enough. Is time-to-value minimized?
+5. **Integration barrier** — Doesn't connect to their existing tools. Are integrations addressed?
+
+### Accessibility & Inclusion
+
+Gaps that alienate entire user segments:
+- Keyboard-only navigation for users who can't use a mouse
+- Screen reader support for visually impaired users
+- Mobile responsiveness for users on phones
+- Offline or degraded-mode support for users with unreliable connections
+- Internationalization for non-English-speaking users
+
+## Evaluation Framework
+
+For each innovation suggestion, evaluate before proposing to the user.
+
+### Cost Assessment
+
+- **Trivial** (no new features): A small addition to an existing PRD feature section. No new user flows, no new data entities.
+- **Moderate** (1-3 new features): Requires new PRD feature entries, possibly a new user flow. Contained within existing product scope.
+- **Significant** (reshapes scope): Requires rethinking product boundaries, adding new personas, or fundamentally changing architecture assumptions.
+
+### Impact Assessment
+
+- **Nice-to-have**: Users wouldn't notice if absent. Polishes the product but doesn't change adoption or satisfaction meaningfully.
+- **Noticeable improvement**: Users would appreciate it. Reduces friction in common workflows or addresses a gap competitors have filled.
+- **Significant differentiator**: Sets the product apart. Users would choose this product partly because of this capability.
+
+### Decision Framework
+
+| | Trivial Cost | Moderate Cost | Significant Cost |
+|---|---|---|---|
+| **Differentiator** | Must-have v1 | Must-have v1 | Backlog (worth it but not now) |
+| **Noticeable** | Must-have v1 | Backlog | Backlog |
+| **Nice-to-have** | Include if free | Backlog | Reject |
+
+### Presenting to the User
+
+Group related suggestions for efficient decision-making. For each group:
+1. Describe the enhancement and its user benefit (1-2 sentences)
+2. State the cost (trivial/moderate/significant)
+3. State your recommendation (must-have v1 / backlog / reject) with reasoning
+4. Wait for approval before integrating into the PRD
+5. Document approved innovations to the same standard as existing PRD features — full description, priority, business rules. No vague one-liners.

package/knowledge/review/review-adr.md

@@ -0,0 +1,203 @@
+---
+name: review-adr
+description: Failure modes and review passes specific to Architecture Decision Records
+topics: [review, adr, decisions]
+---
+
+# Review: Architecture Decision Records
+
+ADRs encode the "why" behind the architecture. They must be complete (every significant decision recorded), honest (genuine trade-off analysis), and non-contradictory (no two ADRs making incompatible decisions). This review uses 7 passes targeting the specific ways ADR sets fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Decision Coverage
+
+### What to Check
+
+Every significant architectural decision has an ADR. Technology choices, pattern selections, component boundaries, integration strategies, and constraint trade-offs are all recorded.
+
+### Why This Matters
+
+Unrecorded decisions become folklore — known to the original author but invisible to implementing agents. When an agent encounters an undocumented technology choice, it either assumes incorrectly or asks questions the ADR should have answered. At scale, unrecorded decisions are the primary source of "but why do we do it this way?" confusion.
+
+### How to Check
+
+1. Read through the domain models and architecture document (if it exists at this point)
+2. List every decision implied by the structure: technology choices (language, framework, database), architectural patterns (monolith vs. microservices, event-driven vs. request-response), component boundaries, integration mechanisms, data storage strategies
+3. For each identified decision, find the corresponding ADR
+4. Flag decisions that are visible in the artifacts but have no ADR
+5. Check that technology selection decisions cover: primary language/framework, database(s), key infrastructure (message queue, cache, CDN), deployment platform
+
+### What a Finding Looks Like
+
+- P0: "The architecture uses PostgreSQL and Redis but there is no ADR recording why these were chosen over alternatives."
+- P1: "The system uses event-driven communication between Order and Inventory services, but no ADR documents this pattern choice versus synchronous calls."
+- P2: "The testing framework choice (Jest) is implied by package.json conventions but not recorded as a decision."
+
+---
+
+## Pass 2: Rationale Quality
+
+### What to Check
+
+Each ADR has genuine alternatives that were seriously considered (not straw-manned). Consequences are honest — both positive and negative. The rationale explains why the chosen option was selected, not just what was selected.
+
+### Why This Matters
+
+Straw-manned alternatives ("we could do nothing" or obviously bad options) indicate the decision was made before the analysis. This means the real reasoning is undocumented. When conditions change, the team has no basis for re-evaluating because they do not know why the decision was actually made.
+
+### How to Check
+
+1. For each ADR, read the alternatives section
+2. Check that at least 2-3 alternatives are genuinely viable — would a reasonable engineer consider them?
+3. Verify each alternative has honest pros and cons (not just cons)
+4. Read the consequences section: are there negative consequences? (Every decision has trade-offs — all-positive consequences indicate dishonest analysis)
+5. Check the rationale: does it explain why the chosen option's trade-offs are acceptable, or does it just restate the decision?
+6. Look for evaluation criteria: what dimensions were the options compared on?
+
+### What a Finding Looks Like
+
+- P0: "ADR-003 lists 'do nothing' and 'use an obviously unsuitable technology' as alternatives. The real alternatives (comparable frameworks) are missing."
+- P1: "ADR-007 consequences section lists only benefits. A REST API decision always has trade-offs (chatty calls, over-fetching, versioning complexity) — these are absent."
+- P2: "ADR-012 explains what was chosen but not why. The rationale section reads 'We chose React' without explaining what made it the best fit."
+
+---
+
+## Pass 3: Contradiction Detection
+
+### What to Check
+
+No two ADRs make contradictory decisions without explicit acknowledgment. When one ADR supersedes or modifies another, the relationship is documented.
+
+### Why This Matters
+
+Contradictory ADRs give implementing agents conflicting instructions. If ADR-005 says "use REST for all APIs" and ADR-012 says "use GraphQL for the dashboard API" without referencing ADR-005, an agent reading both does not know which takes precedence. Contradictions that are intentional (scoped exceptions) must be explicit.
+
+### How to Check
+
+1. Build a decision matrix: for each ADR, note what it decides and what domain it constrains
+2. Look for overlapping constraints: two ADRs that affect the same architectural concern
+3. For each overlap, determine: do they agree, or do they contradict?
+4. For contradictions, check: does the later ADR reference the earlier one and explain the exception?
+5. Check for implicit contradictions: ADR-A says "minimize external dependencies" while ADR-B adds three new external services
+6. Verify supersession chains: if ADR-X supersedes ADR-Y, is ADR-Y marked as superseded?
+
+### What a Finding Looks Like
+
+- P0: "ADR-005 specifies 'all state in PostgreSQL' but ADR-011 introduces Redis for session management without referencing ADR-005 or explaining the exception."
+- P1: "ADR-003 (monolith-first) and ADR-009 (separate auth service) contradict. ADR-009 should reference ADR-003 and explain why auth is the exception."
+- P2: "ADR-015 supersedes ADR-008 but ADR-008 status is still 'accepted'. Update to 'superseded by ADR-015'."
+
+---
+
+## Pass 4: Implied Decision Mining
+
+### What to Check
+
+Decisions visible in domain models, architecture, or code that were never formally recorded as ADRs. These are the "everyone knows" decisions that new team members do not know.
+
+### Why This Matters
+
+Implied decisions are the most dangerous gap in an ADR set. They represent consensus that was never examined or documented. When an implementing agent encounters an implied decision, it has no rationale to evaluate whether the decision still applies. Implied decisions also tend to be the decisions most likely to be wrong — they were never subjected to alternatives analysis.
+
+### How to Check
+
+1. Read domain models looking for architectural assumptions: "the system uses X" statements embedded in narrative
+2. Read architecture documents for technology mentions without corresponding ADRs
+3. Check for pattern assumptions: "RESTful API" assumed without an ADR choosing REST over alternatives
+4. Look for constraint assumptions: "single database" or "multi-tenant" assumed without formal analysis
+5. Check for deployment assumptions: cloud provider, containerization, CI/CD tool — all are decisions
+6. Review domain event patterns: synchronous vs. asynchronous, at-least-once vs. exactly-once — these are decisions
+
+### What a Finding Looks Like
+
+- P0: "The domain models assume multi-tenancy (tenant_id on entities) but there is no ADR analyzing single-tenant vs. multi-tenant trade-offs."
+- P1: "The architecture assumes containerized deployment (Docker references throughout) but no ADR records this decision."
+- P2: "TypeScript is used throughout code examples in domain models but no ADR formally selects TypeScript over JavaScript."
+
+---
+
+## Pass 5: Status Hygiene
+
+### What to Check
+
+ADR statuses reflect reality. No stale "proposed" ADRs (should be accepted or rejected). Supersession chains are clean. Deprecated ADRs point to their replacements.
+
+### Why This Matters
+
+Stale statuses create confusion about which decisions are in effect. A "proposed" ADR that was accepted months ago but never updated looks like an undecided question. Broken supersession chains mean both the old and new ADR appear active, leading to the contradiction problems in Pass 3.
+
+### How to Check
+
+1. List all ADRs and their statuses
+2. Flag any "proposed" or "draft" ADRs — are these genuinely pending, or were they accepted but not updated?
+3. For "superseded" or "deprecated" ADRs, verify they reference their replacement
+4. For "accepted" ADRs, verify they are still current — has a later ADR effectively superseded them?
+5. Check for "rejected" ADRs — are the rejections still valid, or have circumstances changed?
+6. Verify ADR numbering is sequential and has no gaps (gaps suggest deleted ADRs, which violates ADR principles)
+
+### What a Finding Looks Like
+
+- P1: "ADR-004 has status 'proposed' but is referenced by three other ADRs as if it were accepted. Update status."
+- P1: "ADR-006 status is 'deprecated' but does not reference which ADR replaces it."
+- P2: "ADR numbering jumps from 008 to 010. If ADR-009 was removed, it should exist as 'rejected' or 'withdrawn', not deleted."
+
+---
+
+## Pass 6: Cross-Reference Integrity
+
+### What to Check
+
+ADRs that reference each other do so correctly. Cross-references point to real ADRs, the referenced content matches what is claimed, and no circular reference chains create logical loops.
+
+### Why This Matters
+
+Broken cross-references make it impossible to follow decision chains. When ADR-015 says "as decided in ADR-007," but ADR-007 does not actually address that topic, the rationale chain is broken. Implementing agents cannot trace why decisions were made.
+
+### How to Check
+
+1. For each ADR, extract all references to other ADRs
+2. Verify each referenced ADR exists
+3. Verify the referenced ADR actually says what the referencing ADR claims it says
+4. Check for circular reference chains (A references B references C references A)
+5. Verify "supersedes" relationships are bidirectional (superseding ADR says "supersedes X"; X says "superseded by Y")
+6. Check that references to domain models and architecture documents are also accurate
+
+### What a Finding Looks Like
+
+- P1: "ADR-012 says 'per ADR-007, we use event-driven communication' but ADR-007 actually decides on synchronous REST. Wrong cross-reference."
+- P1: "ADR-015 supersedes ADR-008, but ADR-008 does not mention being superseded."
+- P2: "ADR-020 references 'the data model in Section 3' without specifying which document's Section 3."
+
+---
+
+## Pass 7: Downstream Readiness
+
+### What to Check
+
+The system architecture step needs technology choices and pattern decisions finalized. All architecture-constraining decisions must be in "accepted" status with clear rationale.
+
+### Why This Matters
+
+The architecture document translates ADR decisions into component structure. If technology choices are unresolved, the architect must either make the decision inline (bypassing the ADR process) or leave the architecture ambiguous. Both lead to rework.
+
+### How to Check
+
+The system architecture step specifically needs:
+1. **Technology stack decisions** — Language, framework, database, key infrastructure, all accepted
+2. **Architectural pattern decisions** — Monolith vs. services, synchronous vs. asynchronous, state management approach
+3. **Integration pattern decisions** — How components communicate, what protocols, what data formats
+4. **Deployment topology decisions** — Where the system runs, how many environments, how deploys work
+5. **Cross-cutting concern decisions** — Logging, monitoring, authentication, error handling patterns
+6. **Data management decisions** — Single vs. multiple databases, caching strategy, data consistency model
+
+For each category, verify at least one accepted ADR covers it. If a category is intentionally deferred, verify the deferral is documented with a timeline.
+
+### What a Finding Looks Like
+
+- P0: "No accepted ADR covers database technology selection. The system architecture step cannot design data storage components without this decision."
+- P0: "The monolith-vs-services question has two proposed ADRs (ADR-003, ADR-004) but neither is accepted. The system architecture step cannot define component boundaries."
+- P1: "Authentication approach is not covered by any ADR. The system architecture step needs to know the auth pattern to design the auth component."
+- P2: "Monitoring strategy has no ADR. This could be deferred to the operations step but should be noted."

package/knowledge/review/review-api-contracts.md

@@ -0,0 +1,233 @@
+---
+name: review-api-contracts
+description: Failure modes and review passes specific to API contract specifications
+topics: [review, api, contracts, rest, graphql]
+---
+
+# Review: API Contracts
+
+API contracts define the system's external and internal interfaces. They must cover every domain operation that crosses a boundary, handle errors explicitly, enforce authentication and authorization, and align with both the domain model and the database schema. This review uses 8 passes targeting the specific ways API contracts fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Operation Coverage
+
+### What to Check
+
+Every domain operation that crosses a component boundary has a corresponding API endpoint (or GraphQL query/mutation, gRPC method, etc.). No cross-boundary operation is left without an API contract.
+
+### Why This Matters
+
+Missing endpoints mean entire features cannot be accessed through the API. Implementing agents discover the gap when they need to wire up a frontend component or integration — they either invent an endpoint (diverging from the contract) or block waiting for design. Operation coverage gaps are the most common API contract failure.
+
+### How to Check
+
+1. List every component interaction from the architecture's data flows
+2. For each interaction that crosses a component or service boundary, verify a corresponding API endpoint exists
+3. Cross-reference domain model operations: every aggregate command (create, update, delete) that is exposed beyond its owning service needs an endpoint
+4. Check for read operations: every query pattern identified in the architecture needs a corresponding GET endpoint or query
+5. Verify that domain events that trigger cross-service operations have corresponding webhook or event subscription endpoints if applicable
+6. Check for administrative operations: user management, configuration, health checks, metrics
+
+### What a Finding Looks Like
+
+- P0: "Architecture data flow shows 'Frontend requests user's order history' but no GET /users/{id}/orders endpoint exists in the API contract."
+- P1: "Domain model defines 'cancel order' as a command on the Order aggregate, but no PATCH/DELETE endpoint covers order cancellation."
+- P2: "Health check endpoint is not documented. Implementation will need one for deployment orchestration."
+
+---
+
+## Pass 2: Error Contract Completeness
+
+### What to Check
+
+Every endpoint has explicit error responses defined. Error responses include status codes, error body structure, and conditions under which each error occurs.
+
+### Why This Matters
+
+Undocumented errors are the primary source of poor error handling in client code. When the API returns a 422 that is not in the contract, the frontend falls back to a generic "something went wrong" message. Complete error contracts enable clients to handle every failure mode gracefully.
+
+### How to Check
+
+1. For each endpoint, list the documented error responses
+2. Check for standard errors every endpoint should handle: 400 (bad input), 401 (unauthenticated), 403 (unauthorized), 404 (not found), 500 (server error)
+3. Check for domain-specific errors: business rule violations (e.g., "insufficient inventory"), state transition errors (e.g., "cannot cancel a shipped order"), constraint violations (e.g., "duplicate email")
+4. Verify error response bodies have a consistent structure across all endpoints (error code, message, details)
+5. Check for rate limiting errors (429) if the API has rate limits
+6. Verify that error responses do not leak internal details (stack traces, database errors, internal IDs)
+
+### What a Finding Looks Like
+
+- P0: "POST /orders endpoint documents only 201 (success) and 400 (bad request). Missing: 401 (unauthenticated), 403 (not authorized to create orders), 409 (duplicate order reference), 422 (validation errors like 'inventory unavailable')."
+- P1: "Error response format varies between endpoints. /users returns {error: string} while /orders returns {code: number, message: string, details: object}. Standardize."
+- P2: "No endpoint documents a 429 (rate limited) response, but the architecture mentions rate limiting as a requirement."
+
+---
+
+## Pass 3: Auth/AuthZ Coverage
+
+### What to Check
+
+Every endpoint specifies its authentication requirements (who can call it) and authorization rules (what permissions are needed). No endpoint is left with ambiguous access control.
+
+### Why This Matters
+
+Endpoints without documented auth requirements default to "anyone can call this" in implementation. This is a security vulnerability when the endpoint should be restricted. Even internal service-to-service endpoints need auth documentation — "internal only, requires service token" is a valid auth specification.
+
+### How to Check
+
+1. For each endpoint, check for authentication specification: unauthenticated, user token, service token, API key, etc.
+2. For authenticated endpoints, check for authorization specification: what role, permission, or ownership is required?
+3. Verify that resource-ownership authorization is documented: "users can only access their own orders" (not just "requires user role")
+4. Check for admin/superuser endpoints: are they clearly distinguished from regular user endpoints?
+5. Verify that public endpoints are explicitly marked as public (not just missing auth — intentional vs. accidental)
+6. Check for cross-service authentication: how do services authenticate to each other?
+
+### What a Finding Looks Like
+
+- P0: "DELETE /users/{id} has no auth specification. Can any authenticated user delete any user? Only admins? Only the user themselves?"
+- P1: "GET /orders/{id} requires authentication but does not specify authorization. Can any authenticated user view any order, or only their own?"
+- P2: "Service-to-service endpoints (e.g., /internal/inventory/reserve) do not document the authentication mechanism. Are they protected by network isolation, service tokens, or mTLS?"
+
+---
+
+## Pass 4: Versioning Consistency
+
+### What to Check
+
+API versioning strategy is consistent across all endpoints and aligns with the ADR on API versioning. Version handling is explicit, not assumed.
+
+### Why This Matters
+
+Inconsistent versioning makes it impossible for clients to know which version they are consuming. If some endpoints use URL versioning (/v1/), others use header versioning (Accept: application/vnd.api.v1+json), and others have no versioning, client SDK generation and API gateway configuration become fragmented.
+
+### How to Check
+
+1. Find the ADR on API versioning strategy
+2. Verify every endpoint follows the same versioning scheme
+3. Check for endpoints with no version indicator — are they intentionally unversioned (health checks, root) or accidentally unversioned?
+4. If URL versioning is used, verify all paths include the version prefix
+5. Check for backward compatibility commitments: what changes are considered breaking?
+6. Verify that the contract documents how clients should handle version upgrades
+
+### What a Finding Looks Like
+
+- P1: "ADR-008 specifies URL-based versioning (/v1/), but three endpoints omit the version prefix: /health, /orders/webhook, /auth/token."
+- P1: "Some endpoints use /v1/ prefix and others use /api/v1/ prefix. Inconsistent path structure."
+- P2: "No documentation on what constitutes a breaking change versus a backward-compatible change. Clients do not know when to expect a version bump."
+
+---
+
+## Pass 5: Payload Shape vs Domain Entities
+
+### What to Check
+
+Request and response payloads align with domain model entities. Field names match domain terminology. Field types match domain attribute types. Payload structure reflects domain relationships.
+
+### Why This Matters
+
+Misalignment between API payloads and domain entities creates a translation layer that implementing agents must build and maintain. If the domain entity uses "orderedAt" but the API returns "created_date," every consumer must know about the mapping. Alignment reduces cognitive load and bug surface.
+
+### How to Check
+
+1. For each endpoint, compare request/response fields to the corresponding domain entity attributes
+2. Check field names: do they match domain terminology (ubiquitous language)?
+3. Check field types: if the domain model says "Money" (amount + currency), does the API represent it the same way or split/merge fields?
+4. Check nested structures: do response shapes reflect domain aggregate boundaries?
+5. Verify that API responses do not expose internal database fields (auto-increment IDs, internal status codes, audit columns) unless intentional
+6. Check for missing fields: domain entity attributes that are absent from the API response (may be intentional for security, or may be a gap)
+
+### What a Finding Looks Like
+
+- P1: "Domain entity 'Order' uses 'placedAt' (DateTime) but API response uses 'createdDate' (string). Name mismatch and type mismatch."
+- P1: "Domain entity 'Product' has a 'price' attribute modeled as Money (amount + currency), but the API returns 'price' as a plain number with no currency. Multi-currency support will break."
+- P2: "API response includes 'internal_status_code' field which is a database implementation detail, not a domain concept."
+
+---
+
+## Pass 6: Idempotency
+
+### What to Check
+
+Mutating operations (POST, PUT, PATCH, DELETE) document their idempotency behavior. Operations that should be idempotent specify the mechanism (idempotency keys, natural idempotency).
+
+### Why This Matters
+
+Non-idempotent operations cause duplicate side effects on retry. If a client retries a failed POST /orders (network timeout, unclear response), the system may create two orders. Idempotency documentation tells client developers whether they can safely retry and how to do so.
+
+### How to Check
+
+1. For each POST endpoint, check: is it idempotent? If yes, what mechanism (idempotency key header, natural deduplication by business key)?
+2. For each PUT endpoint, verify it is naturally idempotent (same PUT produces the same result)
+3. For each PATCH endpoint, check if idempotency depends on the specific operation (appending to a list is not idempotent; setting a value is)
+4. For each DELETE endpoint, verify behavior on repeated calls (first call deletes, subsequent calls return 404 or 204?)
+5. Check for operations with side effects (sending emails, charging payments) — these must be idempotent or explicitly documented as non-idempotent
+6. Verify that the idempotency mechanism is documented for clients: what header to send, how long the idempotency key is valid, what happens on key reuse
+
+### What a Finding Looks Like
+
+- P0: "POST /payments/charge has no idempotency specification. A client retry could charge the customer twice."
+- P1: "POST /orders documents an idempotency key mechanism but does not specify the header name, key format, or expiration window."
+- P2: "DELETE /orders/{id} does not specify behavior on repeated calls. Does the second DELETE return 404 (resource not found) or 204 (success, already deleted)?"
+
+---
+
+## Pass 7: Pagination/Filtering
+
+### What to Check
+
+List endpoints have pagination designed. Filter and sort parameters are documented. Response includes pagination metadata.
+
+### Why This Matters
+
+Unpaginated list endpoints return unbounded result sets. In development this works fine; in production with thousands of records, a single unpaginated call can crash the server or the client. Pagination must be designed, not retrofitted — retrofitting changes the API contract and breaks existing clients.
+
+### How to Check
+
+1. Identify every list/collection endpoint (GET endpoints returning arrays)
+2. Verify each has pagination parameters documented (page/size, cursor-based, or offset/limit)
+3. Check that pagination response includes metadata: total count (or has-next indicator), current page/cursor, page size
+4. Verify that filter parameters are documented for common query patterns (identified in architecture data flows)
+5. Check sort parameters: which fields can be sorted on? What is the default sort order?
+6. Verify maximum page size is specified and enforced (prevents clients requesting 10,000 records)
+7. For cursor-based pagination, check that cursor format and stability guarantees are documented
+
+### What a Finding Looks Like
+
+- P0: "GET /orders returns all orders with no pagination parameters. With 100,000 orders, this endpoint will timeout or crash."
+- P1: "GET /products has pagination (page, size) but no filter parameters. The architecture's data flow shows 'search products by category and price range' as a primary use case."
+- P2: "Pagination response includes 'total_count' but does not specify whether this is an exact count or an estimate (important for large datasets)."
+
+---
+
+## Pass 8: Downstream Readiness
+
+### What to Check
+
+The UX spec and implementation tasks steps can proceed with these API contracts. The API provides everything needed to build frontend interactions and define backend tasks.
+
+### Why This Matters
+
+The UX spec needs to know what data is available from the API to design screens. Implementation tasks need to know the API surface to scope work. Gaps in the API contract create ambiguity in both downstream phases.
+
+### How to Check
+
+The UX spec step needs:
+1. Every user-facing action has a corresponding API endpoint
+2. Response shapes are detailed enough to design screen layouts (know what fields are available)
+3. Error responses are documented enough to design error states
+4. Loading states are inferable: which operations are fast (synchronous) vs. slow (async with polling)?
+
+The implementation tasks step needs:
+1. Endpoint complexity is visible: which endpoints are simple CRUD, which require complex business logic?
+2. Dependencies between endpoints are clear: which endpoints must be built first?
+3. Integration points with external services are specified
+4. Authentication/authorization requirements are detailed enough to implement
+
+### What a Finding Looks Like
+
+- P0: "The UX wireframe shows a 'user dashboard' with order count, recent orders, and account balance, but the API has no endpoint that provides this aggregated data. The frontend would need to make 3+ separate calls."
+- P1: "Several endpoints are marked as 'async' (returns 202) but there is no documented polling or webhook mechanism for the frontend to get the result."
+- P2: "API response examples do not include null/empty cases. The UX spec needs to know what an empty order list or a user with no profile photo looks like in API terms."