@zigrivers/scaffold 2.28.1 → 2.38.0

package/knowledge/review/review-database-design.md

@@ -10,6 +10,19 @@ The database schema translates domain entities and their relationships into pers
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Entity Coverage**: Every domain entity requiring persistence maps to a table; no domain concept is missing from the schema.
+- **Pass 2 — Relationship Fidelity**: Schema relationships accurately reflect domain model cardinality and direction; no missing or fabricated foreign keys.
+- **Pass 3 — Normalization Justification**: Normalization level of each table is justified; deliberate denormalization has documented rationale tied to access patterns.
+- **Pass 4 — Index Coverage**: Indexes cover known query patterns from architecture data flows; no critical query requires a full table scan.
+- **Pass 5 — Constraint Enforcement**: Database constraints (NOT NULL, UNIQUE, CHECK, FK) enforce domain invariants where possible.
+- **Pass 6 — Migration Safety**: Migration plan handles rollbacks and data preservation; destructive operations identified; data migrations separated from schema migrations.
+- **Pass 7 — Cross-Schema Consistency**: Multi-database naming conventions, shared identifiers, and cross-database references are consistent.
+- **Pass 8 — Downstream Readiness**: Schema supports efficient CRUD, list/search queries, relationship traversal, and aggregates needed by API contracts.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Entity Coverage

package/knowledge/review/review-domain-modeling.md

@@ -6,10 +6,14 @@ topics: [review, domain-modeling, ddd, bounded-contexts]
 
 # Review: Domain Modeling
 
-Domain models are the foundation of the entire pipeline. Every subsequent phase builds on them. A gap or error here compounds through ADRs, architecture, database schema, API contracts, and implementation tasks. This review uses 10 passes targeting the specific ways domain models fail.
+## Summary
+
+Domain models are the foundation of the entire pipeline. Every subsequent phase builds on them. A gap or error here compounds through ADRs, architecture, database schema, API contracts, and implementation tasks. This review uses 10 passes targeting the specific ways domain models fail: (1) PRD coverage audit, (2) bounded context integrity, (3) entity vs value object classification, (4) aggregate boundary validation, (5) domain event completeness, (6) invariant specification, (7) ubiquitous language consistency, (8) cross-domain relationship clarity, (9) downstream readiness, and (10) internal consistency.
 
 Follows the review process defined in `review-methodology.md`.
 
+## Deep Guidance
+
 ---
 
 ## Pass 1: PRD Coverage Audit

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

@@ -6,10 +6,23 @@ 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.
+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 8 passes targeting the specific ways implementation tasks fail.
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Architecture Coverage**: Every architectural component, module, and integration point has corresponding tasks; cross-cutting concerns and infrastructure included.
+- **Pass 2 — Missing Dependencies**: Task dependencies are complete and correct; no circular dependencies; no implicit prerequisites left undeclared.
+- **Pass 3 — Task Sizing**: No task too large for a single agent session (30-60 min) or too small to be meaningful; clear scope boundaries.
+- **Pass 4 — Acceptance Criteria**: Every task has clear, testable criteria covering happy path and at least one error/edge case.
+- **Pass 5 — Critical Path Accuracy**: The identified critical path is actually the longest dependency chain; near-critical paths identified.
+- **Pass 6 — Parallelization Validity**: Tasks marked as parallel are truly independent; no shared state, files, or undeclared dependencies.
+- **Pass 7 — Agent Context**: Each task specifies which documents/sections the implementing agent should read; context is sufficient and minimal.
+- **Pass 8 — Agent Executability**: Every task complies with the 5 agent sizing rules (three-file, 150-line, single-concern, decision-free, test co-location); exceptions are justified.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Architecture Coverage
@@ -203,6 +216,50 @@ AI agents have limited context windows. If a task does not specify what to read,
 
 ---
 
