@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/finalization/implementation-playbook.md

@@ -10,6 +10,8 @@ The implementation playbook is the definitive reference for AI agents executing
 
 This is the most critical finalization document. If the onboarding guide tells agents "what this project is," the playbook tells them "how to do the work."
 
+## Summary
+
 ## Task Execution Protocol
 
 ### How Agents Pick Work
@@ -63,6 +65,21 @@ Read before starting:
 
 If a task does not have a context brief, the agent should create one from the specification artifacts before starting.
 
+### Minimum Context by Task Type
+
+When a per-task context block is incomplete, agents should consult this taxonomy to ensure they have sufficient context:
+
+| Task Type | Required Docs | Additional Context |
+|-----------|--------------|-------------------|
+| Backend API | `docs/api-contracts.md`, `docs/database-schema.md`, `docs/domain-models/`, `docs/coding-standards.md`, `docs/tdd-standards.md` | Relevant ADR for API style choices |
+| Frontend UI | `docs/ux-spec.md`, `docs/design-system.md`, `docs/api-contracts.md`, `docs/coding-standards.md`, `docs/tdd-standards.md` | Component patterns from design system |
+| Database migration | `docs/database-schema.md`, `docs/domain-models/`, `docs/operations-runbook.md` | Rollback strategy from ops runbook |
+| Infrastructure/CI | `docs/dev-setup.md`, `docs/git-workflow.md`, `docs/operations-runbook.md` | Deployment pipeline stages |
+| Bug fix | Relevant source code, `docs/tdd-standards.md`, `docs/coding-standards.md` | Related test files, reproduction steps |
+| Security hardening | `docs/security-review.md`, `docs/api-contracts.md`, `docs/coding-standards.md` | OWASP checklist items from security review |
+
+## Deep Guidance
+
 ## Coding Standards
 
 Coding standards ensure consistency across agents. Every agent must follow these conventions without exception. Inconsistency between agents produces a codebase that feels like it was written by different teams — because it was.
@@ -288,8 +305,8 @@ Before a task is considered complete, all quality gates must pass.
 ### Gate 1: Tests Pass
 
 ```bash
-npm test                     # All tests pass
-npm run test:coverage        # Coverage meets threshold
+make test                    # All tests pass
+make test-coverage           # Coverage meets threshold
 ```
 
 Every task must include tests for the code it adds or modifies:
@@ -301,8 +318,8 @@ Every task must include tests for the code it adds or modifies:
 ### Gate 2: Lint and Type Check
 
 ```bash
-npm run lint                 # No lint errors (warnings are allowed but discouraged)
-npm run typecheck            # No type errors
+make lint                    # No lint errors (warnings are allowed but discouraged)
+make typecheck               # No type errors
 ```
 
 Do not disable lint rules with `eslint-disable` unless the rule is genuinely wrong for that specific case, and add a comment explaining why.
@@ -310,9 +327,11 @@ Do not disable lint rules with `eslint-disable` unless the rule is genuinely wro
 ### Gate 3: Build Succeeds
 
 ```bash
-npm run build                # Production build succeeds
+make build                   # Production build succeeds
 ```
 
+> Commands shown here are examples. Use the actual commands from your project's CLAUDE.md Key Commands table.
+
 If the build fails with warnings, investigate. Warnings often become errors in stricter environments.
 
 ### Gate 4: Manual Verification
@@ -325,6 +344,12 @@ Automated tests are necessary but not sufficient. Always verify the feature work
 
 Run the full test suite, not just the tests for the changed code. New code can break existing features through unexpected interactions.
 
+### Gate 6: Evals
+
+**Gate: Evals** — Run `make eval` (or project-equivalent from CLAUDE.md Key Commands). All eval checks must pass. If a specific eval fails, consult `docs/eval-standards.md` for category descriptions and resolution guidance.
+
+Evals run collectively via `make eval`. If a specific eval category fails, consult `docs/eval-standards.md` for the category description and resolution approach.
+
 ## Inter-Agent Handoff
 
 When one agent completes a task and another agent will build on it, the completing agent must communicate:
