@zigrivers/scaffold 2.1.2 → 2.38.0

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
@@ -174,3 +185,54 @@ A quality gate that exists in documentation but not in CI is not a gate. If the
 - P0: "Testing strategy requires 80% code coverage but the CI pipeline has no coverage reporting or enforcement. The requirement is unverifiable."
 - P1: "Security scanning is listed as a quality requirement but no specific tool or CI pipeline step implements it."
 - P2: "Quality gates run linting, unit tests, and integration tests, but do not validate database migrations. A broken migration would pass all gates and fail in production."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Copy-Pasted Generic Strategy
+
+The testing strategy is a boilerplate document that says "we will have unit tests, integration tests, and E2E tests" without connecting to the actual architecture. No mention of specific components, no mapping of test types to architectural layers, no project-specific invariants.
+
+**How to spot it:** The strategy could be copy-pasted into any other project and still read correctly. No component names, no domain terms, no architecture-specific decisions.
+
+### 2. Testing Strategy Disconnected from Architecture
+
+The strategy defines test types and coverage goals but does not reference the system architecture. Tests are organized by test framework (Jest unit tests, Playwright E2E tests) rather than by architectural component. This makes it impossible to verify coverage — you cannot tell which components are tested and which are not.
+
+**How to spot it:** Search for component names from the architecture document. If none appear in the testing strategy, the two documents are disconnected.
+
+### 3. Mock-Everything Mentality
+
+Every external dependency is mocked, including the database. Unit test coverage is high, but no test ever executes a real query, a real HTTP call, or a real message queue interaction. The test suite provides confidence that the mocking layer works, not that the system works.
+
+**Example finding:**
+
+```markdown
+## Finding: TSR-009
+
+**Priority:** P1
+**Pass:** Integration Boundary Coverage (Pass 5)
+**Document:** docs/testing-strategy.md, Section 4.2
+
+**Issue:** All database tests use an in-memory mock repository. The repository interface
+is tested, but no test ever executes SQL against a real PostgreSQL instance. The following
+risks are untested: query syntax errors, constraint violations, transaction isolation
+behavior, migration correctness.
+
+**Recommendation:** Add integration tests using testcontainers or a CI-managed PostgreSQL
+instance for at least the OrderRepository and UserRepository (the two repositories with
+complex queries).
+```
+
+### 4. No Negative Test Scenarios
+
+The strategy defines tests for the happy path but never specifies what happens when things fail. No test scenarios for invalid input, network timeouts, concurrent modification, or resource exhaustion. The system is verified to work when everything goes right — the most uninteresting case.
+
+**How to spot it:** Scan test scenario descriptions for words like "invalid," "timeout," "failure," "error," "reject," "concurrent," "duplicate." If these are absent, negative scenarios are missing.
+
+### 5. Coverage Percentage as the Only Quality Metric
+
+The strategy defines 80% code coverage as the quality gate but specifies no other quality criteria. High coverage with no assertion quality means tests that execute code paths without verifying behavior — "tests" that call functions and ignore the return value. Coverage measures how much code was run, not whether it was tested correctly.
+
+**How to spot it:** The quality gates section mentions only code coverage. No mention of mutation testing, assertion density, test execution time budgets, or flakiness tracking.

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
@@ -170,3 +181,57 @@ Stories are the primary input to domain discovery in the domain modeling step. I
 - P1: "US-007 ('As a teacher, I want to manage my classes') — acceptance criteria say 'classes are managed correctly.' No mention of what entities are involved (Class, Enrollment, Student?), what state transitions occur, or what business rules apply. Domain modeling will have to guess."
 - P2: "Cross-story entity naming is inconsistent: US-003 uses 'User,' US-008 uses 'Account,' US-015 uses 'Member.' These may be different bounded context terms or may be accidental inconsistency — clarify before domain modeling."
 - P2: "Stories in the 'Payments' epic mention 'processing a payment' but no acceptance criteria describe the payment lifecycle states (pending → processing → completed/failed). Domain events cannot be discovered from these stories."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Reviewing Against a Generic Checklist Instead of the PRD