+## Pass 8: Agent Executability
+
+### What to Check
+
+Every task complies with the five agent executability rules. Tasks exceeding limits without justification must be split.
+
+- **Three-File Rule**: Count application files each task modifies (test files excluded). Flag any task touching 4+ files. Check for `<!-- agent-size-exception -->` annotations on flagged tasks.
+- **150-Line Budget**: Estimate net-new lines per task based on the task description scope. Flag tasks likely to produce 200+ lines. Signals: "implement X with Y and Z", multiple acceptance criteria spanning different modules, multi-layer work.
+- **Single-Concern Rule**: Check each task description for "and" connecting unrelated work. Flag tasks spanning multiple architectural layers or feature domains.
+- **Decision-Free Execution**: Scan for unresolved design decisions. Red flags: "choose", "determine", "decide", "evaluate options", "select the best approach", "pick the right", "figure out". Every design choice must be resolved in the task description.
+- **Test Co-location**: Verify every task that produces application code also includes test requirements. Flag any "write tests for tasks X-Y" aggregation pattern. Flag tasks with no test mention.
+
+### Why This Matters
+
+Large tasks are the #1 cause of AI agent failure during implementation. When a task requires reading 5+ files, holding multiple abstractions in context, and writing 300+ lines — agents lose coherence, make inconsistent changes, or run out of context window. Tasks with unresolved design decisions cause agents to make architectural choices they shouldn't, producing inconsistent implementations across tasks. Deferred testing produces untestable code and violates TDD.
+
+### How to Check
+
+1. For each task, count the application files it modifies (exclude test files). Flag 4+ files.
+2. Estimate net-new application code lines from the task scope. Flag 200+ estimated lines.
+3. Read the task description. Does it contain "and" connecting distinct concerns? Flag it.
+4. Scan for decision language: "choose", "determine", "decide", "evaluate", "select", "figure out". Flag any unresolved decisions.
+5. Check test requirements. Does every code-producing task specify what to test? Flag tasks with no test mention or deferred testing.
+6. For flagged tasks, check for `<!-- agent-size-exception: reason -->`. Accept justified exceptions; flag unjustified ones.
+7. For each P0/P1 finding, provide a specific split recommendation: name the sub-tasks, list files each owns, specify dependencies between them.
+
+### Severity
+
+- P0: Task exceeds 6+ files or 300+ estimated lines — must split immediately, no exceptions
+- P1: Task violates three-file rule without justification — must split or add exception annotation
+- P1: Task violates 150-line budget without justification — must split or justify
+- P1: Task contains unresolved design decisions — must resolve in task description
+- P2: Task has "and" connecting concerns but stays within limits — recommend split
+- P2: Test requirements vague ("add appropriate tests") or deferred — strengthen with specifics
+- P3: Task near limits (3 files, ~150 lines) — note as borderline, no action required
+
+### What a Finding Looks Like
+
+- P1: "Task BD-15 'Implement order management API' modifies 5 files (routes, controller, service, validator, model). Violates three-file rule. Split into: BD-15a 'Create order model and migration' (1 file + migration), BD-15b 'Implement order service with validation' (2 files), BD-15c 'Add order routes and controller' (2 files, depends on BD-15a, BD-15b)."
+- P1: "Task BD-22 'Build settings page' says 'determine whether to use tabs or accordion for organizing preferences.' This is an unresolved design decision. The task description must specify the layout pattern."
+- P2: "Task BD-08 'Set up error handling AND configure logging' connects two concerns with 'and'. Recommend splitting into error handling task and logging task."
+
+---
+
 ## Common Review Anti-Patterns
 
 ### 1. Reviewing Tasks in Isolation

package/knowledge/review/review-methodology.md

@@ -8,6 +8,17 @@ topics: [review, methodology, quality-assurance, multi-pass]
 
 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.
 
+## Summary
+
+- **Multi-pass review**: Each pass has a single focus (coverage, consistency, structure, downstream readiness). Passes are ordered broadest-to-most-specific.
+- **Finding severity**: P0 blocks next phase (must fix), P1 is a significant gap (should fix), P2 is an improvement opportunity (fix if time permits), P3 is nice-to-have (skip).
+- **Fix planning**: Group findings by root cause, same section, and same severity. Fix all P0s first, then P1s. Never fix ad hoc.
+- **Re-validation**: After applying fixes, re-run the specific passes that produced the findings. Stop when no new P0/P1 findings appear.
+- **Downstream readiness gate**: Final check verifies the next phase can proceed with these artifacts. Outcomes: pass, conditional pass, or fail.
+- **Review report**: Structured output with executive summary, findings by pass, fix plan, fix log, re-validation results, and downstream readiness assessment.
+
+## Deep Guidance
+
 ## Multi-Pass Review Structure
 
 ### Why Multiple Passes