@@ -402,3 +427,56 @@ The playbook is a living document. Update it when:
 - Agent coordination issues arise (add to parallel work rules)
 
 The playbook should be the first document agents read before their first task, and the document they reference throughout implementation. If an agent asks a question that the playbook should answer, the answer goes in the playbook.
+
+### Error Recovery
+
+> The depth and specificity of error recovery guidance in CLAUDE.md depends on the `workflow-audit` step's methodology depth. At MVP depth, error recovery may be minimal.
+
+When quality gates fail during implementation:
+
+**Test failures:**
+1. Read the failing test to understand the expected behavior
+2. Check if the test is testing your change or pre-existing functionality
+3. If your change broke the test: fix the implementation, not the test
+4. If the test is wrong: document why and update the test with the fix
+5. Re-run the full test suite, not just the failing test
+
+**CI failures:**
+1. Pull latest main and rebase your branch
+2. Run `make check` locally to reproduce the failure
+3. If the failure is environment-specific: check dev-setup.md for requirements
+4. If the failure is a flaky test: document the flakiness and retry once
+
+### Eval Failure Recovery
+
+When `make eval` fails during implementation:
+
+1. **Read the failing test name** — eval category names indicate what's wrong (e.g., `adherence` = coding standard violation, `consistency` = cross-document mismatch)
+2. **Check `docs/eval-standards.md`** (if it exists) for category-specific guidance
+3. **Common eval failures**:
+   - **Adherence evals**: Code doesn't match coding-standards.md patterns. Fix: read the specific standard and adjust code.
+   - **Consistency evals**: Document references are stale or contradictory. Fix: update the reference to match current state.
+   - **Structure evals**: File/directory doesn't match project-structure.md. Fix: move files to correct location.
+   - **Security evals**: Missing input validation or auth check. Fix: add the missing security control per security-review.md.
+4. **If eval seems wrong**: Check if the eval itself is outdated. Flag for upstream review rather than working around it.
+
+**Spec gap discovered during implementation:**
+1. Document the gap with specific details (what's missing, what's needed)
+2. Check if an ADR or architecture decision covers the case
+3. If the gap is small: make a judgment call, document it in the commit message
+4. If the gap is significant: pause the task and flag it for upstream resolution
+
+**Agent produces incorrect output:**
+1. Review the task description and acceptance criteria
+2. Diff the output against the expected behavior
+3. If the task description was ambiguous: improve it for future agents
+4. Roll back the incorrect changes and retry with clearer context
+
+### Dependency Failure
+
+When a task's upstream dependency hasn't merged or has failed:
+
+1. **Check the dependency task status** in docs/implementation-plan.md
+2. **If in-progress**: Wait for it to merge. Do not start work that depends on uncommitted changes.
+3. **If failed/blocked**: Flag for human review. The task may need to be reworked, reordered, or its dependency removed.
+4. **If the dependency is in a different agent's worktree**: Coordinate via AGENTS.md or the task tracking system. Never duplicate work.

package/knowledge/product/gap-analysis.md

@@ -6,7 +6,11 @@ topics: [gap-analysis, requirements, completeness, ambiguity, edge-cases]
 
 # Gap Analysis
 
-Gap analysis is the systematic process of finding what is missing from a set of requirements or specifications. A gap is anything that an implementing team would need to know but that the document does not tell them. Gaps are not errors (things stated incorrectly) — they are omissions (things not stated at all).
+## Summary
+
+Gap analysis is the systematic process of finding what is missing from a set of requirements or specifications. A gap is anything that an implementing team would need to know but that the document does not tell them. Gaps are not errors (things stated incorrectly) — they are omissions (things not stated at all). The process uses section-by-section review, cross-reference checking, edge case enumeration, ambiguity detection, and contradiction detection to surface omissions before they become expensive implementation surprises.
+
+## Deep Guidance
 
 ## Systematic Analysis Approaches
 

package/knowledge/product/prd-craft.md

@@ -8,13 +8,36 @@ topics: [prd, requirements, product, scoping]
 
 A Product Requirements Document is the single source of truth for what is being built and why. It defines the problem, the users, the scope, and the success criteria. Everything in the pipeline flows from the PRD — domain models, architecture, implementation tasks. A weak PRD propagates weakness through every downstream artifact.
 
