@zigrivers/scaffold 2.1.0

package/knowledge/review/review-implementation-tasks.md

@@ -0,0 +1,202 @@
+---
+name: review-implementation-tasks
+description: Failure modes and review passes specific to implementation tasks artifacts
+topics: [review, tasks, planning, decomposition, agents]
+---
+
+# Review: Implementation Tasks
+
+The implementation tasks document translates the architecture into discrete, actionable work items that AI agents can execute. Each task must be self-contained enough for a single agent session, correctly ordered by dependency, and clear enough to implement without asking questions. This review uses 7 passes targeting the specific ways implementation tasks fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Architecture Coverage
+
+### What to Check
+
+Every architectural component, module, and integration point has corresponding implementation tasks. No part of the architecture is left without work items.
+
+### Why This Matters
+
+Uncovered components are discovered during implementation when an agent realizes a dependency has no task. This blocks the agent, creates unplanned work, and disrupts the critical path. Coverage gaps typically occur in cross-cutting concerns (logging, error handling, auth middleware) and infrastructure (CI/CD, deployment, database migrations).
+
+### How to Check
+
+1. List every component from the system architecture document
+2. For each component, find implementation tasks that cover it
+3. Flag components with no corresponding tasks
+4. Check cross-cutting concerns: logging, error handling, authentication/authorization middleware, configuration management, health checks
+5. Check infrastructure tasks: database migration scripts, CI/CD pipeline setup, deployment configuration, environment setup
+6. Check integration tasks: component-to-component wiring, API client generation, event bus configuration
+7. Verify that testing tasks exist alongside implementation tasks (not deferred to "later")
+
+### What a Finding Looks Like
+
+- P0: "Architecture describes an 'API Gateway' component with routing, rate limiting, and auth validation, but no implementation tasks exist for it. Five downstream tasks assume it exists."
+- P1: "Database migration tasks cover schema creation but no task covers seed data or test fixtures. The testing strategy requires test data."
+- P2: "Logging infrastructure is mentioned in architecture but has no dedicated task. Individual component tasks may handle it ad hoc, creating inconsistent logging."
+
+---
+
+## Pass 2: Missing Dependencies
+
+### What to Check
+
+Task dependencies are complete and correct. No task assumes a prerequisite that is not listed as a dependency. No circular dependencies exist.
+
+### Why This Matters
+
+Missing dependencies cause agents to start work that immediately blocks — the agent picks up a task, discovers it depends on something not yet built, and wastes a session. Circular dependencies make it impossible to determine a valid execution order. Both destroy parallelization efficiency.
+
+### How to Check
+
+1. For each task, read its description and acceptance criteria
+2. Identify everything the task needs to exist before it can start (database tables, API endpoints, shared libraries, configuration)
+3. Verify each prerequisite is listed as a dependency
+4. Check for implicit dependencies: "implement user dashboard" implicitly depends on "implement user authentication" — is this explicit?
+5. Build the full dependency graph and check for cycles
+6. Verify that the dependency graph has at least one task with no dependencies (the starting point)
+7. Check for over-specified dependencies: tasks blocked on things they do not actually need, creating artificial bottlenecks
+
+### What a Finding Looks Like
+
+- P0: "Task 'Implement order API endpoints' has no dependency on 'Create database schema.' The API task cannot start without tables to query."
+- P1: "Tasks 'Implement user service' and 'Implement auth middleware' depend on each other. Circular dependency — determine which can be built first with a mock."
+- P2: "Task 'Build product listing page' lists 'Deploy staging environment' as a dependency. This is over-specified — the page can be built and tested locally."
+
+---
+
+## Pass 3: Task Sizing
+
+### What to Check
+
+No task is too large for a single agent session (typically 30-60 minutes of focused work). No task is too small to be meaningful (trivial one-line changes should be grouped). Tasks have a clear scope boundary.
+
+### Why This Matters
+
+Too-large tasks exceed agent context windows and session limits. The agent runs out of context mid-task, produces incomplete work, and the next session must understand and continue partial progress — which is error-prone. Too-small tasks create overhead (setup, context loading, validation) that exceeds the actual work.
+
+### How to Check
+
+1. For each task, estimate the implementation scope: how many files touched, how many functions written, how much logic?
+2. Flag tasks that involve more than one major component or module — these are likely too large
+3. Flag tasks that involve more than 5-7 files — these may exceed agent context
+4. Flag tasks that are trivial (rename a variable, update a config value) — these should be grouped into a larger task
+5. Check that each task has a clear boundary: when does the agent stop? "Implement the order module" has no clear boundary; "Implement order creation endpoint with validation" does
+6. Verify that tasks do not mix concerns: a single task should not be "implement auth AND set up database"
+
+### What a Finding Looks Like
+
+- P0: "Task 'Implement the entire backend' is a single task covering 15 architectural components, 40+ files, and hundreds of functions. This must be decomposed into component-level tasks."
+- P1: "Task 'Set up user service with authentication, authorization, profile management, and email verification' covers four distinct features. Split into separate tasks."
+- P2: "Task 'Update README with API documentation link' is a one-line change. Group with other documentation tasks."
+
+---
+
+## Pass 4: Acceptance Criteria
+
+### What to Check
+
+Every task has clear, testable acceptance criteria that define "done." Criteria are specific enough that an agent can verify its own work.
+
+### Why This Matters
+
+Without acceptance criteria, agents do not know when to stop. They either under-deliver (missing edge cases, skipping error handling) or over-deliver (adding features not asked for, over-engineering). Clear criteria also enable automated verification — if the criteria are testable, CI can validate them.
+
+### How to Check
+
+1. For each task, read the acceptance criteria
+2. Check that criteria are testable assertions, not vague goals: "user can log in" is vague; "POST /auth/login returns 200 with JWT token when given valid credentials, 401 with error message when given invalid credentials" is testable
+3. Verify criteria cover the happy path AND at least one error/edge case
+4. Check that criteria reference specific inputs and expected outputs
+5. Look for criteria that say "should work correctly" or "handle errors properly" — these are not actionable
+6. Verify that criteria align with the API contract, database schema, and UX spec (no contradictions with upstream artifacts)
+
+### What a Finding Looks Like
+
+- P0: "Task 'Implement payment processing' has acceptance criteria: 'Payments should work.' This is untestable. Specify: which payment methods, what validation, what error responses, what idempotency behavior."
+- P1: "Task 'Build user registration' criteria say 'user can register' but do not specify validation rules (password requirements, email format, duplicate handling)."
+- P2: "Acceptance criteria reference 'standard error format' without specifying what that format is. Link to the error contract in the API spec."
+
+---
+
+## Pass 5: Critical Path Accuracy
+
+### What to Check
+
+The identified critical path is actually the longest dependency chain. Moving tasks on/off the critical path would not shorten total project duration.
+
+### Why This Matters
+
+An incorrect critical path means optimization effort is misdirected. If the team parallelizes work on the perceived critical path but the actual bottleneck is elsewhere, total project duration does not improve. The critical path determines the minimum project duration — optimizing anything else has zero impact on delivery date.
+
+### How to Check
+
+1. Trace the longest dependency chain from start to finish — this is the critical path
+2. Compare with the documented critical path — do they match?
+3. Check for hidden long chains: integration tasks, end-to-end testing, deployment setup — these are often on the actual critical path but not recognized
+4. Verify that critical path tasks are not blocked by non-critical tasks (this would extend the critical path)
+5. Check for near-critical paths: chains that are only 1-2 tasks shorter than the critical path. These become the critical path if any task slips.
+6. Verify that critical path tasks have clear owners and no ambiguity — these are the tasks that cannot afford delays
+
+### What a Finding Looks Like
+
+- P0: "The documented critical path is: schema -> API -> frontend. But the actual longest chain is: schema -> API -> integration tests -> deployment pipeline -> end-to-end tests, which is 2 tasks longer."
+- P1: "Critical path task 'Implement auth service' depends on non-critical task 'Design admin dashboard.' This dependency makes the admin dashboard silently critical."
+- P2: "Two dependency chains are within one task of the critical path length. These near-critical paths should be identified to guide resource allocation."
+
+---
+
+## Pass 6: Parallelization Validity
+
+### What to Check
+
+Tasks marked as parallelizable are truly independent. They do not share state, modify the same files, or have undeclared dependencies on each other's output.
+
+### Why This Matters
+
+False parallelization causes merge conflicts, race conditions, and wasted work. If two agents build features that both modify the same shared module, their changes conflict at merge time. One agent's work may need to be redone. Worse, if both agents assume they own a shared resource, they may produce incompatible implementations.
+
+### How to Check
+
+1. For each set of tasks marked as parallel, check: do they modify the same files?
+2. Check for shared state: do parallel tasks both write to the same database tables, configuration files, or shared modules?
+3. Check for shared dependencies: if both tasks depend on a shared library, will one task's changes to that library affect the other?
+4. Verify that parallel tasks produce independent outputs that can be merged without conflict
+5. Check for ordering assumptions: does parallel task A assume parallel task B has or has not completed?
+6. Look for shared infrastructure: if both tasks need to modify CI/CD configuration, they will conflict
+
+### What a Finding Looks Like
+
+- P0: "Tasks 'Implement user service' and 'Implement auth middleware' are marked as parallel, but both modify 'src/middleware/index.ts'. These will produce merge conflicts."
+- P1: "Tasks 'Build order API' and 'Build inventory API' are parallel but both need to modify the shared database connection configuration. Sequence the config setup first."
+- P2: "Parallel tasks 'Build feature A' and 'Build feature B' both add entries to the routing table. Minor merge conflict risk — document the resolution strategy."
+
+---
+
+## Pass 7: Agent Context
+
+### What to Check
+
+Each task specifies which documents and artifacts the implementing agent should read before starting. The context is sufficient for the agent to complete the task without hunting for information.
+
+### Why This Matters
+
+AI agents have limited context windows. If a task does not specify what to read, the agent either loads too much context (wasting tokens, risking truncation) or too little (missing crucial design decisions). Explicit context references are the difference between an agent that executes efficiently and one that spends half its session discovering what it needs to know.
+
+### How to Check
+
+1. For each task, verify a context section lists the specific documents/sections to read
+2. Check that the listed context is sufficient: does it cover the relevant architecture section, API contract, database schema, and UX spec for this task?
+3. Check that the listed context is minimal: does it include only what is needed for this specific task, not the entire project documentation?
+4. Verify that context references are specific: "docs/system-architecture.md, Section 3.2: Order Service" not just "docs/system-architecture.md"
+5. Check for missing context: does the task require knowledge that is not in any listed document? (This may indicate a documentation gap)
+6. Verify that coding standards, testing strategy, and git workflow references are included where relevant
+
+### What a Finding Looks Like
+
+- P0: "Task 'Implement order creation endpoint' lists no context documents. The agent needs the API contract (endpoint spec), database schema (orders table), domain model (Order aggregate invariants), and architecture section (Order Service design)."
+- P1: "Task 'Build user dashboard' references the architecture document but not the UX spec. The agent will build the component structure correctly but not the visual design."
+- P2: "Task context references 'docs/system-architecture.md' without specifying which section. The agent will load the entire 2000-line document instead of the relevant 100-line section."