package/knowledge/review/review-operations.md

@@ -10,6 +10,18 @@ The operations runbook defines how the system is deployed, monitored, and mainta
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Deployment Strategy Completeness**: Full deploy lifecycle documented from merged PR to running production, including build, test, stage, deploy, verify, and rollback stages.
+- **Pass 2 — Rollback Procedures**: Every deployment type has a corresponding rollback procedure; database rollbacks addressed separately from code rollbacks.
+- **Pass 3 — Monitoring Coverage**: Infrastructure, application, and business metrics identified with dashboards defined for all critical system components.
+- **Pass 4 — Alerting Thresholds**: Alerts have justified thresholds based on baselines, severity levels map to response expectations, and alert fatigue is considered.
+- **Pass 5 — Runbook Scenarios**: Common failure scenarios have step-by-step runbook entries covering symptoms, diagnosis, resolution, verification, and escalation.
+- **Pass 6 — Dev Environment Parity**: Local development environment reasonably matches production behavior; documented deviations with implications.
+- **Pass 7 — DR/Backup Coverage**: Disaster recovery approach documented with RTO/RPO targets; backup strategy covers all persistent data stores.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Deployment Strategy Completeness

package/knowledge/review/review-prd.md

@@ -10,6 +10,19 @@ The PRD is the foundation of the entire pipeline. Every subsequent phase builds
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Problem Statement Rigor**: Verify the problem is specific, testable, grounded in evidence, and names a specific user group without prescribing solutions.
+- **Pass 2 — Persona & Stakeholder Coverage**: Ensure personas are goal-driven with constraints and context; 2-4 meaningful personas covering all stakeholder groups.
+- **Pass 3 — Feature Scoping Completeness**: Confirm in-scope, out-of-scope, and deferred lists exist; features are specific enough to estimate with prioritization applied.
+- **Pass 4 — Success Criteria Measurability**: Every criterion needs a target value, measurement method, and tie-back to the problem statement.
+- **Pass 5 — NFR Quantification**: All NFR categories addressed with quantified targets and conditions, not adjectives.
+- **Pass 6 — Constraint & Dependency Documentation**: Technical, timeline, budget, team, and regulatory constraints present with traceable downstream impact.
+- **Pass 7 — Error & Edge Case Coverage**: Sad paths for every feature with user input or external dependencies; failure modes for third-party integrations.
+- **Pass 8 — Downstream Readiness for User Stories**: Features specific enough to map to stories, personas specific enough to be actors, business rules explicit enough for acceptance criteria.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Problem Statement Rigor

package/knowledge/review/review-security.md

@@ -10,6 +10,18 @@ The security review document assesses the system's security posture across authe
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — OWASP Coverage**: Every OWASP Top 10 category addressed with project-specific analysis, not generic checklist advice.
+- **Pass 2 — Auth/AuthZ Boundary Alignment**: Security boundaries align with API contract auth requirements; no access control gaps between security review and API enforcement.
+- **Pass 3 — Secrets Management**: No secrets in code or version control; rotation strategy exists; vault/secrets manager integration specified for all secret categories.
+- **Pass 4 — Dependency Audit Coverage**: Vulnerability scanning integrated into CI covering direct and transitive dependencies; response policy for discovered vulnerabilities.
+- **Pass 5 — Threat Model Scenarios**: Structured threat model (STRIDE/PASTA) covering all trust boundaries with specific, project-relevant threat scenarios and mapped mitigations.
+- **Pass 6 — Data Classification**: Data categorized by sensitivity level with handling requirements per category; regulatory compliance addressed.
+- **Pass 7 — Input Validation**: Validation at all system boundaries (not just frontend) covering type, format, range, and business rules.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: OWASP Coverage

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

@@ -6,12 +6,14 @@ 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.
+## Summary
 
-This review uses 10 passes targeting the specific ways architecture documents fail.
+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: (1) domain model coverage, (2) ADR constraint compliance, (3) data flow completeness, (4) module structure integrity, (5) state consistency, (6) diagram/prose consistency, (7) extension point integrity, (8) invariant verification, (9) downstream readiness, and (10) internal consistency.
 
 Follows the review process defined in `review-methodology.md`.
 
+## Deep Guidance
+
 ---
 
 ## Pass 1: Domain Model Coverage

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

