@zigrivers/scaffold 2.1.0

package/knowledge/validation/implementability-review.md

@@ -0,0 +1,252 @@
+---
+name: implementability-review
+description: Dry-running specs as an implementing agent to catch ambiguity and missing detail
+topics: [validation, implementability, ambiguity, agent-readiness, dry-run]
+---
+
+# Implementability Review
+
+An implementability review reads every specification as if you were an AI agent about to implement it. For each task, the question is: "Do I have everything I need to start coding right now?" Every question you would need to ask is a gap. Every ambiguity you would need to resolve is a defect. This is the most practical validation — it tests whether the specs actually work for their intended consumer.
+
+## The Implementing Agent Perspective
+
+AI agents implementing tasks have specific constraints that make implementability review different from a human code review:
+
+1. **No institutional memory.** The agent knows only what the specifications say. If a convention is "obvious" to the team but not documented, the agent will not follow it.
+2. **No ability to ask clarifying questions in real-time.** The agent will either guess or stop. Both are bad.
+3. **Literal interpretation.** If the spec says "handle errors appropriately," the agent has no shared understanding of what "appropriately" means for this project.
+4. **Context window limits.** The agent may not have all specifications loaded simultaneously. Each task needs enough context to be self-contained or must explicitly reference what to read.
+5. **No ability to "look at what others did."** Unless the codebase already has examples, the agent cannot infer patterns from existing code.
+
+## What to Check
+
+### 1. Task-Level Completeness
+
+For each implementation task, verify:
+
+**Inputs are specified:**
+- What files or modules does this task modify or create?
+- What existing code does it depend on?
+- What specifications should the implementer read?
+
+**Expected output is clear:**
+- What is the concrete deliverable? (files created, functions implemented, tests passing)
+- How will success be measured?
+
+**Scope is bounded:**
+- Is it clear where this task starts and stops?
+- Are there ambiguous boundaries with adjacent tasks?
+
+**Dependencies are explicit:**
+- What tasks must be completed before this one can start?
+- What will this task produce that other tasks need?
+
+### 2. Ambiguity Detection
+
+Ambiguity is any specification statement that a reasonable implementer could interpret in more than one way.
+
+**Common ambiguity patterns:**
+
+**Vague adjectives and adverbs:**
+- "The system should be fast" — How fast? Specify latency targets.
+- "Properly validate input" — What validation rules? Which inputs?
+- "Handle errors gracefully" — What does graceful mean? Show error message? Retry? Log and continue?
+- "Securely store passwords" — Which algorithm? What salt length? What cost factor?
+
+**Missing specifics:**
+- "Paginate the results" — Page size? Cursor-based or offset-based? Default sort order?
+- "Send a notification" — Via what channel? Email? Push? In-app? What is the message content?
+- "Log the event" — What log level? What fields? What format? Where does it go?
+
+**Implicit behavior:**
+- "When the user is not authenticated, redirect to login" — What about API calls? Return 401 or redirect?
+- "Support multiple languages" — Which languages? How are translations managed? What is the fallback?
+- "Cache the results" — For how long? What invalidates the cache? What cache store?
+
+**Detection technique:** For each specification statement, ask:
+1. Could two different developers implement this differently and both believe they followed the spec?
+2. If yes, the statement is ambiguous.
+
+### 3. Error Case Coverage
+
+Error handling is where implementability most often breaks down. For each operation:
+
+**Input validation errors:**
+- What happens when required fields are missing?
+- What happens when field values are out of range?
+- What happens when field types are wrong (string instead of number)?
+- What are the specific validation rules and error messages?
+
+**Business logic errors:**
+- What happens when a domain invariant would be violated?
+- What happens when a referenced entity does not exist?
+- What happens when the operation is not allowed in the current state?
+
+**Infrastructure errors:**
+- What happens when the database is unavailable?
+- What happens when an external service times out?
+- What happens when the disk is full?
+
+**Concurrency errors:**
+- What happens when two users modify the same entity simultaneously?
+- What happens when a task is claimed by two agents at the same time?
+- Is optimistic or pessimistic locking specified?
+
+**For each error scenario, the spec should define:**
+- The error response format (status code, error body structure)
+- Whether the operation should be retried
+- What the user sees (if user-facing)
+- Whether the error should be logged and at what level
+- Whether an alert should be triggered
+
+### 4. Data Shape Precision
+
+For every data structure that crosses a boundary (API request/response, database row, event payload, component props):
+
+**Type precision:**
+- Are types specified? (`string` is not enough — is it an email? A UUID? Free text with a max length?)
+- Are optional fields marked? (What is the default when omitted?)
+- Are nullable fields distinguished from optional fields?
+- Are enum values listed exhaustively?
+
+**Relationship precision:**
+- Are foreign key relationships clear? (Does the task know which table to join?)
+- Are nested objects or arrays specified? (What is the shape of items in the array?)
+- Are circular references addressed? (How deep does serialization go?)
+
+**Format precision:**
+- Date format (ISO 8601? Unix timestamp? Local timezone?)
+- Money format (cents as integer? Decimal string? Object with amount and currency?)
+- ID format (auto-increment integer? UUID v4? ULID? CUID?)
+
+### 5. Pattern and Convention Specification
+
+For each task, the implementer needs to know what patterns to follow:
+
+**Code organization:**
+- Where do new files go? (Directory structure, naming conventions)
+- What is the module/component pattern? (One class per file? Barrel exports? Index files?)
+
+**Error handling pattern:**
+- Do errors propagate as exceptions or as return values?
+- Is there a custom error class hierarchy?
+- Where is error mapping done (at the boundary or in the domain)?
+
+**Testing pattern:**
+- What test file naming convention? (`*.test.ts`, `*.spec.ts`, `__tests__/`)
+- What test structure? (describe/it? test()? Separate unit and integration directories?)
+- What mocking approach? (Jest mocks? Dependency injection? Test doubles?)
+
+**Logging pattern:**
+- What logger? (console, winston, pino, structured JSON?)
+- What log levels for what events?
+- What contextual fields to include?
+
+If these patterns are not in the specification, each agent will invent their own, producing an inconsistent codebase.
+
+## How to Perform the Review
+
+### Role-Play Method
+
+For each task in the implementation tasks document:
+
+1. **Read only what the task says to read.** Do not bring in knowledge from other tasks or general experience. The agent will only have what it is told to read.
+2. **Attempt to write pseudocode.** Try to outline the implementation based solely on the specification.
+3. **Record every point where you would need to ask a question.** Each question is a gap.
+4. **Record every point where you would need to make an assumption.** Each assumption should either be confirmed in the spec or documented as a finding.
+5. **Record every point where you would need to look at existing code for reference.** If the existing code does not yet exist (greenfield), this is a gap.
+
+### Checklist Per Task
+
+```
+Task: [Task ID and title]
+
+Information Check:
+- [ ] What to build is clear (not just what area to work in)
+- [ ] Where to put the code is specified (directory, file naming)
+- [ ] What patterns to follow are referenced or documented
+- [ ] Dependencies on other tasks are listed
+- [ ] What "done" looks like is defined (test criteria, acceptance criteria)
+
+Ambiguity Check:
+- [ ] No vague adjectives (fast, secure, robust, scalable, appropriate)
+- [ ] No missing specifics (pagination details, error formats, cache TTL)
+- [ ] No implicit behavior (authentication, authorization, logging)
+
+Error Case Check:
+- [ ] Input validation errors defined
+- [ ] Business logic errors defined
+- [ ] Infrastructure failure behavior defined
+- [ ] Concurrency behavior defined
+
+Data Shape Check:
+- [ ] All data structures have explicit types
+- [ ] Optional and nullable fields distinguished
+- [ ] Enum values listed
+- [ ] Formats specified (dates, money, IDs)
+```
+
+## Output Format
+
+### Per-Task Findings
+
+```markdown
+## Task T-015: Implement Order Creation Endpoint
+
+**Implementability Score:** 3/5 (Partially implementable — key gaps exist)
+
+### Gaps Found
+
+1. **AMBIGUITY** — Error response format not specified
+   - Spec says "return appropriate error" but does not define the error response body structure.
+   - Impact: Agent will invent an error format that may be inconsistent with other endpoints.
+   - Fix: Add error response schema to API contracts.
+
+2. **MISSING** — Inventory check behavior undefined
+   - Spec says "validate inventory" but does not define what happens when inventory is insufficient.
+   - Questions: Partial order allowed? Wait-list? Immediate rejection?
+   - Fix: Add inventory insufficiency handling to the order creation flow in API contracts.
+
+3. **VAGUE** — "Log the order creation event"
+   - What logger? What log level? What fields? What format?
+   - Fix: Reference logging conventions in the implementation playbook.
+```
+
+### Summary Table
+
+```markdown
+| Task | Score | Gaps | Critical | Assessment |
+|------|-------|------|----------|------------|
+| T-012 | 5/5 | 0 | 0 | Ready to implement |
+| T-013 | 4/5 | 2 | 0 | Minor clarifications needed |
+| T-015 | 3/5 | 4 | 1 | Error handling gaps |
+| T-020 | 2/5 | 6 | 3 | Significant rework needed |
+```
+
+### Scoring Guide
+
+- **5/5** — Task is fully implementable. No questions, no assumptions needed.
+- **4/5** — Task is mostly implementable. Minor clarifications needed but an agent could make reasonable assumptions.
+- **3/5** — Task is partially implementable. Some gaps that could lead to incorrect implementation.
+- **2/5** — Task has significant gaps. Agent would need to guess about core behavior.
+- **1/5** — Task is not implementable. Fundamental information is missing.
+
+Target: All tasks should score 4/5 or higher before implementation begins.
+
+## Common Findings by Category
+
+### Most Frequently Missing
+
+1. Error response formats (almost always under-specified)
+2. Logging conventions (almost never specified)
+3. Input validation rules (specified for happy path, missing for edge cases)
+4. Concurrency handling (rarely addressed in specs)
+5. Empty state behavior (what happens when there is no data)
+
+### Most Impactful When Missing
+
+1. Authentication/authorization boundaries (who can call what)
+2. Data migration and seeding (how does initial data get in)
+3. Environment configuration (what env vars, what defaults)
+4. External service integration details (API keys, rate limits, retry policies)
+5. State machine transitions (valid state changes and their guards)