package/knowledge/review/review-methodology.md

@@ -0,0 +1,215 @@
+---
+name: review-methodology
+description: Shared process for conducting multi-pass reviews of documentation artifacts
+topics: [review, methodology, quality-assurance, multi-pass]
+---
+
+# Review Methodology
+
+This document defines the shared process for reviewing pipeline artifacts. It covers HOW to review, not WHAT to check — each artifact type has its own review knowledge base document with domain-specific passes and failure modes. Every review phase (1a through 10a) follows this process.
+
+## Multi-Pass Review Structure
+
+### Why Multiple Passes
+
+A single read-through catches surface errors but misses structural problems. The human tendency (and the AI tendency) is to get anchored on the first issue found and lose track of the broader picture. Multi-pass review forces systematic coverage by constraining each pass to one failure mode category.
+
+Each pass has a single focus: coverage, consistency, structural integrity, or downstream readiness. The reviewer re-reads the artifact with fresh eyes each time, looking for one thing. This is slower than a single pass but catches 3-5x more issues in practice.
+
+### Pass Ordering
+
+Order passes from broadest to most specific:
+
+1. **Coverage passes first** — Is everything present that should be? Missing content is the highest-impact failure mode because it means entire aspects of the system are unspecified. Coverage gaps compound downstream: a missing domain in the domain modeling step means missing ADRs in the decisions step, missing components in the architecture step, missing tables in the specification step, and so on.
+
+2. **Consistency passes second** — Does everything agree with itself and with upstream artifacts? Inconsistencies are the second-highest-impact failure because they create ambiguity for implementing agents. When two documents disagree, the agent guesses — and guesses wrong.
+
+3. **Structural integrity passes third** — Is the artifact well-formed? Are relationships explicit? Are boundaries clean? Structural issues cause implementation friction: circular dependencies, unclear ownership, ambiguous boundaries.
+
+4. **Downstream readiness last** — Can the next phase proceed? This pass validates that the artifact provides everything its consumers need. It is the gate that determines whether to proceed or iterate.
+
+### Pass Execution
+
+For each pass:
+
+1. State the pass name and what you are looking for
+2. Re-read the entire artifact (or the relevant sections) with only that lens
+3. Record every finding, even if minor — categorize later
+4. Do not fix anything during a pass — record only
+5. After completing all findings for this pass, move to the next pass
+
+Do not combine passes. The discipline of single-focus reading is the mechanism that catches issues a general-purpose review misses.
+
+## Finding Categorization
+
+Every finding gets a severity level. Severity determines whether the finding blocks progress or gets deferred.
+
+### P0: Blocks Next Phase
+
+The artifact cannot be consumed by the next pipeline phase in its current state. The next phase would produce incorrect output or be unable to proceed.
+
+**Examples:**
+- A domain entity referenced by three other models is completely undefined
+- An ADR contradicts another ADR with no acknowledgment, and the architecture depends on both
+- A database schema is missing tables for an entire bounded context
+- An API endpoint references a data type that does not exist in any domain model
+
+**Action:** Must fix before proceeding. No exceptions.
+
+### P1: Significant Gap
+
+The artifact is usable but has a meaningful gap that will cause rework downstream. The next phase can proceed but will need to make assumptions that may be wrong.
+
+**Examples:**
+- An aggregate is missing one invariant that affects validation logic
+- An ADR lists alternatives but does not evaluate them
+- A data flow diagram omits error paths
+- An API endpoint is missing error response definitions
+
+**Action:** Should fix before proceeding. Fix unless the cost of fixing now significantly exceeds the cost of fixing during the downstream phase (rare).
+
+### P2: Improvement Opportunity
+
+The artifact is correct and usable but could be clearer, more precise, or better organized. The next phase can proceed without issue.
+
+**Examples:**
+- A domain model uses informal language where a precise definition would help
+- An ADR's consequences section is vague but the decision is clear
+- A diagram uses inconsistent notation but the meaning is unambiguous
+- An API contract could benefit from more examples
+
+**Action:** Fix if time permits. Log for future improvement.
+
+### P3: Nice-to-Have
+
+Stylistic, formatting, or polish issues. No impact on correctness or downstream consumption.
+
+**Examples:**
+- Inconsistent heading capitalization
+- A diagram could be reformatted for readability
+- A section could be reordered for flow
+- Minor wording improvements
+
+**Action:** Fix during finalization phase if at all. Do not spend review time on these.
+
+## Fix Planning
+
+After all passes are complete and findings are categorized, create a fix plan before making any changes. Ad hoc fixing (fixing issues as you find them) risks:
+
+- Introducing new issues while fixing old ones
+- Fixing a symptom instead of a root cause (two findings may share one fix)
+- Spending time on P2/P3 issues before P0/P1 are resolved
+
+### Grouping Findings
+
+Group related findings into fix batches:
+
+1. **Same root cause** — Multiple findings that stem from a single missing concept, incorrect assumption, or structural issue. Fix the root cause once.
+2. **Same section** — Findings in the same part of the artifact that can be addressed in a single editing pass.
+3. **Same severity** — Process all P0s first, then P1s. Do not interleave.
+
+### Prioritizing by Downstream Impact
+
+Within the same severity level, prioritize fixes that have the most downstream impact:
+
+- Fixes that affect multiple downstream phases rank higher than single-phase impacts
+- Fixes that change structure (adding entities, changing boundaries) rank higher than fixes that change details (clarifying descriptions, adding examples)
+- Fixes to artifacts consumed by many later phases rank higher (domain models affect everything; API contracts affect fewer phases)
+
+### Fix Plan Format
+
+```markdown
+## Fix Plan
+
+### Batch 1: [Root cause or theme] (P0)
+- Finding 1.1: [description]
+- Finding 1.3: [description]
+- Fix approach: [what to change and why]
+- Affected sections: [list]
+
+### Batch 2: [Root cause or theme] (P0)
+- Finding 2.1: [description]
+- Fix approach: [what to change and why]
+- Affected sections: [list]
+
+### Batch 3: [Root cause or theme] (P1)
+...
+```
+
+## Re-Validation
+
+After applying all fixes in a batch, re-run the specific passes that produced the findings in that batch. This is not optional — fixes routinely introduce new issues.
+
+### What to Check
+
+1. The original findings are resolved (the specific issues no longer exist)
+2. The fix did not break anything checked by the same pass (re-read the full pass scope, not just the fixed section)
+3. The fix did not introduce inconsistencies with other parts of the artifact (quick consistency check)
+
+### When to Stop
+
+Re-validation is complete when:
+- All P0 and P1 findings are resolved
+- Re-validation produced no new P0 or P1 findings
+- Any new P2/P3 findings are logged but do not block progress
+
+If re-validation produces new P0/P1 findings, create a new fix batch and repeat. If this cycle repeats more than twice, the artifact likely has a structural problem that requires rethinking a section rather than patching individual issues.
+
+## Downstream Readiness Gate
+
+The final check in every review: can the next phase proceed with these artifacts?
+
+### How to Evaluate
+
+1. Read the meta-prompt for the next phase — what inputs does it require?
+2. For each required input, verify the current artifact provides it with sufficient detail and clarity
+3. For each quality criterion in the next phase's meta-prompt, verify the current artifact supports it
+4. Identify any questions the next phase's author would need to ask — each question is a gap
+
+### Gate Outcomes
+
+- **Pass** — The next phase can proceed. All required information is present and unambiguous.
+- **Conditional pass** — The next phase can proceed but should be aware of specific limitations or assumptions. Document these as handoff notes.
+- **Fail** — The next phase cannot produce correct output. Specific gaps must be addressed first.
+
+A conditional pass is the most common outcome. Document the conditions clearly so the next phase knows what assumptions it is inheriting.
+
+## Review Report Format
+
+Every review produces a structured report. This format ensures consistency across all review phases and makes it possible to track review quality over time.
+
+```markdown
+# Review Report: [Artifact Name]
+
+## Executive Summary
+[2-3 sentences: overall artifact quality, number of findings by severity,
+whether downstream gate passed]
+
+## Findings by Pass
+
+### Pass N: [Pass Name]
+| # | Severity | Finding | Location |
+|---|----------|---------|----------|
+| 1 | P0 | [description] | [section/line] |
+| 2 | P1 | [description] | [section/line] |
+
+### Pass N+1: [Pass Name]
+...
+
+## Fix Plan
+[Grouped fix batches as described above]
+
+## Fix Log
+| Batch | Findings Addressed | Changes Made | New Issues |
+|-------|-------------------|--------------|------------|
+| 1 | 1.1, 1.3 | [summary] | None |
+| 2 | 2.1 | [summary] | 2.1a (P2) |
+
+## Re-Validation Results
+[Which passes were re-run, what was found]
+
+## Downstream Readiness Assessment
+- **Gate result:** Pass | Conditional Pass | Fail
+- **Handoff notes:** [specific items the next phase should be aware of]
+- **Remaining P2/P3 items:** [count and brief summary, for future reference]
+```