@@ -10,6 +10,17 @@ The testing strategy defines how the system will be verified at every layer. It
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Coverage Gaps by Layer**: Each architectural layer has test coverage defined; test pyramid is balanced (not top-heavy or bottom-heavy).
+- **Pass 2 — Domain Invariant Test Cases**: Every domain invariant has at least one corresponding test scenario covering positive and negative cases.
+- **Pass 3 — Test Environment Assumptions**: Test environment matches production constraints; database engines, service configurations, and test data are realistic.
+- **Pass 4 — Performance Test Coverage**: Performance-critical paths have benchmarks with specific thresholds; load and stress testing scenarios defined.
+- **Pass 5 — Integration Boundary Coverage**: All component integration points have integration tests using real (not mocked) dependencies.
+- **Pass 6 — Quality Gate Completeness**: CI pipeline gates cover linting, type checking, tests, and security scanning; gates block deployment on failure.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Coverage Gaps by Layer

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

@@ -10,6 +10,17 @@ User stories translate PRD requirements into user-facing behavior with testable
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — PRD Coverage**: Every PRD feature, flow, and requirement has at least one corresponding user story; no silent coverage gaps.
+- **Pass 2 — Acceptance Criteria Quality**: Every story has testable, unambiguous Given/When/Then criteria covering happy path and at least one error/edge case.
+- **Pass 3 — Story Independence**: Stories can be implemented independently; dependencies are explicit, not hidden; no circular dependencies.
+- **Pass 4 — Persona Coverage**: Every PRD-defined persona has stories; every story maps to a valid, defined persona.
+- **Pass 5 — Sizing & Splittability**: No story too large for 1-3 agent sessions or too small to be meaningful; oversized stories have clear split points.
+- **Pass 6 — Downstream Readiness**: Domain entities, events, aggregate boundaries, and business rules are discoverable from acceptance criteria for domain modeling.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: PRD Coverage

package/knowledge/review/review-ux-specification.md

@@ -1,7 +1,7 @@
 ---
 name: review-ux-specification
 description: Failure modes and review passes specific to UI/UX specification artifacts
-topics: [review, ux, design, accessibility, responsive]
+topics: [review, ux, design, accessibility, responsive-design]
 ---
 
 # Review: UX Specification
@@ -10,6 +10,18 @@ The UX specification translates user journeys from the PRD and component archite
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — User Journey Coverage vs PRD**: Every user-facing PRD feature has a corresponding screen, flow, or interaction; non-happy-path journeys covered.
+- **Pass 2 — Accessibility Compliance**: WCAG level stated; keyboard navigation, screen reader support, color contrast, and focus management specified.
+- **Pass 3 — Interaction State Completeness**: Every component has all states defined: empty, loading, populated, error, disabled, and edge states.
+- **Pass 4 — Design System Consistency**: Colors, spacing, typography reference design system tokens, not one-off values.
+- **Pass 5 — Responsive Breakpoint Coverage**: Behavior defined for all breakpoints; navigation, data tables, and forms adapt appropriately.
+- **Pass 6 — Error State Handling**: Every user action that can fail has a designed error state with user-friendly messages and clear recovery paths.
+- **Pass 7 — Component Hierarchy vs Architecture**: Frontend components in UX spec align with architecture component boundaries and state management approach.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: User Journey Coverage vs PRD

package/knowledge/review/review-vision.md