package/knowledge/validation/scope-management.md

@@ -0,0 +1,223 @@
+---
+name: scope-management
+description: Detecting scope creep and ensuring specs stay aligned to PRD boundaries
+topics: [validation, scope, creep, prd-alignment, gold-plating]
+---
+
+# Scope Management
+
+Scope management validation compares every specification artifact against the PRD to ensure that the documented system matches what was actually requested. Features that cannot be traced to a PRD requirement are scope creep. Requirements that grew during documentation are scope inflation. Extra polish on non-critical features is gold-plating. This validation catches all three.
+
+## Why Scope Grows
+
+Scope grows during the documentation pipeline for understandable reasons — but each growth increases implementation effort, risk, and timeline. Common causes:
+
+1. **Engineering enthusiasm** — Domain modeling reveals interesting patterns, and the team designs for future needs that are not in the PRD.
+2. **Defensive architecture** — "We should add this abstraction now because it will be hard to add later." Maybe, but if it is not in the PRD, it is scope creep.
+3. **Completeness bias** — "Every API should have full CRUD" even when the PRD only calls for Create and Read.
+4. **Platform assumptions** — "All modern apps need real-time notifications" even when the PRD does not mention them.
+5. **Review-driven growth** — During review phases, reviewers identify gaps that are real but beyond the PRD scope. These gaps are valid observations but should be deferred, not added.
+6. **Implicit requirements** — "Obviously we need admin tooling" or "of course there is a settings page" — unless the PRD says so, these are not requirements.
+
+## What to Check
+
+### 1. Feature-to-PRD Tracing
+
+For every feature, endpoint, screen, or capability in the specifications, verify it traces to a specific PRD requirement.
+
+**Process:**
+1. Build a list of every concrete capability in the specifications:
+   - Every API endpoint
+   - Every database table
+   - Every UI screen or component
+   - Every background job or scheduled task
+   - Every integration with an external service
+2. For each capability, find the PRD requirement that justifies it.
+3. Classify each capability:
+   - **Traced** — Maps directly to a PRD requirement.
+   - **Supporting** — Does not map to a PRD requirement directly but is necessary infrastructure for a traced capability (e.g., database connection pooling supports all data features).
+   - **Creep** — Cannot be traced to any PRD requirement and is not necessary infrastructure.
+
+**What findings look like:**
+- "API endpoint `GET /analytics/reports` has no corresponding PRD requirement. The PRD mentions displaying basic stats on the dashboard but does not mention a reports feature."
+- "The `AuditLog` table is not traceable to any PRD requirement. While audit logging is good practice, it is not a v1 requirement."
+- "The UX spec includes an 'Admin Dashboard' with user management, role assignment, and system monitoring. The PRD mentions only a basic admin interface for content moderation."
+
+### 2. Requirement Scope Inflation
+
+A requirement starts small in the PRD and grows during documentation. The PRD says "users can search products" — by the time it reaches the API contracts, there is full-text search with faceted filtering, auto-suggest, and search analytics.
+
+**Process:**
+1. For each PRD requirement, compare its original scope (as stated in the PRD) with its implementation scope (as described in later artifacts).
+2. Look for:
+   - Features that are more detailed than the requirement called for.
+   - Additional sub-features not mentioned in the requirement.
+   - Higher quality targets than the requirement specified.
+   - More platforms or device types than the requirement addressed.
+
+**Detection heuristics:**
+- Count the API endpoints per PRD feature. A single feature with 10+ endpoints may indicate inflation.
+- Count the database tables per domain entity. An entity with 5+ tables may indicate over-engineering.
+- Compare the PRD's feature description word count to the architecture's implementation description. If the implementation is 10x longer, scope may have inflated.
+- Check for features that only appear after the architecture step that were not in the domain modeling step or the PRD.
+
+**What findings look like:**
+- "PRD says 'users can update their profile.' Architecture specifies profile versioning with history, diff view, and rollback capability. This exceeds the PRD requirement."
+- "PRD says 'send email notifications for important events.' Implementation tasks include: email templates engine, unsubscribe management, bounce handling, email analytics, and A/B testing. Only the first two are justified by the PRD."
+
+### 3. Gold-Plating Detection
+
+Gold-plating is adding extra polish, features, or capabilities beyond what is needed. Unlike scope creep (adding new features), gold-plating over-engineers existing features.
+
+**Indicators of gold-plating:**
+- **Over-abstraction** — Generic plugin systems when only one plugin type exists. Configurable everything when the configuration will never change. Abstract factory patterns when there is only one concrete class.
+- **Premature optimization** — Caching layers for data that is accessed once per session. Database sharding for an application that will have 100 users. CDN configuration for an internal tool.
+- **Excessive error handling** — Circuit breakers and retry policies for services that have 99.99% uptime. Graceful degradation for features that can simply show an error.
+- **Over-documentation** — API endpoints with 50+ response examples. Database schemas with migration scripts for every possible future change.
+- **UI polish beyond requirements** — Animations, micro-interactions, and visual effects for an internal business tool. Dark mode when the PRD does not mention it.
+
+**Detection technique:**
+For each specification element, ask: "If I removed this, would any PRD requirement be unmet?" If the answer is no, it is gold-plating.
+
+### 4. Deferred Scope Leaking In
+
+The PRD explicitly defers certain features ("out of scope for v1," "future enhancement"). Verify none of these deferred items appear in the specifications.
+
+**Process:**
+1. Extract all explicitly deferred items from the PRD.
+2. Search all specification artifacts for any reference to deferred items.
+3. Check for partial implementations — infrastructure for a deferred feature that is "already done" but not needed yet.
+
+**What findings look like:**
+- "PRD defers multi-language support to v2, but the database schema has a `locale` column on every content table and the API contracts accept `Accept-Language` headers."
+- "PRD defers mobile app to v2, but the architecture includes a 'Mobile API Gateway' component and the API contracts include mobile-specific endpoints."
+
+### 5. NFR Scope Alignment
+
+Non-functional requirements are especially prone to scope creep because they can always be "better."
+
+**Process:**
+1. For each NFR in the PRD, check whether the implementation scope matches the specified target:
+   - If PRD says "p95 under 500ms," does the architecture target 100ms?
+   - If PRD says "WCAG AA," does the UX spec target WCAG AAA?
+   - If PRD says "99.9% uptime," does the operations runbook design for 99.99%?
+2. Over-specifying NFRs is gold-plating. The implementation effort difference between 99.9% and 99.99% uptime is enormous.
+
+## How to Structure the Audit
+
+### Pass 1: PRD Boundary Extraction
+
+Build a definitive list of what is in scope and what is out:
+
+```markdown
+## In Scope (from PRD)
+1. User registration and authentication
+2. Product catalog with search
+3. Shopping cart
+4. Checkout with Stripe payment
+5. Order history
+6. Basic admin: content moderation
+
+## Explicitly Out of Scope (from PRD)
+1. Multi-language support (v2)
+2. Mobile native app (v2)
+3. Marketplace (third-party sellers) (v2)
+4. Social features (reviews, ratings) (v2)
+5. Advanced analytics and reporting (v2)
+
+## NFR Targets (from PRD)
+- Performance: p95 < 500ms for page loads
+- Availability: 99.9% uptime
+- Security: OWASP Top 10 compliance
+- Accessibility: WCAG AA
+- Scale: Support 10,000 concurrent users
+```
+
+### Pass 2: Artifact Scanning
+
+For each specification artifact, list every capability and trace it:
+
+```markdown
+| Capability | Artifact | PRD Requirement | Classification |
+|------------|----------|-----------------|----------------|
+| POST /auth/register | API contracts | User registration | Traced |
+| POST /auth/login | API contracts | User authentication | Traced |
+| GET /auth/sessions | API contracts | — | Creep (session management not in PRD) |
+| users table | Schema | User registration | Traced |
+| user_sessions table | Schema | — | Creep (paired with sessions endpoint) |
+| SearchService with Elasticsearch | Architecture | Product search | Inflation (PRD says search, not full-text search engine) |
+| Notification Service | Architecture | — | Creep |
+| Admin Analytics Dashboard | UX spec | — | Creep (PRD says basic moderation only) |
+```
+
+### Pass 3: Impact Assessment
+
+For each scope finding, assess the impact of keeping vs removing it:
+
+```markdown
+## Finding: Notification Service
+
+**Classification:** Scope creep
+**Effort to implement:** ~3 tasks, ~2 days
+**Impact of keeping:** Adds complexity to architecture, requires email service integration, adds operational burden
+**Impact of removing:** Users would not receive email notifications for order updates — but the PRD does not require this
+**Recommendation:** Defer to v2. Remove from architecture and implementation tasks.
+```
+
+## Output Format
+
+### Scope Audit Summary
+
+```markdown
+## Scope Audit Results
+
+**Total capabilities identified:** 85
+**Traced to PRD:** 62 (73%)
+**Supporting infrastructure:** 15 (18%)
+**Scope creep:** 5 (6%)
+**Gold-plating:** 3 (4%)
+
+### Scope Creep Items
+1. Notification Service — recommend defer
+2. Admin Analytics Dashboard — recommend defer
+3. User session management API — recommend simplify
+4. Export to PDF — recommend remove (explicitly deferred in PRD)
+5. Multi-language database support — recommend remove (explicitly deferred in PRD)
+
+### Gold-Plating Items
+1. Full-text search with Elasticsearch — PRD says "search," recommend PostgreSQL full-text search
+2. WCAG AAA compliance — PRD says AA, recommend AA
+3. 99.99% uptime architecture — PRD says 99.9%, recommend simplifying HA setup
+
+### Scope Inflation Items
+1. User profile: versioning and rollback added beyond PRD requirement
+2. Email notifications: template engine, unsubscribe management, analytics added
+3. Search: faceted filtering, auto-suggest, search analytics added
+
+### Estimated Effort Savings if Scope is Tightened
+- Removing creep: ~8 tasks, ~5 days estimated
+- Fixing gold-plating: ~4 tasks, ~3 days estimated
+- Reducing inflation: ~6 tasks, ~4 days estimated
+- **Total: ~18 tasks, ~12 days estimated savings**
+```
+
+## Decision Framework
+
+Not all scope additions are bad. Some are genuinely necessary even if not in the PRD. Use this framework:
+
+| Question | If Yes | If No |
+|----------|--------|-------|
+| Is it required for a PRD feature to work? | Keep (supporting infrastructure) | Continue evaluation |
+| Does the PRD explicitly defer it? | Remove | Continue evaluation |
+| Would a user notice its absence? | Consider keeping, but flag for PRD update | Remove |
+| Does it significantly increase implementation effort? | Remove unless critical | May keep if low effort |
+| Does it add operational complexity? | Remove unless critical | May keep if simple |
+
+When in doubt, defer. It is always easier to add a feature later than to remove one that has been built.
+
+## When to Run Scope Validation
+
+- After all documentation phases are complete, before the implementation tasks step.
+- After the implementation tasks step, before implementation begins.
+- When the task list feels "too big" — scope validation often reveals why.
+- When stakeholders ask "why is this taking so long?" — scope validation quantifies the answer.