package/knowledge/review/review-operations.md

@@ -0,0 +1,212 @@
+---
+name: review-operations
+description: Failure modes and review passes specific to operations and deployment runbook artifacts
+topics: [review, operations, deployment, monitoring, runbooks]
+---
+
+# Review: Operations & Deployment
+
+The operations runbook defines how the system is deployed, monitored, and maintained in production. It must cover the full deployment lifecycle, provide runbook procedures for common failure scenarios, and ensure the development environment reasonably mirrors production. This review uses 7 passes targeting the specific ways operations documentation fails.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Deployment Strategy Completeness
+
+### What to Check
+
+The full deploy lifecycle is documented: how code gets from a merged PR to running in production. Build, test, stage, deploy, verify, and rollback stages are all covered.
+
+### Why This Matters
+
+An incomplete deployment strategy means the team is one configuration error away from a production outage with no recovery plan. Every gap in the deployment pipeline is a place where a deployment can fail silently — code that passes CI but is never actually deployed, deployments that succeed but skip health checks, environments that drift from the documented configuration.
+
+### How to Check
+
+1. Trace the deployment pipeline from commit to production: build step, test step, staging deployment, production deployment, post-deploy verification
+2. Verify each stage has a clear trigger (manual, automatic), success criteria, and failure behavior
+3. Check for environment progression: does code move through dev -> staging -> production? Can environments be skipped?
+4. Verify that deployment artifacts are specified: Docker images, serverless packages, compiled binaries — what gets deployed?
+5. Check for blue-green or canary deployment patterns if mentioned in ADRs — are they fully designed or just named?
+6. Verify that deployment credentials, access controls, and approval requirements are documented (who can deploy, who can approve)
+7. Check for database migration integration: when do migrations run relative to code deployment?
+
+### What a Finding Looks Like
+
+- P0: "Deployment pipeline shows build -> test -> production with no staging environment. There is no way to verify a deployment before it reaches production."
+- P1: "Database migrations are not mentioned in the deployment pipeline. When do migrations run? Before or after the new code deploys? What happens if a migration fails mid-deploy?"
+- P1: "Post-deploy verification is missing. After deployment, how is the team notified that the new version is healthy? No health check, no smoke test, no monitoring check."
+- P2: "Deployment approvals are not specified. Can any developer deploy to production, or is approval required?"
+
+---
+
+## Pass 2: Rollback Procedures
+
+### What to Check
+
+Every deployment type has a corresponding rollback procedure. Rollback is tested (or at least testable), not just documented. Database rollbacks are addressed separately from code rollbacks.
+
+### Why This Matters
+
+Rollback is the emergency brake. When a deployment causes a production incident, the first response is to roll back. If the rollback procedure is untested, incomplete, or does not exist, the team is stuck debugging a production issue under pressure instead of reverting to a known-good state. Database rollbacks are especially critical — code can be swapped instantly, but data changes cannot.
+
+### How to Check
+
+1. For each deployment type (code deploy, database migration, configuration change, infrastructure change), verify a rollback procedure exists
+2. Check that code rollback specifies the mechanism: redeploy previous version, revert container tag, infrastructure-as-code rollback
+3. Check that database rollback addresses: can migrations be reversed? What about data migrations (not just schema)?
+4. Verify rollback has a time estimate: how long does a rollback take?
+5. Check for rollback testing: is the rollback procedure tested periodically, or only discovered during an incident?
+6. Verify that partial deployment rollback is addressed: what if only 2 of 5 services deployed before the failure?
+7. Check for data consistency during rollback: if the new code wrote data in a new format, does the old code handle it?
+
+### What a Finding Looks Like
+
+- P0: "No rollback procedure exists. If a deployment causes a production issue, the team has no documented way to revert."
+- P0: "Database migration rollback says 'reverse the migration' but the migration drops a column. Column data is lost — rollback is impossible without a backup."
+- P1: "Code rollback procedure exists but does not address database schema compatibility. Rolling back code to version N-1 while the database is at schema version N will cause errors."
+- P2: "Rollback time estimate is missing. The team does not know whether rollback takes 30 seconds or 30 minutes."
+
+---
+
+## Pass 3: Monitoring Coverage
+
+### What to Check
+
+All critical system metrics are identified, dashboards are defined, and monitoring covers infrastructure, application, and business metrics.
+
+### Why This Matters
+
+Without monitoring, production issues are discovered by users, not by the team. The time between "something breaks" and "the team knows about it" determines the blast radius of every incident. Monitoring must cover three layers: infrastructure (servers, containers, network), application (response times, error rates, throughput), and business (transaction volume, conversion rates, revenue).
+
+### How to Check
+
+1. Verify infrastructure metrics are specified: CPU, memory, disk, network, container health
+2. Verify application metrics are specified: request rate, error rate, response time (p50, p95, p99), active connections
+3. Check for business metrics: transaction volume, user signups, conversion rates — metrics that indicate the system is functioning correctly from a business perspective
+4. Verify that every component from the architecture has at least one monitored metric
+5. Check for dependency monitoring: are external services (databases, third-party APIs, message queues) monitored for availability and latency?
+6. Verify that monitoring covers error categorization: not just "errors happened" but "what type of errors" (4xx vs. 5xx, timeout vs. validation)
+7. Check for dashboard specifications: what dashboards exist, what do they show, who uses them?
+
+### What a Finding Looks Like
+
+- P0: "No application-level metrics are defined. The operations runbook mentions 'monitoring' but does not specify what is monitored."
+- P1: "Infrastructure metrics (CPU, memory) are monitored but application error rates are not. A bug causing 100% 500 errors would not trigger an alert."
+- P1: "External database monitoring is not mentioned. If the database becomes slow or unavailable, the monitoring system will not detect it until application health checks fail."
+- P2: "Business metrics (order volume, revenue) are not monitored. The system could be returning empty results for all product queries without triggering any alert."
+
+---
+
+## Pass 4: Alerting Thresholds
+
+### What to Check
+
+Alerts have justified thresholds (not arbitrary values). Alert severity levels map to response expectations. Alert fatigue is considered — not everything is a page.
+
+### Why This Matters
+
+Arbitrary thresholds cause two problems. Thresholds too low create alert storms — the on-call engineer gets paged for normal traffic spikes and learns to ignore alerts. Thresholds too high mean real incidents go undetected. Justified thresholds based on baseline behavior and business impact ensure alerts are both actionable and timely.
+
+### How to Check
+
+1. For each alert, check that the threshold has a rationale: why this number? Based on baseline data, SLA requirements, or capacity limits?
+2. Verify alert severity levels are defined: page (wake someone up), warn (investigate next business day), info (log for review)
+3. Check that page-level alerts are reserved for conditions that affect users or revenue — not internal metrics that can wait
+4. Verify de-duplication and grouping: if a server flaps, does it generate one alert or hundreds?
+5. Check for missing alerts: are there monitored metrics that have no corresponding alert? (Monitoring without alerting means no one is watching the dashboard)
+6. Verify alert routing: who gets which alerts? Is the on-call rotation documented?
+7. Check for alert testing: are alerts tested (fire a synthetic failure and verify the alert triggers)?
+
+### What a Finding Looks Like
+
+- P0: "Error rate alert threshold is 'greater than 0' — any single error triggers a page. This will cause alert fatigue within the first day of production."
+- P1: "CPU usage alert threshold is 80% with no justification. Is 80% normal during peak traffic? Is 60% already a problem? The threshold needs to be based on baseline behavior."
+- P1: "Alerts exist but no on-call rotation or escalation path is documented. When an alert fires at 3 AM, who receives it?"
+- P2: "Alert for disk usage exists but no alert for disk growth rate. A slow disk leak will only trigger when the disk is nearly full, leaving little time to respond."
+
+---
+
+## Pass 5: Runbook Scenarios
+
+### What to Check
+
+Common failure scenarios have runbook entries with step-by-step resolution procedures. Scenarios cover the failures most likely to occur and most impactful when they do.
+
+### Why This Matters
+
+During an incident, the on-call engineer is under stress, possibly working at 3 AM, and possibly unfamiliar with the subsystem that failed. A runbook provides step-by-step guidance so they do not need to debug from first principles. Missing runbook scenarios mean the engineer improvises under pressure — increasing resolution time and risk of making things worse.
+
+### How to Check
+
+1. List the most likely failure scenarios: database connection loss, external API outage, out-of-memory, certificate expiration, disk full, deployment failure, high latency
+2. For each scenario, verify a runbook entry exists
+3. Check that each runbook entry includes: symptoms (how to recognize this failure), diagnosis steps (how to confirm the root cause), resolution steps (how to fix it), verification (how to confirm it is fixed), post-mortem (what to document after the incident)
+4. Verify that runbook steps are specific and actionable: "check the logs" is too vague; "run `kubectl logs deployment/order-service -n production --tail=100` and look for `ConnectionRefused` errors" is actionable
+5. Check for escalation paths: when should the on-call engineer escalate to a senior engineer or the team lead?
+6. Verify that runbook entries reference the correct tools, dashboards, and access paths
+
+### What a Finding Looks Like
+
+- P0: "No runbook entries exist. The operations runbook discusses monitoring and alerting but provides no incident response procedures."
+- P1: "Database connection failure runbook says 'restart the database connection pool.' How? What command? What service? What if it does not recover after restart?"
+- P2: "Runbook entries exist for infrastructure failures but not for application-level failures (e.g., a bug causing 500 errors on a specific endpoint)."
+
+---
+
+## Pass 6: Dev Environment Parity
+
+### What to Check
+
+The local development environment reasonably matches production. Developers can run the full system locally with realistic behavior. Environment differences are documented.
+
+### Why This Matters
+
+When the development environment diverges from production, "works on my machine" becomes the default. Bugs that only appear in production are impossible to reproduce locally, increasing debugging time from hours to days. Dev environment parity is not about identical hardware — it is about identical behavior for application-level concerns.
+
+### How to Check
+
+1. Compare the dev environment stack to production: same database engine? Same message queue? Same cache? Same auth provider?
+2. Check for documented deviations: if production uses AWS SQS but dev uses a local queue, is this documented with its implications?
+3. Verify that local setup instructions exist and are complete: can a new developer go from clone to running system?
+4. Check that seed data or test fixtures exist for local development
+5. Verify that environment variables, configuration, and secrets management for local development are documented
+6. Check for containerization: if production runs in containers, does local development also use containers?
+7. Verify that local SSL/TLS handling matches production if HTTPS is required
+
+### What a Finding Looks Like
+
+- P0: "No local development setup instructions exist. A new developer cannot run the system locally."
+- P1: "Production uses PostgreSQL 15 but local development uses SQLite. SQL dialect differences will cause bugs that only appear in production."
+- P1: "Production uses Redis for session storage but local development stores sessions in memory. Multi-instance behavior cannot be tested locally."
+- P2: "Local development uses mock email service but production uses SendGrid. Email formatting and delivery behavior differences are not documented."
+
+---
+
+## Pass 7: DR/Backup Coverage
+
+### What to Check
+
+Disaster recovery approach is documented. Backup strategy covers all persistent data. Recovery time objectives (RTO) and recovery point objectives (RPO) are specified.
+
+### Why This Matters
+
+Without a backup strategy, data loss is permanent. Without a disaster recovery plan, a region outage or infrastructure failure takes the system offline indefinitely. RTO and RPO define the business tolerance for downtime and data loss — without them, the team does not know whether their backup strategy is sufficient.
+
+### How to Check
+
+1. Verify backup strategy covers all persistent data stores: primary database, file storage, message queues (if persistent), configuration stores
+2. Check that backup frequency is specified and aligns with RPO: if RPO is 1 hour, backups must run at least hourly
+3. Verify backup retention policy: how long are backups kept? Is there a legal/compliance requirement?
+4. Check that backup restoration is documented and tested: can the team actually restore from a backup?
+5. Verify DR strategy: multi-region, failover, warm standby, or cold recovery? What is the expected RTO?
+6. Check for data encryption at rest: are backups encrypted? Where are encryption keys stored?
+7. Verify that DR testing is planned: is there a schedule for testing recovery procedures?
+
+### What a Finding Looks Like
+
+- P0: "No backup strategy is documented. If the primary database is corrupted or lost, data recovery is impossible."
+- P0: "Backups run daily but the RPO is 15 minutes. Up to 24 hours of data could be lost, far exceeding the business tolerance."
+- P1: "Backup restoration procedure says 'restore from backup' with no specifics. What tool? What command? How long does it take? What is the verification step?"
+- P2: "DR strategy exists but has never been tested. The team does not know if recovery actually works within the stated RTO."