@@ -0,0 +1,255 @@
+---
+name: review-vision
+description: Vision-specific review passes, failure modes, and quality criteria for product vision documents
+topics: [review, vision, product-strategy, validation]
+---
+
+# Review: Product Vision
+
+The product vision document sets the strategic direction for everything downstream. It defines why the product exists, who it serves, what makes it different, and what traps to avoid. A weak vision produces a PRD that lacks focus, user stories that lack purpose, and an architecture that lacks guiding constraints. This review uses 5 passes targeting the specific ways vision artifacts fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Summary
+
+Vision review validates that the product vision is specific enough to guide decisions, inspiring enough to align a team, and honest enough to withstand scrutiny. The 5 passes target: (1) vision clarity -- is the vision statement specific, inspiring, and actionable, (2) target audience -- are users defined by behaviors and motivations rather than demographics, (3) competitive landscape -- is the analysis honest about strengths and not just weaknesses, (4) guiding principles -- do they create real tradeoffs with X-over-Y format, and (5) anti-vision -- does it name specific traps rather than vague disclaimers.
+
+---
+
+## Deep Guidance
+
+## Pass 1: Vision Clarity
+
+### What to Check
+
+- Is the vision statement specific to THIS product, not a generic mission statement?
+- Does it inspire action, not just describe a category?
+- Is it actionable -- could a team use it to make a yes/no decision about a feature?
+- Does it avoid jargon, buzzwords, and empty superlatives ("best-in-class," "world-class," "revolutionary")?
+- Is it short enough to remember (1-3 sentences)?
+
+### Why This Matters
+
+The vision statement is the single most referenced artifact in the pipeline. It appears in PRD context, guides user story prioritization, and informs architecture trade-offs. A generic vision like "make the best project management tool" provides zero signal -- it cannot distinguish between features to build and features to skip. A specific vision like "help 2-person freelance teams track client work without learning project management" makes every downstream decision easier.
+
+### How to Check
+
+1. Read the vision statement in isolation -- does it name a specific outcome for a specific group?
+2. Try the "swap test" -- could you replace the product name with a competitor's name and have the vision still be true? If yes, it is not specific enough
+3. Try the "decision test" -- present two hypothetical features and ask whether the vision helps you choose between them. If it does not, the vision is too vague
+4. Check for buzzwords: "leverage," "synergy," "best-in-class," "end-to-end," "seamless" -- these add words without adding meaning
+5. Check length -- if the vision takes more than 30 seconds to read aloud, it is too long to internalize
+
+### What a Finding Looks Like
+
+- P0: "Vision statement is 'To be the leading platform for enterprise collaboration.' This could describe Slack, Teams, Notion, or Confluence. It names no specific user group, no specific problem, and no specific differentiation."
+- P1: "Vision statement is specific but contains 'seamless end-to-end experience' -- this phrase adds no decision-making value. Replace with the specific experience being described."
+- P2: "Vision is 4 paragraphs long. Distill to 1-3 sentences that a team member could recite from memory."
+
+### Common Failure Modes
+
+- **Category description**: The vision describes a market category, not a product direction ("We build developer tools")
+- **Aspiration without specificity**: The vision is inspiring but cannot guide decisions ("Empower teams to do their best work")
+- **Solution masquerading as vision**: The vision describes a technology choice, not a user outcome ("AI-powered analytics platform")
+
+---
+
+## Pass 2: Target Audience
+
+### What to Check
+
+- Is the target audience defined by behaviors, motivations, and constraints -- not demographics?
+- Does the audience description create clear inclusion/exclusion criteria?
+- Are there signs of the "everyone" trap (audience so broad it provides no prioritization signal)?
+- Does the audience description explain WHY these people need this product specifically?
+
+### Why This Matters
+
+Demographics (age, location, job title) do not predict product needs. Behaviors and motivations do. "Marketing managers aged 30-45" tells you nothing about what to build. "Solo marketers who manage 5+ channels without a team and need to appear more capable than they are" tells you everything. The audience definition flows directly into PRD personas -- vague audiences produce vague personas produce vague user stories.
+
+### How to Check
+
+1. Check whether the audience is defined by observable behaviors ("currently uses spreadsheets to track...") versus demographics ("25-40 year old professionals")
+2. Check for motivations -- WHY does this audience need the product? What is the underlying drive?
+3. Check for constraints -- what limits this audience? Budget? Time? Technical skill? Team size?
+4. Apply the "exclusion test" -- does the audience definition clearly exclude some potential users? If not, it is too broad
+5. Check that the audience connects to the vision -- is this the audience that the vision serves?
+
+### What a Finding Looks Like
+
+- P0: "Target audience is 'businesses of all sizes.' This excludes nobody and provides no prioritization signal. The PRD cannot write meaningful personas from this."
+- P1: "Target audience mentions 'small business owners' but defines them only by company size (<50 employees), not by behaviors, pain points, or motivations."
+- P2: "Audience description is behavior-based but does not explain why existing solutions fail this group."
+
+### Common Failure Modes
+
+- **Demographic-only**: Defined by who they are, not what they do ("SMB owners aged 25-45")
+- **Too broad**: Audience includes everyone ("teams of any size in any industry")
+- **Missing motivation**: Describes the audience but not why they need THIS product
+- **No exclusion criteria**: Cannot determine who is NOT the target audience
+
+---
+
+## Pass 3: Competitive Landscape
+
+### What to Check
+
+- Does the competitive analysis honestly assess competitors' strengths, not just their weaknesses?
+- Are competitors named specifically, not referred to generically ("existing solutions")?
+- Is the differentiation based on substance (different approach, different audience, different trade-offs) not superficiality ("better UX")?
+- Does the analysis acknowledge what competitors do well that this product will NOT try to replicate?
+
+### Why This Matters
+
+A competitive landscape that only lists competitor weaknesses produces false confidence. Competitors have strengths -- users chose them for reasons. Understanding those reasons prevents building a product that is strictly worse in dimensions users care about. Differentiation based on "we'll just do it better" is not differentiation -- it is a bet that the team is more competent than established competitors with more resources.
+
+### How to Check
+
+1. For each named competitor, check that at least one genuine strength is acknowledged
+2. Check that differentiation is structural (different trade-off, different audience segment, different approach) not aspirational ("better design")
+3. Verify competitors are named specifically -- "Competitor X" or "the market" provides no signal
+4. Check whether the analysis acknowledges what the product will NOT compete on (conceding dimensions to competitors)
+5. Look for the "better at everything" anti-pattern -- if the product claims superiority in every dimension, the analysis is dishonest
+
+### What a Finding Looks Like
+
+- P0: "Competitive section lists 4 competitors but only describes their weaknesses. No competitor strengths are acknowledged. This produces a false picture of the market and prevents honest differentiation."
+- P1: "Differentiation claim is 'better user experience.' This is not structural differentiation -- every product claims this. What specific design trade-off creates a different experience?"
+- P2: "Competitors are referred to as 'existing solutions' and 'current tools' without naming them. Specific names enable specific analysis."
+
+### Common Failure Modes
+
+- **Weakness-only analysis**: Lists only what competitors do poorly, creating false confidence
+- **Aspirational differentiation**: Claims superiority without structural basis ("we'll be faster, simpler, and more powerful")
+- **Generic competitors**: References "the market" or "existing solutions" without naming specific products
+- **Missing concessions**: Does not acknowledge what the product will deliberately NOT compete on
+
+---
+
+## Pass 4: Guiding Principles
+
+### What to Check
+
+- Are principles in X-over-Y format, creating real trade-offs?
+- Does each principle rule out a specific, tempting alternative?
+- Could a reasonable person disagree with the principle (i.e., the "over Y" option is genuinely attractive)?
+- Are principles specific enough to resolve a real product decision?
+
+### Why This Matters
+
+Guiding principles that do not create trade-offs are platitudes. "We value quality" is not a principle -- nobody advocates for poor quality. "We value correctness over speed-to-market" is a principle because speed-to-market is genuinely valuable and someone could reasonably choose it. X-over-Y format forces the vision author to name what the product will sacrifice, which is the only way principles become useful for downstream decision-making.
+
+### How to Check
+
+1. For each principle, check for X-over-Y structure -- is something being chosen OVER something else?
+2. Apply the "reasonable disagreement" test -- would a smart, well-intentioned person choose Y over X? If not, the principle is a platitude
+3. Construct a hypothetical product decision and check whether the principle resolves it
+4. Check that the set of principles covers the most common trade-off dimensions for this product type (simplicity vs. power, speed vs. correctness, flexibility vs. consistency, etc.)
+5. Verify no two principles contradict each other
+
+### What a Finding Looks Like
+
+- P0: "Principles include 'We value simplicity, quality, and user delight.' These are not trade-offs -- they are universally desirable attributes. No team would advocate for complexity, poor quality, or user frustration."
+- P1: "Principle 'Convention over configuration' is in X-over-Y format but does not specify what conventions or what configuration options are sacrificed. Too abstract to resolve a real decision."
+- P2: "Principles are well-formed but do not cover the speed-vs-correctness dimension, which is a common tension for this product type."
+
+### Common Failure Modes
+
+- **Platitudes**: Principles everyone agrees with ("we value quality") that rule out nothing
+- **Missing sacrifice**: X-over-Y format but Y is not genuinely attractive ("quality over bugs")
+- **Too abstract**: Principles are directionally correct but too vague to resolve specific decisions
+- **Contradictory pairs**: Two principles that cannot both be followed ("move fast" and "never ship bugs")
+
+---
+
+## Pass 5: Anti-Vision
+
+### What to Check
+
+- Does the anti-vision name specific, tempting traps -- not vague disclaimers?
+- Are the anti-vision items things the team could plausibly drift into (not absurd strawmen)?
+- Does each item explain WHY it is tempting and HOW to recognize the drift?
+- Is the anti-vision specific to THIS product, not generic warnings?
+
+### Why This Matters
+
+The anti-vision is the vision's immune system. It names the specific failure modes that are most likely given the product's domain, team, and competitive landscape. Without it, teams drift toward common traps without recognizing the drift. A good anti-vision makes the team uncomfortable because it names things they might actually do -- not things no reasonable team would do.
+
+### How to Check
+
+1. For each anti-vision item, check specificity -- does it name a concrete behavior or outcome, not a vague category?
+2. Apply the "temptation test" -- is this something the team could plausibly drift into? If the answer is "obviously not," the anti-vision item is a strawman
+3. Check whether each item explains the mechanism: why is this trap tempting, and what are the early warning signs?
+4. Verify the anti-vision items connect to the product domain -- are they specific to THIS type of product?
+5. Check that anti-vision items complement guiding principles -- if a principle says "simplicity over power," the anti-vision should name a specific way the product might become complex
+
+### What a Finding Looks Like
+
+- P0: "Anti-vision section says 'We will not build a bad product.' This is not an anti-vision -- it is a tautology. Name specific traps: 'We will not become a feature-comparison checklist tool that matches competitors feature-for-feature while losing our core simplicity advantage.'"
+- P1: "Anti-vision names 'scope creep' as a trap but does not explain which specific scope expansion is most tempting for this product or how to recognize it early."
+- P2: "Anti-vision items are specific but do not connect to the guiding principles. Each principle's 'Y' (the sacrificed value) should have a corresponding anti-vision item that names the drift toward Y."
+
+### Common Failure Modes
+
+- **Vague disclaimers**: "We won't lose focus" -- too generic to be actionable
+- **Absurd strawmen**: Names failures no team would pursue ("we won't build an insecure product")
+- **Missing mechanism**: Names the trap but not why it is tempting or how to detect drift
+- **Generic warnings**: Anti-vision items apply to any product, not THIS product specifically
+
+---
+
+## Finding Report Template
+
+```markdown
+## Vision Review Report
+
+### Pass 1: Vision Clarity
+- **P1**: Vision statement "Build the best project management tool" is a category description, not a product vision. It cannot guide feature trade-offs. Recommendation: rewrite as a specific change statement.
+
+### Pass 2: Target Audience
+- No findings
+
+### Pass 3: Competitive Landscape
+- **P2**: Competitor "Acme" is described by weaknesses only. Add at least one acknowledged strength.
+
+### Pass 4: Guiding Principles
+- **P0**: Principles are platitudes ("quality", "simplicity") without X-over-Y trade-offs. Cannot resolve downstream decisions.
+
+### Pass 5: Anti-Vision
+- **P1**: Anti-vision says "avoid scope creep" without naming which specific scope expansion is tempting.
+
+### Summary
+- P0: 1 | P1: 2 | P2: 1 | P3: 0
+- Blocks downstream: Yes (P0 in guiding principles)
+```
+
+## Severity Examples for Vision Documents
+
+### P0 (Blocks downstream phases)
+
+- Vision statement is a category description that cannot guide any decision
+- Target audience is "everyone" -- PRD cannot write meaningful personas
+- No guiding principles exist -- all downstream trade-offs are unresolved
+- Anti-vision is absent entirely
+
+### P1 (Causes significant downstream quality issues)
+
+- Vision is specific but contains unfalsifiable claims
+- Target audience is demographic-only with no behavioral definition
+- Competitive analysis lists only competitor weaknesses
+- Principles exist but are platitudes without real trade-offs
+
+### P2 (Minor issues, fix during iteration)
+
+- Vision is slightly too long to memorize
+- One competitor is described generically rather than by name
+- One principle is well-formed but could be more specific
+- Anti-vision items are specific but miss one common trap for this product type
+
+### P3 (Observations for future improvement)
+
+- Competitive landscape could include an emerging competitor
+- Anti-vision could add early warning indicators for each trap
+- Principles could be ordered by frequency of application