@zigrivers/scaffold 2.1.1 → 2.28.1

package/knowledge/core/ux-specification.md

@@ -1,7 +1,7 @@
 ---
 name: ux-specification
-description: UX documentation patterns, design systems, accessibility, and component architecture
-topics: [ux, design-system, accessibility, wireframes, user-flows, responsive-design, components]
+description: UX documentation patterns — user flows, interaction states, component architecture, accessibility, and responsive behavior
+topics: [ux, accessibility, wireframes, user-flows, responsive-design, components, interaction-states]
 ---
 
 ## User Flow Documentation
@@ -128,148 +128,11 @@ Define how data flows through the component tree:
 
 **Promotion rule:** A component starts as page-specific. When a second feature needs the same component, promote it to shared. Don't pre-optimize by making everything shared from the start.
 
-## Design System
+## Design System Reference
 
-A design system is the set of constraints and building blocks that ensure visual consistency across the entire application. It includes design tokens, base components, and usage patterns.
+Design tokens (colors, typography, spacing, borders, shadows), base component visual specs, dark mode patterns, and the pattern library are defined in `docs/design-system.md`. The UX specification consumes these tokens — it does not redefine them.
 
-### Design Tokens
-
-Design tokens are the atomic values that define the visual language. They are variables, not hard-coded values. Every visual property in the application references a token.
-
-**Color tokens:**
-
-```
---color-primary: #2563EB          // Main brand/action color
---color-primary-hover: #1D4ED8    // Interactive state
---color-primary-light: #DBEAFE    // Backgrounds, subtle highlights
-
---color-secondary: #7C3AED        // Supporting brand color
-
---color-neutral-50: #FAFAFA       // Lightest background
---color-neutral-100: #F5F5F5      // Card backgrounds
---color-neutral-200: #E5E5E5      // Borders
---color-neutral-400: #A3A3A3      // Muted text, placeholders
---color-neutral-700: #404040      // Secondary text
---color-neutral-900: #171717      // Primary text
-
---color-success: #16A34A          // Success states, positive actions
---color-warning: #CA8A04          // Warning states, caution
---color-error: #DC2626            // Error states, destructive actions
---color-info: #2563EB             // Informational states
-```
-
-**Typography tokens:**
-
-```
---font-family: 'Inter', system-ui, sans-serif
-
---text-xs: 0.75rem    // 12px — fine print, labels
---text-sm: 0.875rem   // 14px — secondary text, table cells
---text-base: 1rem     // 16px — body text
---text-lg: 1.125rem   // 18px — subheadings
---text-xl: 1.25rem    // 20px — section titles
---text-2xl: 1.5rem    // 24px — page titles
---text-3xl: 1.875rem  // 30px — hero text
-
---font-weight-normal: 400
---font-weight-medium: 500
---font-weight-semibold: 600
---font-weight-bold: 700
-
---line-height-tight: 1.25
---line-height-normal: 1.5
---line-height-relaxed: 1.75
-```
-
-**Spacing tokens:**
-
-```
---space-1: 0.25rem    // 4px  — tight gaps (icon to label)
---space-2: 0.5rem     // 8px  — compact spacing (list items)
---space-3: 0.75rem    // 12px — default padding (buttons, inputs)
---space-4: 1rem       // 16px — standard spacing (form fields)
---space-6: 1.5rem     // 24px — section padding
---space-8: 2rem       // 32px — large gaps
---space-12: 3rem      // 48px — section separators
---space-16: 4rem      // 64px — page-level spacing
-```
-
-**Border and shadow tokens:**
-
-```
---radius-sm: 0.25rem   // 4px  — subtle rounding (tags, badges)
---radius-md: 0.5rem    // 8px  — standard rounding (cards, inputs, buttons)
---radius-lg: 0.75rem   // 12px — prominent rounding (modals, panels)
---radius-full: 9999px  // Pill shapes, avatars
-
---shadow-sm: 0 1px 2px rgba(0,0,0,0.05)
---shadow-md: 0 4px 6px rgba(0,0,0,0.07)
---shadow-lg: 0 10px 15px rgba(0,0,0,0.1)
---shadow-xl: 0 20px 25px rgba(0,0,0,0.1)
-```
-
-### Dark Mode
-
-When dark mode is required, define a parallel set of semantic tokens that switch based on the color scheme:
-
-```css
-:root {
-  --bg-primary: var(--color-neutral-50);
-  --bg-card: white;
-  --text-primary: var(--color-neutral-900);
-  --text-secondary: var(--color-neutral-700);
-  --border-default: var(--color-neutral-200);
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bg-primary: var(--color-neutral-900);
-    --bg-card: var(--color-neutral-800);
-    --text-primary: var(--color-neutral-50);
-    --text-secondary: var(--color-neutral-400);
-    --border-default: var(--color-neutral-700);
-  }
-}
-```
-
-Use semantic tokens (`--bg-primary`, `--text-primary`) in components, not raw color tokens. This makes dark mode automatic.
-
-### Base Components
-
-Define the standard appearance and behavior for every common component:
-
-**Buttons:**
-- Variants: Primary (solid fill), Secondary (subtle fill), Outline (border only), Ghost (no border), Destructive (red/danger)
-- Sizes: sm (28px height), md (36px height), lg (44px height)
-- States: default, hover, active, focused, disabled, loading
-- Loading state replaces label with spinner, disables interaction
-
-**Form elements:**
-- All inputs: border, focus ring, error state (red border + error message below), disabled state (reduced opacity)
-- Labels: always visible (never placeholder-only), required indicator (asterisk or "(required)")
-- Help text: below input, muted color, explains what the field expects
-- Error messages: below input, error color, describes what went wrong and how to fix it
-
-**Cards:**
-- Default: white/card background, subtle shadow or border, rounded corners
-- Interactive: hover state (shadow increase or border color change), cursor pointer
-- Header/footer sections: visually separated, structured content areas
-
-**Feedback:**
-- Toast notifications: temporary, non-blocking, auto-dismiss (with manual dismiss option)
-- Alert banners: persistent until dismissed, full-width or contained within a section
-- Empty states: illustration or icon, explanatory text, call-to-action button
-- Loading: skeleton loaders (preferred over spinners for content areas), spinner for actions
-
-### Pattern Library
-
-Document recurring UI patterns with implementation guidance:
-
-- **Search with autocomplete:** Debounced input, dropdown results, keyboard navigation, "no results" state
-- **Confirmation dialogs:** Before destructive actions, clearly state what will happen, "Cancel" as primary action (preventing accidents)
-- **Inline editing:** Click to edit, Enter to save, Escape to cancel, loading indicator during save
-- **Bulk actions:** Select all, individual select, action toolbar appears when items selected
-- **Wizard/stepper:** Progress indicator, back/next navigation, save progress between steps
+When specifying component behavior in user flows and interaction states, reference design system tokens by name (e.g., `--color-error`, `--space-4`) rather than hard-coding values. If `docs/design-system.md` does not exist yet, note which tokens are needed and defer visual decisions to the design-system step.
 
 ## Accessibility
 