-This document covers what makes a good PRD, what makes a bad one, and how to tell the difference.
+## Summary
 
-## Problem Statement
+### PRD Structure
+
+A complete PRD includes these sections:
+1. **Problem Statement** — Specific, testable, grounded in observable reality. Names a user group, describes a pain point, includes quantitative evidence.
+2. **Target Users** — Personas with roles, needs, current behavior, constraints, and success criteria. Typically 2-4 meaningful personas.
+3. **Feature Scoping** — Three explicit lists: In Scope (v1), Out of Scope, and Deferred (future). Each in-scope feature detailed enough to estimate.
+4. **Success Criteria** — Measurable outcomes tied to the problem statement with target values and measurement methods.
+5. **Constraints** — Technical, timeline, budget, team, and regulatory constraints traceable to architectural decisions.
+6. **Non-Functional Requirements** — Quantified performance, scalability, availability, security, accessibility, data, i18n, browser/device support, and monitoring requirements.
+7. **Competitive Context** — What exists, how this differs, why users would switch.
+
+### Quality Criteria
+
+- Problem statement is specific and testable
+- Features are prioritized with MoSCoW (Must/Should/Could/Won't)
+- Success criteria have target values and measurement methods
+- NFRs are quantified (not "fast" but "p95 under 200ms")
+- Error scenarios and edge cases are addressed
+- The PRD says WHAT, not HOW
+- Every feature is detailed enough for estimation without prescribing implementation
+
+## Deep Guidance
+
+### Problem Statement
 
 The problem statement is the foundation. If it is wrong, everything built on top of it is wrong.
 
-### What Makes a Good Problem Statement
+#### What Makes a Good Problem Statement
 
 A good problem statement is **specific**, **testable**, and **grounded in observable reality**.
 
@@ -29,7 +52,7 @@ A good problem statement is **specific**, **testable**, and **grounded in observ
 - "Users want a better dashboard." (Aspirational, not grounded. What is wrong with the current one? What does "better" mean?)
 - "We need to modernize our technology stack." (Technology is not a problem — what user-facing or business issue does the old stack cause?)
 
-### Problem Statement Checklist
+#### Problem Statement Checklist
 
 - [ ] Names a specific user group (not "users" or "everyone")
 - [ ] Describes an observable behavior or pain point (not a desired state)
@@ -37,9 +60,9 @@ A good problem statement is **specific**, **testable**, and **grounded in observ
 - [ ] Does not prescribe a solution (the problem is not "we need feature X")
 - [ ] Can be validated — you can measure whether the problem is solved
 
-## Target Users
+### Target Users — Detailed Persona Methodology
 
-### Personas with Needs
+#### Personas with Needs
 
 Each persona should have:
 - **Role or description** — Who they are in relation to the product.
@@ -69,17 +92,17 @@ Each persona should have:
 
 The bad persona tells the implementation team nothing actionable. It does not constrain design decisions.
 
-### How Many Personas
+#### How Many Personas
 
 Most products have 2-4 meaningful personas. If a PRD lists more than 6, the product scope is likely too broad. If it lists only 1, secondary users (admins, support staff, integration partners) may be missing.
 
-### Anti-pattern: The Everything User
+#### Anti-pattern: The Everything User
 
 A persona that represents all users is no persona at all. "Power users who want advanced features AND casual users who want simplicity" describes a contradiction, not a persona. Different personas may have conflicting needs — that is fine, but the PRD must state which takes priority.
 
-## Feature Scoping
+### Feature Scoping — Depth
 
-### What Is In, What Is Out, What Is Deferred
+#### What Is In, What Is Out, What Is Deferred
 
 Every PRD should have three explicit lists:
 
@@ -126,7 +149,7 @@ Every PRD should have three explicit lists:
 
 This tells you nothing about boundaries. Is "user management" basic registration or full RBAC with teams and permissions? Is "analytics" a page view counter or a business intelligence suite?
 
-### MoSCoW Prioritization
+#### MoSCoW Prioritization — In Depth
 
 When the in-scope list is large, use MoSCoW to further prioritize:
 
@@ -160,7 +183,7 @@ Won't Have:
 - Social login
 ```
 
-### Feature Detail Level
+#### Feature Detail Level
 
 Each in-scope feature needs enough detail to be estimable:
 
@@ -175,9 +198,9 @@ Each in-scope feature needs enough detail to be estimable:
 
 The PRD says WHAT, not HOW.
 
-## Success Criteria
+### Success Criteria — Depth
 
-### Measurable Outcomes
+#### Measurable Outcomes
 
 Success criteria define how you will know the product works. They must be measurable, specific, and tied to the problem statement.
 
@@ -193,7 +216,7 @@ Success criteria define how you will know the product works. They must be measur
 - "Revenue increases." (Not tied to the problem. Revenue can increase for many reasons.)
 - "We ship on time." (Success criteria for the project, not the product)
 
-### Types of Success Criteria
+#### Types of Success Criteria
 
 1. **User behavior metrics** — Conversion rates, completion rates, time-on-task, error rates.
 2. **Business metrics** — Revenue impact, cost reduction, customer acquisition.
@@ -202,9 +225,9 @@ Success criteria define how you will know the product works. They must be measur
 
 Every success criterion should have a **target value** and a **measurement method**. "Checkout abandonment under 40% as measured by analytics funnel tracking" is complete. "Checkout abandonment decreases" is not.
 
-## Constraints
+### Constraints — Detailed Categories
 
-### Categories of Constraints
+#### Categories of Constraints
 
 **Technical constraints:**
 - Existing systems that must be integrated with.
@@ -233,7 +256,7 @@ Every success criterion should have a **target value** and a **measurement metho
 - Accessibility mandates (ADA, WCAG requirements).
 - Industry-specific regulations.
 
-### How Constraints Affect Downstream Artifacts
+#### How Constraints Affect Downstream Artifacts
 
 Each constraint should be traceable to architectural decisions:
 - "Must use PostgreSQL" → ADR for database choice.
@@ -241,11 +264,9 @@ Each constraint should be traceable to architectural decisions:
 - "Team of 3 developers" → Implementation tasks sized for 3 parallel workers.
 - "Launch by March 1" → Feature scope fits within timeline.
 
-## Non-Functional Requirements
-
-NFRs define HOW the system should behave, not WHAT it should do. They are frequently under-specified in PRDs, which leads to expensive rework.
+### NFR Quantification Patterns
 
-### Quantified NFRs
+#### Quantified NFRs
 
 **Good:**
 - "Page load time: p95 under 2 seconds on 4G mobile connection."
@@ -260,7 +281,7 @@ NFRs define HOW the system should behave, not WHAT it should do. They are freque
 - "Scalable." (To what? 100 users? 1 million users? What is the growth curve?)
 - "Secure." (Against what threats? To what standard?)
 
-### NFR Categories Checklist
+#### NFR Categories Checklist
 
 - [ ] **Performance** — Response times (p50, p95, p99), throughput, page load times
 - [ ] **Scalability** — Concurrent users, data volume, growth rate
@@ -272,42 +293,42 @@ NFRs define HOW the system should behave, not WHAT it should do. They are freque
 - [ ] **Browser/device support** — Minimum browser versions, mobile support, responsive breakpoints
 - [ ] **Monitoring** — What needs to be observable? Alerting thresholds?
 
-## Competitive Context
+### Competitive Context Analysis
 
-### What to Include
+#### What to Include
 
 - **What exists** — Name competing products and what they do well.
 - **How this is different** — Specific differentiators, not "we're better."
 - **Why users would switch** — What pain does this product solve that competitors do not?
 - **What to learn from** — Features or patterns from competitors worth adopting.
 
-### What NOT to Include
+#### What NOT to Include
 
 - Exhaustive competitor feature matrices (belongs in market research, not PRD).
 - Competitive strategy or positioning (belongs in business plan, not PRD).
 - Pricing comparisons (unless pricing is a product feature).
 
-## Common PRD Failures
+### Common PRD Failures
 
-### The "Requirements as Solutions" Failure
+#### The "Requirements as Solutions" Failure
 PRD prescribes technical solutions instead of stating requirements. "Use Redis for caching" belongs in architecture, not the PRD. The PRD should say "response time under 200ms" — how to achieve that is an architectural decision.
 
-### The "Missing Sad Path" Failure
+#### The "Missing Sad Path" Failure
 PRD describes only happy paths. What happens when payment fails? When the user's session expires during checkout? When the network drops? When the form has invalid data? Every user action that can fail should have at least a sentence about what happens.
 
-### The "Everyone Is a User" Failure
+#### The "Everyone Is a User" Failure
 PRD addresses "users" as a monolith instead of identifying distinct personas with distinct needs. Admins, end users, API consumers, and support staff have different requirements.
 
-### The "Implied API" Failure
+#### The "Implied API" Failure
 PRD describes a UI but implies an API without stating it. "Users can view their order history" implies GET /orders, data model for orders, pagination, filtering, sorting. These implications should be explicit in the PRD.
 
-### The "No Boundaries" Failure
+#### The "No Boundaries" Failure
 PRD states what is in scope but never states what is out. Every documentation phase becomes a scope negotiation.
 
-### The "Success Is Shipping" Failure
+#### The "Success Is Shipping" Failure
 PRD has no success criteria beyond "launch the product." Without measurable outcomes, there is no way to know if the product solved the problem.
 
-## PRD Quality Checklist
+### PRD Quality Checklist
 
 Before considering a PRD complete:
 

package/knowledge/product/prd-innovation.md

@@ -10,6 +10,18 @@ This knowledge covers feature-level innovation — discovering new capabilities,
 
 This is distinct from user story innovation (`user-story-innovation.md`), which covers UX-level enhancements to existing features. If an idea doesn't require a new PRD section or feature entry, it belongs in user story innovation, not here.
 
+## Summary
+
+- **Scope**: Feature-level innovation (new capabilities, competitive gaps, defensive improvements). UX polish on existing features belongs in user story innovation.
+- **Competitive analysis**: Research direct competitors, adjacent products, and emerging patterns. Classify findings as table-stakes (must-have), differentiator (evaluate), or copied-feature (skip).
+- **UX gap analysis**: Evaluate first-60-seconds experience, flow friction points, and missing flows that force workarounds.
+- **Missing expected features**: Search/discovery, data management (bulk import/export, undo), communication (notifications), and personalization (settings, saved views).
+- **AI-native opportunities**: Natural language interfaces, auto-categorization, predictive behavior, and content generation. Must pass the "magic vs. gimmick" test.
+- **Defensive product thinking**: Write plausible 1-star reviews to identify gaps; analyze abandonment barriers (complexity, performance, trust, value, integration).
+- **Evaluation framework**: Cost (trivial/moderate/significant) x Impact (nice-to-have/noticeable/differentiator). Must-have v1 = differentiator at any cost up to moderate, or noticeable at trivial cost.
+
+## Deep Guidance
+
 ## Scope Boundary
 
 **In scope:**

package/knowledge/product/vision-craft.md

@@ -0,0 +1,213 @@
+---
+name: vision-craft
+description: What makes a good product vision — strategic framing, audience definition, competitive positioning, guiding principles
+topics: [vision, strategy, product, positioning, competitive-analysis]
+---
+
+# Vision Craft
+
+A product vision document is the strategic North Star that guides all downstream product decisions. It answers "why does this product exist?" and "what positive change does it create in the world?" — questions that are upstream of the PRD's "what should we build?" Everything in the pipeline flows from the vision. A weak vision produces a PRD without strategic grounding, which produces features without coherent purpose.
+
+## Summary
+
+### Vision Document Structure
+
+A complete product vision document includes these sections:
+1. **Vision Statement** — One inspiring sentence describing the positive change the product creates. Not a feature description. Concise enough to remember and repeat.
+2. **Elevator Pitch** — Geoffrey Moore template: For [target customer] who [need], [product] is a [category] that [key benefit]. Unlike [alternative], our product [differentiation].
+3. **Problem Space** — The pain in vivid detail: who feels it, how they cope, why existing solutions fail.
+4. **Target Audience** — Personas defined by behaviors and motivations, not demographics. Primary and secondary audiences with context of use.
+5. **Value Proposition** — Unique value framed as outcomes, not features. Why someone would choose this over alternatives.
+6. **Competitive Landscape** — Direct competitors, indirect alternatives, "do nothing" option. Honest about strengths and weaknesses.
+7. **Guiding Principles** — 3-5 design tenets framed as prioritization tradeoffs ("We choose X over Y").
+8. **Anti-Vision** — What the product is NOT. Traps to avoid. Directions that would dilute the vision.
+9. **Business Model Intuition** — Revenue model, unit economics assumptions, go-to-market direction.
+10. **Success Criteria** — Leading indicators, year 1 milestones, year 3 aspirations, what failure looks like.
+11. **Strategic Risks & Assumptions** — Key bets, what could invalidate them, severity and mitigation.
+12. **Open Questions** — Unresolved strategic questions for future consideration.
+
+### Quality Criteria
+
+- Vision statement describes positive change, not a product feature
+- Vision statement is concise enough to remember after hearing once
+- Guiding principles create real tradeoffs (if nobody would disagree, it's not a principle)
+- Competitive analysis is honest about the product's weaknesses, not just strengths
+- Target audience describes behaviors and motivations, not demographics
+- Business model section addresses sustainability without being a full business plan
+- Anti-vision prevents real traps, not just vague disclaimers
+
+## Deep Guidance
+
+### Vision Statement
+
+The vision statement is the foundation. If it fails, the entire document lacks a North Star.
+
+#### What Makes a Good Vision Statement
+
+A good vision statement is **inspiring**, **concise**, **enduring**, and **customer-centric**. It describes the positive change the product creates in the world — not a feature, not a business metric.
+
+**Good examples:**
+- "Accelerate the world's transition to sustainable energy" (Tesla)
+- "Belong anywhere" (Airbnb)
+- "Create economic opportunity for every member of the global workforce" (LinkedIn)
+- "Every book ever printed, in any language, all available in 60 seconds" (Kindle)
+- "Make work life simpler, more pleasant, and more productive" (Slack)
+- "Increase the GDP of the internet" (Stripe)
+
+**Bad examples:**
+- "Be the #1 project management tool in the enterprise market" (business metric, not positive change)
+- "Build an AI-powered platform for data analytics" (solution description, not vision)
+- "Provide a seamless user experience for managing tasks" (vague, feature-level)
+- "Disrupt the healthcare industry" (aspirational buzzword, says nothing specific)
+
+#### Roman Pichler's Vision Quality Checklist
+
+- **Inspiring** — Describes a positive change that motivates people
+- **Shared** — Co-created with the team, not handed down from above
+- **Ethical** — Does not cause harm to people or the planet
+- **Concise** — Easy to understand, remember, and repeat
+- **Ambitious** — A big, audacious goal (BHAG) that stretches beyond the comfortable
+- **Enduring** — Guides for 5-10 years; free from solution-specific assumptions
+
+### Geoffrey Moore's Elevator Pitch Template
+
+From *Crossing the Chasm* — the most widely used single-statement framework for articulating product positioning:
+
+```
+For [target customer]
+Who [statement of need or opportunity],
+The [product name] is a [product category]
+That [key benefit, reason to buy].
+Unlike [primary competitive alternative],
+Our product [statement of primary differentiation].
+```
+
+**When to use:** As a structured exercise to force clarity about target customer, need, category, and differentiation. The output should feel like a natural sentence, not a fill-in-the-blank template.
+
+### Guiding Principles
+
+Guiding principles are design tenets that constrain decisions. They are NOT platitudes.
+
+#### The Test
+
+If nobody would disagree with a principle, it's not a principle — it's a platitude. "We value quality" is not a principle. "We choose correctness over speed" is a principle because it implies a real tradeoff (some teams would choose the opposite).
+
+**Good principles (create real tradeoffs):**
+- "We choose simplicity over power" (implies some features won't exist)
+- "We choose transparency over control" (implies users see everything, even messy internals)
+- "We choose speed of iteration over perfection" (implies shipping rough work)
+- "We choose privacy over personalization" (implies less-tailored experiences)
+
+**Bad principles (platitudes):**
+- "We value user experience" (who wouldn't?)
+- "We build reliable software" (this is table stakes, not a principle)
+- "We care about security" (no one would say they don't)
+
+### Anti-Vision
+
+The anti-vision explicitly names what the product is NOT. This is critical for preventing scope creep and maintaining strategic focus.
+
+#### What to Include
+
+- Features the team will be tempted to build but shouldn't
+- Common traps in this product space that catch every competitor
+- Directions that would dilute the core value proposition
+- "If we find ourselves doing X, we've lost the plot"
+
+#### Why It Matters
+
+Without an anti-vision, the team defaults to "yes" for every reasonable-sounding feature request. The anti-vision gives explicit permission to say "no."
+
+### Competitive Landscape
+
+#### Honest Competitive Analysis
+
+The competitive landscape section must be honest — acknowledge what competitors do well, not just where they fall short. A dishonest competitive analysis ("all competitors are terrible") undermines credibility and leads to blind spots in product strategy.
+
+**Structure:**
+- **Direct competitors** — Products solving the same problem for the same users
+- **Indirect alternatives** — Different approaches to the same underlying need
+- **"Do nothing" option** — The status quo. Often the strongest competitor.
+
+For each: what they do well, where they fall short, and why users would choose your product over them.
+
+### Common Anti-Patterns
+
+1. **Confusing Vision with Strategy** — The vision says what the world looks like when the product succeeds. The strategy says how you get there. Keep them separate.
+2. **Tying Vision to a Solution** — "Build the best X" references a specific product form. "Enable Y for Z people" survives pivots.
+3. **Failing to Inspire** — Corporate boilerplate doesn't motivate teams. Co-create the vision; don't hand it down.
+4. **Changing the Vision Frequently** — A vision should endure for years. If it changes quarterly, it's not a vision — it's a roadmap item.
+5. **Overly Broad Target Audience** — "Everyone" is not a target audience. Specificity enables focus.
+6. **Features as Needs** — Listing features (solution space) instead of needs (problem space) limits the team's design freedom.
+7. **Decorative Wall Statement** — A vision that hangs on the wall but never guides actual decisions is worse than no vision at all.
+
+### The Product Development Hierarchy
+
+Vision sits at the top of this hierarchy:
+
+```
+Company Mission / Purpose
+    ↓
+Company Vision
+    ↓
+Product Vision          ← THIS DOCUMENT
+    ↓
+Product Strategy
+    ↓
+Product Requirements    ← PRD (docs/plan.md)
+    ↓
+Implementation
+```
+
+The vision document should inform the PRD, not the other way around. When the PRD and vision conflict, revisit the vision first.
+
+### Success Criteria & Measurement
+
+Success criteria in a vision document are directional — they define what "winning" looks like without the precision of a PRD's success metrics.
+
+#### Levels of Success Measurement
+
+- **Leading indicators** — Early signals that validate the vision direction. These are behavioral: are users doing the thing you expected? Are they coming back? Example: "Users who complete onboarding return within 48 hours."
+- **Year 1 milestones** — Concrete, time-bound achievements that demonstrate market fit. Example: "1,000 active users creating at least one project per week."
+- **Year 3 aspirations** — Ambitious but grounded targets that show the vision is being realized. These should feel like a stretch but not fantasy.
+- **Failure indicators** — What would make this a failure even if it ships on time and works correctly? Example: "If users create an account but never return after day 1, the core value proposition is wrong."
+
+#### Common Mistakes in Success Criteria
+
+- Vanity metrics ("1 million downloads") instead of engagement metrics ("daily active usage")
+- Unmeasurable aspirations ("users love the product") instead of observable behavior
+- Missing the "failure despite shipping" scenario — the most dangerous blind spot
+- Setting criteria so low they're guaranteed, removing the diagnostic value
+
+### Business Model Intuition
+
+The vision document captures directional thinking about sustainability, not a financial model.
+
+#### What to Include
+
+- **Revenue model** — How does this make money? Subscription, freemium, marketplace commission, enterprise licensing, usage-based? Pick one primary model and explain why.
+- **Unit economics direction** — What are the key cost drivers? What does a "unit" of value look like? Does the economics improve with scale?
+- **Go-to-market intuition** — How do users discover this product? Product-led growth, sales-led, community-driven, partnership channels? The answer shapes everything from pricing to features.
+
+#### What NOT to Include
+
+- Detailed financial projections (that's a business plan)
+- Multi-year revenue forecasts (that's a pitch deck)
+- Competitive pricing analysis (that's market research — do it, but don't put it in the vision)
+
+### Vision-to-PRD Handoff
+
+The vision document's primary downstream consumer is the PRD. A well-written vision makes PRD creation straightforward; a vague vision forces the PRD author to make strategic decisions that should have been settled upstream.
+
+#### Handoff Checklist
+
+Before declaring the vision ready for PRD creation, verify:
+
+1. **Problem Space** maps cleanly to PRD's Problem Statement
+2. **Target Audience** personas are specific enough for user stories
+3. **Guiding Principles** are concrete enough to resolve "should we build X?" questions
+4. **Competitive Landscape** provides enough context to differentiate features
+5. **Anti-Vision** is clear enough to reject out-of-scope feature requests
+6. **Open Questions** do not include anything that would block product definition
+
+If any of these fail, the vision needs another pass before the PRD can begin.

package/knowledge/review/review-adr.md

@@ -10,6 +10,18 @@ ADRs encode the "why" behind the architecture. They must be complete (every sign
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Decision Coverage**: Every significant architectural decision has an ADR; technology choices, pattern selections, and constraint trade-offs all recorded.
+- **Pass 2 — Rationale Quality**: Alternatives are genuinely viable (not straw-manned); consequences are honest with both positives and negatives.
+- **Pass 3 — Contradiction Detection**: No two ADRs make conflicting decisions without explicit acknowledgment; supersession relationships documented.
+- **Pass 4 — Implied Decision Mining**: Decisions visible in artifacts but never formally recorded as ADRs are identified and flagged.
+- **Pass 5 — Status Hygiene**: ADR statuses reflect reality; no stale "proposed" ADRs; supersession chains are clean.
+- **Pass 6 — Cross-Reference Integrity**: Cross-references between ADRs are correct and bidirectional; no broken or circular reference chains.
+- **Pass 7 — Downstream Readiness**: Technology and pattern decisions are finalized in "accepted" status so architecture can proceed without ambiguity.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Decision Coverage
@@ -201,3 +213,35 @@ For each category, verify at least one accepted ADR covers it. If a category is
 - P0: "The monolith-vs-services question has two proposed ADRs (ADR-003, ADR-004) but neither is accepted. The system architecture step cannot define component boundaries."
 - P1: "Authentication approach is not covered by any ADR. The system architecture step needs to know the auth pattern to design the auth component."
 - P2: "Monitoring strategy has no ADR. This could be deferred to the operations step but should be noted."
+
+### Example Review Finding
+
+```markdown
+### Finding: Straw-man alternatives mask the real decision rationale
+
+**Pass:** 2 — Rationale Quality
+**Priority:** P0
+**Location:** ADR-003 "Use React for Frontend Framework"
+
+**Issue:** ADR-003 lists two alternatives: "Use jQuery" and "Build from scratch
+with vanilla JS." Neither is a genuinely viable alternative for a 2024 SPA with
+the complexity described in the PRD. The real alternatives — Vue, Svelte, Angular
+— are not mentioned.
+
+The consequences section lists four benefits and zero costs. React has well-known
+trade-offs (large bundle size, JSX learning curve, frequent ecosystem churn) that
+are absent.
+
+**Impact:** When conditions change (e.g., bundle size becomes a priority, or the
+team grows to include Vue-experienced developers), there is no documented rationale
+for why React was chosen over comparable frameworks. The ADR cannot be meaningfully
+re-evaluated because the real decision criteria were never recorded.
+
+**Recommendation:** Replace alternatives with genuinely considered options (Vue 3,
+Svelte/SvelteKit, Angular). For each, document honest pros and cons. Add negative
+consequences to the React decision: bundle size overhead, ecosystem churn rate,
+and dependency on the React team's architectural direction (Server Components,
+compiler changes).
+
+**Trace:** ADR-003 → blocks Architecture Phase component structure decisions
+```