package/knowledge/validation/traceability.md

@@ -0,0 +1,198 @@
+---
+name: traceability
+description: Building traceability matrices from requirements through architecture to implementation tasks
+topics: [validation, traceability, requirements, coverage]
+---
+
+# Traceability
+
+Traceability validation ensures that every requirement flows from its origin in the PRD through domain modeling, architecture decisions, system design, and into implementable tasks. A complete traceability matrix is the strongest evidence that nothing has been lost or invented during the documentation pipeline.
+
+## What a Traceability Matrix Is
+
+A traceability matrix is a table where each row represents a requirement and each column represents a pipeline artifact. A complete row means the requirement is fully traced from origin to implementation. A missing cell means a gap — either the requirement was not addressed at that phase, or it was addressed but the connection is not explicit.
+
+### The Columns
+
+| Column | Source Artifact | What to Extract |
+|--------|----------------|-----------------|
+| **Requirement** | PRD | Feature descriptions, user needs, NFRs, constraints |
+| **Domain Concept** | Domain Model | Which entities, aggregates, events, or invariants relate to this requirement |
+| **Decision** | ADRs | Which architectural decisions were made to support this requirement |
+| **Architecture** | System Architecture | Which components, modules, or services implement this requirement |
+| **Data** | Database Schema | Which tables, columns, or indexes support this requirement |
+| **API** | API Contracts | Which endpoints or operations expose this requirement |
+| **UX** | UX Specification | Which screens, flows, or components deliver this requirement to users |
+| **Task** | Implementation Tasks | Which tasks implement this requirement |
+| **Test** | Testing Strategy | Which test cases verify this requirement |
+
+Not every requirement needs every column. A backend NFR like "p95 latency under 200ms" will not have a UX column. A database requirement will not have a UX column. The matrix should indicate "N/A" for legitimately inapplicable cells versus blank for gaps.
+
+## How to Build the Matrix
+
+### Step 1: Extract Requirements from PRD
+
+Read the PRD and extract every discrete requirement. Include:
+
+- **Functional requirements** — Features, user stories, acceptance criteria.
+- **Non-functional requirements** — Performance, security, scalability, accessibility, availability.
+- **Constraints** — Technology mandates, timeline, budget, regulatory.
+- **Deferred items** — Requirements explicitly marked as out of scope or deferred. Track these too — they should NOT appear in downstream artifacts.
+
+Give each requirement a unique identifier (e.g., `REQ-001`). If the PRD does not number them, assign them during extraction.
+
+### Step 2: Trace Each Requirement Forward
+
+For each requirement, search downstream artifacts for references:
+
+1. **Domain Model:** Which domain concepts address this requirement? Look for entities that model the data, events that represent state changes, invariants that enforce rules.
+
+2. **ADRs:** Which decisions were driven by this requirement? Technology choices, pattern selections, trade-off resolutions.
+
+3. **Architecture:** Which component or module is responsible? Where does this requirement live in the system structure?
+
+4. **Database Schema:** Which tables store the data? Which indexes support the queries? Which constraints enforce the rules?
+
+5. **API Contracts:** Which endpoints expose the functionality? Which request/response shapes carry the data?
+
+6. **UX Spec:** Which screens display the information? Which user flows exercise the feature? Which form inputs capture the data?
+
+7. **Tasks:** Which implementation tasks build this feature? Are all layers covered (backend, frontend, infrastructure)?
+
+8. **Tests:** Which test cases verify the requirement works correctly? Are edge cases covered?
+
+### Step 3: Identify Gaps
+
+After building the matrix, scan for:
+
+- **Empty cells (not N/A)** — A requirement that reaches architecture but has no tasks is a gap. A requirement with tasks but no tests is a gap.
+- **Orphaned artifacts** — Artifacts that trace to no requirement. These may indicate scope creep (see scope-management knowledge base) or missing PRD entries.
+- **Thin traces** — A requirement that has only one task and one test for a complex feature. The trace exists but is insufficient.
+- **Deferred items appearing downstream** — Requirements marked as deferred in the PRD but implemented in architecture or tasks.
+
+### Step 4: Handle Missing Cells
+
+For each gap, determine the appropriate action:
+
+| Gap Type | Likely Action |
+|----------|---------------|
+| Requirement has no domain concept | Add to domain model or confirm it is a cross-cutting concern |
+| Requirement has no ADR | Verify no decision was needed, or create an ADR |
+| Requirement has no architecture component | Add component or map to existing component |
+| Requirement has no schema support | Add schema elements (if requirement involves data persistence) |
+| Requirement has no API endpoint | Add endpoint (if requirement involves external interface) |
+| Requirement has no UX | Add UX elements (if requirement is user-facing) |
+| Requirement has no tasks | Create tasks to implement it |
+| Requirement has no tests | Add test cases |
+| Artifact has no requirement | Flag as potential scope creep or identify missing PRD requirement |
+
+## Matrix Format
+
+### Compact Format (for overview)
+
+```markdown
+| Req ID | Requirement | Domain | ADR | Arch | DB | API | UX | Task | Test |
+|--------|-------------|--------|-----|------|----|-----|----|------|------|
+| REQ-001 | User registration | User entity | ADR-003 | AuthService | users | POST /auth/register | SignUp flow | T-012 | TS-001 |
+| REQ-002 | Password reset | User.resetToken | ADR-003 | AuthService | users.reset_token | POST /auth/reset | Reset flow | T-015 | TS-002 |
+| REQ-003 | p95 < 200ms | — | ADR-008 | CDN + caching | indexes | — | — | T-050 | TS-040 |
+| REQ-004 | (deferred) Export PDF | — | — | — | — | — | — | — | — |
+```
+
+### Detailed Format (for gap investigation)
+
+```markdown
+## REQ-001: User Registration
+
+**PRD Source:** Section 3.1, "Users must be able to create accounts with email and password"
+
+**Domain Model Trace:**
+- Entity: `User` (email, passwordHash, createdAt)
+- Invariant: email must be unique
+- Event: `UserRegistered`
+
+**ADR Trace:**
+- ADR-003: Use bcrypt for password hashing (cost factor 12)
+
+**Architecture Trace:**
+- Component: `AuthService` handles registration
+- Data Flow: Client → API Gateway → AuthService → UserRepository → Database
+
+**Schema Trace:**
+- Table: `users` (id, email, password_hash, created_at)
+- Index: `idx_users_email` UNIQUE
+- Constraint: NOT NULL on email, password_hash
+
+**API Trace:**
+- POST /auth/register — request: {email, password}, response: {user, token}
+- Error: 409 Conflict if email exists
+
+**UX Trace:**
+- Screen: SignUp (email input, password input, confirm password, submit)
+- Flow: SignUp → Email Verification → Dashboard
+- Validation: client-side email format, password strength
+
+**Task Trace:**
+- T-012: Implement user registration endpoint
+- T-013: Build sign-up form component
+- T-014: Add email verification flow
+
+**Test Trace:**
+- TS-001: Unit test — registration with valid data
+- TS-002: Unit test — duplicate email rejection
+- TS-003: Integration test — full registration flow
+- TS-004: E2E test — sign up from UI
+```
+
+## Traceability for Non-Functional Requirements
+
+NFRs require special tracing because they often cut across multiple components rather than mapping cleanly to a single feature.
+
+### Performance Requirements
+
+Trace through: ADR (caching strategy, database choice) → Architecture (caching layers, CDN, connection pooling) → Schema (indexes, query optimization) → API (pagination, rate limiting) → Testing (load tests, benchmarks).
+
+### Security Requirements
+
+Trace through: ADR (auth strategy, encryption) → Architecture (security boundaries, auth service) → Schema (encrypted columns, audit tables) → API (auth headers, CORS, rate limits) → Testing (penetration tests, auth tests) → UX (CSRF tokens, secure forms).
+
+### Accessibility Requirements
+
+Trace through: ADR (WCAG level target) → UX (ARIA labels, keyboard navigation, screen reader support, color contrast) → Testing (accessibility audits, screen reader tests).
+
+## Common Issues Found During Traceability
+
+1. **The "orphan feature" pattern** — Tasks exist for features that are not in the PRD. Often introduced during architecture when engineers think of improvements. Must be either added to PRD (with stakeholder approval) or removed from tasks.
+
+2. **The "assumed infrastructure" pattern** — Architecture assumes infrastructure (Redis, message queue, CDN) that has no ADR, no tasks, and no operational runbook entry. The requirement is implicit.
+
+3. **The "tested but not specified" pattern** — Test cases exist for behaviors that are not documented in any specification. Often indicates tacit knowledge that should be made explicit.
+
+4. **The "specified but not tested" pattern** — Requirements with full implementation traces but no test coverage. Especially common for error cases and NFRs.
+
+5. **The "split requirement" pattern** — A single PRD requirement maps to tasks across multiple phases that are not linked to each other. If one task is cut, the feature is half-built.
+
+## Bidirectional Tracing
+
+The matrix should be walkable in both directions:
+
+- **Forward (requirement → implementation):** Start from a PRD requirement, verify it has complete downstream coverage.
+- **Backward (implementation → requirement):** Start from a task or test, verify it traces back to a PRD requirement.
+
+Backward tracing catches scope creep — artifacts that exist without a requirement justification. Forward tracing catches gaps — requirements without implementation.
+
+## Tooling Considerations
+
+For the pipeline context, the traceability matrix is a markdown document. Key practices:
+
+- Use consistent identifiers (REQ-001, ADR-003, T-012) so traces are searchable.
+- Cross-reference identifiers rather than duplicating content.
+- Update the matrix when any artifact changes — it is a living document until docs are frozen.
+- During validation, the matrix is the primary output. During finalization, it should be complete.
+
+## When to Use Traceability Validation
+
+- After all pipeline phases are complete, before finalization.
+- When a significant change is made to any artifact (re-run affected rows).
+- When stakeholders ask "is feature X covered?" — the matrix answers immediately.
+- When prioritizing cuts — the matrix shows what is affected if a requirement is deferred.