@@ -367,14 +230,8 @@ Mobile touch targets must be at least 44x44px (Apple) or 48x48px (Material). Ens
 
 **Accessibility as afterthought.** Building the entire UI first, then trying to add accessibility. Results in ARIA hacks layered on top of inaccessible markup. Fix: use semantic HTML from the start. Test keyboard navigation during development, not after.
 
-**Inconsistent spacing and typography.** Five different font sizes that are all "kind of like body text." Spacing that varies randomly between 12px and 17px with no system. Fix: define a spacing scale and type scale in the design system. Only use values from the scale.
-
-**Placeholder text as labels.** Using placeholder text instead of labels for form fields. Placeholders disappear when the user starts typing, leaving them with no indication of what the field expects. Fix: always use visible labels. Placeholders are supplementary hints, not replacements for labels.
-
 **Missing loading states.** The page shows nothing (white screen) while data loads, then content pops in. Users think the app is broken. Fix: use skeleton loaders that match the shape of the content being loaded.
 
-**Ignoring touch targets on mobile.** Tiny links and buttons that require precise finger tapping. Fix: ensure all interactive elements meet minimum 44x44px touch target size on mobile.
-
 **Breaking text on resize.** Content that looks fine at the design width but overflows, truncates, or overlaps at other widths. Fix: test with variable-length content and multiple viewport widths. Use CSS that handles overflow gracefully (truncation with ellipsis, wrapping, or scrolling).
 
 **Modal abuse.** Using modals for content that should be a page (long forms, complex workflows, multi-step processes). Modals are for brief, focused interactions. Fix: if the modal content would benefit from a back button or URL, it should be a page.