+
+The reviewer checks whether stories have acceptance criteria and follow INVEST principles, but never opens the PRD to verify coverage. The stories could be missing entire PRD features and this review would not catch it. Reviews must cross-reference the PRD — checking story quality without checking story completeness misses the highest-severity failure mode.
+
+**How to spot it:** The review report contains no references to specific PRD sections. Findings are all about story quality (vague criteria, poor sizing) and none about story coverage (missing features, missing flows).
+
+### 2. Accepting Vague Acceptance Criteria as "Good Enough"
+
+The reviewer sees acceptance criteria like "user can manage their profile" and does not flag it because the intent is clear. But intent is not implementation guidance. Two agents reading "manage their profile" will implement different field sets, different validation rules, and different UX flows. Acceptance criteria must be testable — if you cannot write an automated test directly from the criterion, it is too vague.
+
+**Example finding:**
+
+```markdown
+## Finding: USR-014
+
+**Priority:** P1
+**Pass:** Acceptance Criteria Quality (Pass 2)
+**Document:** docs/user-stories.md, US-008
+
+**Issue:** Acceptance criteria for US-008 ("As a user, I want to manage my profile"):
+  - "Given I am logged in, when I update my profile, then my changes are saved"
+
+This criterion does not specify: which fields are editable, what validation rules apply,
+whether partial updates are supported, what happens on validation failure, or whether
+changes require re-authentication (e.g., email change).
+
+**Recommendation:** Replace with specific Given/When/Then scenarios:
+  - Given I am logged in, when I change my display name to a valid name (1-100 chars), then my display name is updated
+  - Given I am logged in, when I change my email, then a verification email is sent to the new address and the email is not changed until verified
+  - Given I am logged in, when I submit a display name longer than 100 characters, then I see a validation error
+```
+
+### 3. Ignoring Story Dependencies
+
+The reviewer checks each story in isolation but never maps dependencies between stories. Stories that secretly depend on each other are not flagged. This creates false parallelization opportunities downstream — the implementation tasks phase will mark these as parallel, and agents will produce conflicting work.
+
+**How to spot it:** The review report has no findings from Pass 3 (Story Independence). Dependencies are only discovered later during implementation tasks or during actual implementation.
+
+### 4. Persona Name Drift Without Flagging
+
+The PRD defines personas as "Teacher," "Student," and "Admin." Stories reference "Instructor," "Learner," and "Administrator." The reviewer does not flag the terminology mismatch because the mapping is obvious to a human. But downstream, the domain model and implementation tasks may use either set of terms inconsistently, creating confusion.
+
+**How to spot it:** Compare persona names in the PRD with persona names in story "As a..." statements. Any mismatch is a finding, even if the intent is obvious.
+
+### 5. Reviewing Only Happy-Path Stories
+
+The reviewer verifies that the main user flows have stories but does not check for error handling, edge cases, or administrative workflows. Stories exist for "user creates an account" and "user places an order" but not for "user enters invalid payment info," "user tries to order an out-of-stock item," or "admin resolves a disputed transaction." These missing stories become missing tasks and missing implementations.
+
+**How to spot it:** Count the ratio of happy-path stories to error/edge-case stories. If the ratio is heavily skewed (e.g., 20 happy-path stories and 2 error stories), error handling is systematically under-specified.

package/knowledge/review/{review-ux-spec.md → review-ux-specification.md}

@@ -1,7 +1,7 @@
 ---
-name: review-ux-spec
+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
@@ -206,3 +218,39 @@ When the UX spec designs components that do not match the architecture's compone
 - P1: "The UX spec designs an 'OrderSummaryWidget' that combines order details, customer info, and payment status. The architecture separates these into three independent components (OrderComponent, CustomerComponent, PaymentComponent) with separate data sources."
 - P1: "The UX spec assumes global state for user preferences (accessible from any component), but the architecture specifies component-local state with prop drilling."
 - P2: "The UX spec's 'ProductCard' component bundles product image, price, and add-to-cart button. The architecture models 'ProductDisplay' and 'CartAction' as separate concerns."
+
+### Example Review Finding
+
+```markdown
+### Finding: Dashboard has no empty state or loading state design
+
+**Pass:** 3 — Interaction State Completeness
+**Priority:** P0
+**Location:** UX Spec Section 4.1 "User Dashboard"
+
+**Issue:** The dashboard screen shows charts (order volume, revenue trend) and
+summary metrics (total orders, account balance, recent activity). The spec provides
+only the populated state — what the screen looks like with data.
+
+Missing states:
+- **Empty state:** A new user with zero orders sees empty chart containers with
+  no axes, no labels, and no guidance. The metrics show "$0" and "0 orders" with
+  no context.
+- **Loading state:** When dashboard data is being fetched (3 separate API calls
+  per the API contract), what does the user see? No skeleton, spinner, or
+  progressive loading is specified.
+- **Partial error state:** If the revenue chart API fails but the orders API
+  succeeds, does the entire dashboard show an error, or just the revenue widget?
+
+**Impact:** Implementing agents will either show blank containers (confusing for
+new users), a full-page spinner (poor perceived performance), or nothing at all
+while loading. The first-time user experience — which is critical for activation
+metrics in the PRD — is completely undesigned.
+
+**Recommendation:** Design three additional states:
+1. Empty state with onboarding CTA ("Create your first order to see analytics here")
+2. Skeleton loading state with placeholder shapes matching the populated layout
+3. Per-widget error state with retry button, so partial failures are isolated
+
+**Trace:** UX Spec 4.1 → PRD Success Metric "70% user activation within 7 days"
+```

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