package/knowledge/finalization/apply-fixes-and-freeze.md

@@ -30,44 +30,148 @@ Minor polish, documentation gaps that don't affect implementation correctness, a
 
 **Examples**: Missing UX specs for secondary flows, incomplete examples in knowledge base entries, editorial inconsistencies in prose.
 
+### Categorization Methodology
+
+When collecting findings from multiple validation reports, assign each finding to exactly one category using these decision rules:
+
+1. **Would an agent produce incorrect code if this is not fixed?** -> P0
+2. **Would an agent have to guess or make assumptions?** -> P1
+3. **Is the issue real but unlikely to affect implementation correctness?** -> P2
+
+When a finding spans multiple categories (e.g., a stale count that is also ambiguous), assign it to the highest applicable priority. Do not duplicate findings across priority levels.
+
 ## Fix Application Process
 
 ### Step 1: Build the Fix Plan
 
 1. Collect all findings from validation phase outputs (cross-phase-consistency, traceability-matrix, decision-completeness, critical-path-walkthrough, implementability-dry-run, dependency-graph-validation, scope-creep-check).
-2. Deduplicate — the same root cause often appears in multiple validation reports.
+2. Deduplicate — the same root cause often appears in multiple validation reports. When a single root cause appears in 3+ reports, mark it as a **systemic issue** and track it separately.
 3. Group by affected document — batch fixes to minimize file churn.
 4. Order by priority (P0 first), then by document (reduce context switching).
+5. Estimate impact radius for each fix — how many other documents does this fix touch?
+
+#### Fix Plan Output Format
+
+The fix plan is a working document that guides fix execution. Structure it as follows:
+
+```markdown
+## Fix Plan
+
+### Systemic Issues (multi-document root causes)
+| ID | Root Cause | Affected Documents | Priority | Est. Impact |
+|----|------------|-------------------|----------|-------------|
+| SYS-1 | Pipeline expanded from 32→36 steps, counts not propagated | architecture, state-schema, cli-contract, 12 others | P0 | 15 files |
+
+### Individual Fixes
+| ID | Finding Source | Finding | Priority | Target Document | Dependencies |
+|----|--------------|---------|----------|-----------------|--------------|
+| FIX-1 | CPC-007 | Terminology drift: "prompts" vs "steps" | P0 | state-json-schema.md | FIX-2 |
+| FIX-2 | CPC-007 | Terminology drift: "prompts" vs "steps" | P0 | cli-contract.md | — |
+```
 
 ### Step 2: Apply Fixes
 
 For each fix:
 1. Read the finding and the affected document section.
-2. Make the minimal change that resolves the finding.
-3. Check whether the fix affects other documents (e.g., changing a field name in the schema requires updating API contracts and state documentation).
+2. Make the minimal change that resolves the finding. Do not refactor, improve prose, or add features — fix only what the finding identifies.
+3. Check whether the fix affects other documents (e.g., changing a field name in the schema requires updating API contracts and state documentation). Use project-wide search to find all references before changing any term.
 4. Log the fix in `docs/validation/fix-log.md` with: finding ID, affected files, what changed, why.
+5. For systemic issues, fix the source of truth first, then sweep all downstream references in a single pass.
+
+#### Fix Execution Rules
+
+- **One finding per commit** (or one systemic issue per commit). This makes rollback possible if a fix introduces a regression.
+- **Fix forward, not around.** If a finding reveals a design mistake, fix the design — do not patch the symptom.
+- **Preserve document structure.** Fixes should not reorganize sections, add new headings, or change formatting conventions. Content changes only.
+- **Cross-document fixes must be atomic.** If a terminology change spans 5 files, update all 5 in the same commit. A half-applied rename is worse than the original inconsistency.
+
+### Step 3: Re-validation
 
-### Step 3: Verify No Regressions
+After all fixes are applied, re-validate to confirm fixes resolved the findings without introducing new issues:
 
-After all fixes are applied:
-1. Re-run cross-phase consistency checks on modified documents.
-2. Verify traceability links still resolve (no broken references introduced by renames).
-3. Spot-check that counts, terminology, and cross-references are internally consistent.
-4. If a fix introduced a new issue, treat it as a P0 and resolve before proceeding.
+1. **Re-run affected validation checks.** For each fix, identify which validation pass originally flagged it and re-run that specific check against the modified document(s). At minimum, re-run:
+   - Cross-phase consistency checks on all modified documents
+   - Traceability link resolution (no broken references introduced by renames)
+   - Scope-creep check (fixes did not add new requirements)
+2. **Spot-check adjacent sections.** When a fix modifies a section, read the surrounding sections in the same document to verify internal consistency was not broken.
+3. **Verify counts and cross-references.** Any fix that changes a quantity (step count, story count, task count) requires verifying every other document that cites that quantity.
+4. **Regression test systemic fixes.** For systemic issues that touched many files, grep for the old term/value across the entire docs directory to confirm no instances were missed.
+5. **If re-validation finds new issues**, treat them as P0 findings and loop back to Step 2. The fix→revalidate cycle continues until re-validation produces zero new findings.
+
+#### Re-validation Output
+
+Record re-validation results alongside the fix log:
+
+```markdown
+## Re-validation Results
+
+| Fix ID | Re-validation Check | Result | Notes |
+|--------|-------------------|--------|-------|
+| FIX-1 | CPC re-run | PASS | All "step" references consistent |
+| FIX-3 | Traceability links | FAIL | New broken ref in tasks.md line 47 |
+```
 
 ## Documentation Freeze
 
-Once all P0 and P1 findings are resolved:
+Once all P0 and P1 findings are resolved and re-validation produces zero new findings:
 
 1. Add a freeze marker (tracking comment) to each phase artifact indicating the document is implementation-ready.
 2. Record the freeze timestamp and the validation findings that were addressed.
 3. P2 deferrals are logged in the fix log with rationale — these become backlog items for post-implementation polish.
 
+### Freeze Criteria Checklist
+
+Before declaring freeze, verify all of the following:
+
+- [ ] All P0 findings resolved and re-validated
+- [ ] All P1 findings resolved (or explicitly risk-accepted with documented rationale)
+- [ ] Re-validation produced zero new findings on the final pass
+- [ ] Fix log is complete with all changes documented
+- [ ] P2 deferrals are logged with rationale
+- [ ] Cross-document counts are internally consistent (final count sweep)
+- [ ] All traceability links resolve (no dangling references)
+- [ ] Terminology is consistent across all documents (final terminology sweep)
+
 ### What Freeze Means
 
 - **No further content changes** unless implementation reveals a genuine gap (not a preference).
 - **Formatting and typo fixes** are allowed — they don't affect implementation.
 - **If a gap is found during implementation**, the fix goes through the same prioritization process: update the document, log the change, re-verify consistency.
+- **Freeze does NOT mean the documents are perfect.** P2 deferrals exist. The standard is implementation readiness — an implementing agent can produce correct code from these documents without guessing.
+
+### What Is Allowed After Freeze
+
+| Change Type | Allowed? | Process |
+|------------|----------|---------|
+| Typo fixes, formatting | Yes | Direct edit, no re-validation needed |
+| Gap discovered during implementation | Yes | Prioritize as P0/P1, apply fix, re-validate affected section, log in fix log |
+| "Nice to have" improvements | No | Log as P2 deferral for post-implementation |
+| Scope additions | No | Out of scope — must go through PRD amendment process |
+| Terminology alignment (missed in freeze) | Yes | Treat as P0 fix, apply and re-validate |
+
+### Freeze Marker Format
+
+Add the following marker to the top of each frozen document, immediately after the frontmatter:
+
+```markdown
+<!-- FROZEN: Implementation-ready as of YYYY-MM-DD. Changes require fix-log entry. -->
+```
+
+### Frozen Artifact Set
+
+The complete set of frozen artifacts should be documented in the fix log as a manifest:
+
+```markdown
+## Frozen Artifact Manifest
+
+| Document | Freeze Date | P0 Fixes | P1 Fixes | P2 Deferred |
+|----------|------------|----------|----------|-------------|
+| docs/plan.md | 2025-01-15 | 0 | 2 | 1 |
+| docs/system-architecture.md | 2025-01-15 | 3 | 4 | 2 |
+| docs/api-contracts.md | 2025-01-15 | 1 | 1 | 0 |
+| docs/database-schema.md | 2025-01-15 | 2 | 3 | 1 |
+| ... | ... | ... | ... | ... |
+```
 
 ## Fix Log Format
 
@@ -85,9 +189,56 @@ Once all P0 and P1 findings are resolved:
 | 1 | IR-012: Missing adopt-flow UX spec | Low implementation impact; adopt is secondary flow |
 ```
 
+## The Fix-Revalidate-Freeze Cycle
+
+The full process follows a strict cycle:
+
+```
+Collect findings
+    │
+    ▼
+Build fix plan (categorize, prioritize, estimate impact)
+    │
+    ▼
+┌─> Apply fixes (one finding or systemic issue per commit)
+│       │
+│       ▼
+│   Re-validate (re-run affected checks, spot-check adjacent sections)
+│       │
+│       ▼
+│   New findings? ──Yes──┐
+│       │                │
+│       No               │
+│       │                │
+│       ▼                │
+│   Freeze criteria met? │
+│       │                │
+│       No               │
+│       │                │
+└───────┘ ◄──────────────┘
+        │
+        Yes
+        │
+        ▼
+   Declare freeze (add markers, create manifest, log deferrals)
+```
+
+Each iteration through the cycle should produce strictly fewer findings than the previous iteration. If the count of findings is not decreasing, stop and investigate — you may be fixing symptoms while the root cause persists.
+
 ## Common Pitfalls
 
-1. **Fixing symptoms instead of root causes.** If the same stale count appears in 15 files, the root cause is a single pipeline change that wasn't propagated. Fix the source and sweep all references.
-2. **Introducing new inconsistencies.** Renaming a field in one document but missing it in another. Always search for all references before changing a term.
-3. **Over-fixing.** The goal is implementation readiness, not perfection. If a P2 finding doesn't affect an implementing agent's ability to produce correct code, defer it.
-4. **Skipping verification.** A fix that breaks a cross-reference is worse than the original finding. Always re-verify after applying fixes.
+1. **Fixing symptoms instead of root causes.** If the same stale count appears in 15 files, the root cause is a single pipeline change that wasn't propagated. Fix the source and sweep all references. A good diagnostic: if your fix plan has 10+ individual fixes that all trace to the same upstream change, consolidate them into one systemic fix.
+
+2. **Introducing new inconsistencies.** Renaming a field in one document but missing it in another. Always search for all references before changing a term. Run a project-wide grep for the old term after every rename.
+
+3. **Over-fixing.** The goal is implementation readiness, not perfection. If a P2 finding doesn't affect an implementing agent's ability to produce correct code, defer it. A common trap: improving prose clarity during the fix phase. This is not fixing — it is editing, and it risks introducing new inconsistencies.
+
+4. **Skipping re-validation.** A fix that breaks a cross-reference is worse than the original finding. Always re-validate after applying fixes. The most dangerous fixes are the ones that "obviously" don't need re-validation — those are the ones that introduce silent regressions.
+
+5. **Premature freeze.** Declaring freeze before all P0 and P1 findings are resolved because of time pressure. A premature freeze sends agents into implementation with known issues, guaranteeing rework. If time is short, reduce scope (defer entire features) rather than freezing with known P0 issues.
+
+6. **Scope creep during the fix phase.** A finding says "the error format is unspecified" and the fix adds a complete error taxonomy, error codes, error localization strategy, and retry semantics. The fix should specify the minimum error format needed for implementation. Everything else is new scope.
+
+7. **Infinite fix loops.** Each fix introduces a new finding, which requires another fix, which introduces another finding. This happens when fixes are too broad (changing things beyond what the finding requires) or when the underlying documents have systemic structural problems. Break the loop by: (a) making smaller, more targeted fixes, or (b) stepping back to identify the structural issue and fixing that instead.
+
+8. **Incomplete fix log.** Applying fixes without logging them. The fix log is not bureaucracy — it is the audit trail that proves the freeze is valid. If an implementation agent later questions a design choice, the fix log explains why the document says what it says.

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/review/review-adr.md

@@ -201,3 +201,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
+```