plan

name	plan
description	Structured project plan format with required sections and examples.

Annotated Project Plan Example

This document provides a comprehensive example of an excellent project plan with clear instructions for each section. The example demonstrates implementing a notification system with real-time updates and user preferences.

Plan Versioning Convention

Project plans follow a versioning convention:

• Initial plan: plan-v1.md
• Revised plans: plan-v2.md, plan-v3.md, etc.
• Each version should be self-contained without references to other versions
• Version updates occur when assessment identifies issues or user provides feedback

Front Matter (Optional but Powerful)

```yaml --- dependencies: - user-preferences-api # Only list actual blocking dependencies - event-bus-setup # Must complete before this project preventAutoProgress: true # Add only when user review is critical before code changes --- ``` The YAML front matter is optional. Only use it when: - `dependencies`: Other projects that MUST complete before yours can start (true blockers only) - `preventAutoProgress: true`: Critical production changes or user explicitly requests review

Most plans should NOT include front matter.

---

Title Format

```markdown # Implementation Project: Real-Time Notification System ``` Must follow: `# Implementation Project: [Clear, Specific Title]` - Always use "Implementation Project" (not "Project" or "Plan") - Keep title specific and concise (3-7 words after the colon) - Never use generic terms like "Update" or "Feature" - Don't include version numbers or dates

---

Problem Statement

```markdown ## Problem Statement The application currently lacks real-time notification capabilities, requiring users to manually refresh pages to see updates. This leads to delayed awareness of important events, reduced user engagement, and a subpar user experience compared to modern web applications. ``` Write 2-4 sentences that: 1. Explain the current state and its limitations 2. Describe the negative impact on users or the system 3. Make clear why this needs to be solved now 4. Avoid proposing solutions (save for Technical Approach)

---

Goals & Objectives

```markdown ## Goals & Objectives - [ ] Create notification queue with priority-based ordering - [ ] Implement real-time delivery via WebSocket connections - [ ] Build notification center UI with read/unread states - [ ] Add user preference controls for notification types - [ ] Ensure notifications persist across page refreshes - [ ] Support batching for high-frequency event streams ``` Write 3-7 specific, measurable goals using checkbox format: `- [ ]`

Each goal must be:

• Verifiable (you can definitively check if it's done)
• An outcome, not a process (what will exist, not how to build)
• Directly addressing the user's request

❌ Bad: "Make notifications better", "Research libraries", "Try to add real-time" ✅ Good: "Process 100+ notifications/second without UI lag", "Unread count updates within 500ms"

Note: Goals and Objectives mean the same thing - we use both terms for clarity.

---

Scope

```markdown ## Scope

Include

• In-app notification delivery and display
• Real-time updates via WebSocket connections
• Notification center dropdown component
• User preference storage and enforcement
• Read/unread state management
• Sound/badge indicators for new notifications

Exclude

• Email notification delivery
• Push notifications to mobile devices
• SMS or other external channels
• Notification scheduling/delayed delivery
• Rich media attachments (images, files)
• Notification analytics or tracking

</example>

<instructions>
Define clear boundaries for what is and isn't part of this project.

### Include
- List all features that WILL be built
- Be specific about technical limits (e.g., "100 notifications/second")
- Reference existing systems you'll integrate with

### Exclude (CRITICAL - prevents scope creep)
- Explicitly list what will NOT be built
- Features deferred to future versions
- Related functionality that's out of scope
- Platforms or use cases not being addressed

The Exclude section saves more time than any other part by preventing scope creep.
</instructions>

---

## Framework & Technology Stack

<example>
```markdown
## Framework & Technology Stack

### Core Technologies
- Node.js: v20.11.0
- React: react@18.2.0
- TypeScript: typescript@5.3.3

### Frameworks
- Next.js: next@14.1.0 (App Router)
- Express: express@4.18.2

### Testing
- Jest: jest@29.7.0
- Playwright: @playwright/test@1.41.0
- Testing Library: @testing-library/react@14.1.2

### Key Libraries
- WebSocket: socket.io@4.6.1 - Real-time communication
- State Management: zustand@4.5.0 - Client state management
- Validation: zod@3.22.4 - Schema validation
- Database: @prisma/client@5.8.0 - ORM

### Version-Specific Features Used
- React (react@18.2.0): Suspense boundaries, concurrent rendering
- Node.js v20.11.0: Native WebCrypto API, stable test runner
- TypeScript (typescript@5.3.3): satisfies operator, const type parameters

Document all framework and library versions that constrain the implementation.

Required Structure

1. Core Technologies: Node.js, React, TypeScript versions
2. Frameworks: Next.js, Express, etc.
3. Testing: Test runners and libraries
4. Key Libraries: Important dependencies with purpose
5. Version-Specific Features Used: Features that depend on specific versions

Common Formats (all acceptable)

• Node.js: v20.11.0 or 20.11.0
• React: react@18.2.0 or 18.2.0
• TypeScript: typescript@5.3.3 or 5.3.3
• Exact versions preferred over ranges for reproducibility
• Add purpose for key libraries when helpful (e.g., "- Git Operations: simple-git@3.20.0 - Execute git commands")

Version-Specific Features Examples

• React 18+: Suspense, Server Components, use() hook
• React 19+: Actions, optimistic updates
• Node.js 18+: Native fetch API
• TypeScript 5+: Decorators, satisfies operator
• Next.js 13+: App Router vs Pages Router

Populate from technology stack identification in analysis phase.

---

Technical Spikes (When Needed)

Include this section when you have critical technical unknowns requiring empirical investigation. This includes strategic spikes (comparing alternatives) or tactical spikes (validating chosen approaches). Omit this section if all technical assumptions are validated by existing code or documentation.

Technical spikes are empirical investigations that resolve uncertainty through working code and prototypes. They produce actionable insights that inform technical decisions.

When to Conduct Technical Spikes

Strategic Spikes (Comparing Alternatives):

• Technology Selection: Choosing between multiple viable real-time approaches, state management libraries, or build tools
• Architecture Pattern Evaluation: Testing different integration patterns or data flow approaches
• Unfamiliar Technology Assessment: Prototyping with new frameworks or testing emerging standards

Tactical Spikes (Validating Chosen Approach):

• Version Compatibility: Does library@version support needed features?
• API/Export Verification: Do libraries expose needed types, functions, or methods?
• Framework Behavior: Version-specific behaviors and constraints
• Integration Validation: Do chosen libraries work together in your configuration?
• Performance Feasibility: Does chosen approach meet basic performance requirements?

When to Skip Spikes

• The approach/technology has not been chosen yet (research codebase first)
• Well-documented framework features with clear examples
• Internal code patterns already established
• Standard operations with known patterns

```markdown ## Technical Spike Results

Real-Time Communication Approach Selection

Type: Strategic Spike

• Question: Which real-time approach (WebSocket, Server-Sent Events, or long-polling) best supports notification requirements with horizontal scaling?
• Approaches Tested: Socket.io v4.6.1 (WebSocket), native EventSource (SSE), polling with state management
• Comparison Criteria: Bidirectional communication support, horizontal scaling capability with Redis, developer experience
• Result: Socket.io recommended - provides bidirectional communication, scales with Redis adapter, better developer experience
• Evidence:
  • WebSocket (Socket.io): Bidirectional communication working, <50ms latency, Redis pub/sub integration tested successfully
  • SSE (EventSource): Server→client only, requires separate POST endpoint for client→server
  • Polling: Functional but 23% higher server CPU usage, more complex state synchronization
• Artifacts: [PROJECT_PATH]/scratchpad/realtime-comparison/ contains:
  • approach-socketio/ - Socket.io prototype with Redis adapter
  • approach-sse/ - EventSource implementation with POST fallback
  • approach-polling/ - Polling strategy with state management
  • comparison.md - Side-by-side analysis
  • recommendation.md - Selection rationale
• Impact: Selected Socket.io as Technical Approach; enables bidirectional real-time features with horizontal scaling via Redis adapter

Socket.io Redis Adapter Compatibility

Type: Tactical Spike

• Question: Does Socket.io v4.6.1 support Redis adapter for cross-instance message broadcasting?
• Approach Tested: Created minimal Socket.io server with @socket.io/redis-adapter, tested multi-instance communication
• Result: Confirmed v4.6.1 supports Redis adapter with connection state sharing
• Evidence: Successfully broadcast messages across 3 server instances, verified in scratchpad test
• Artifacts: [PROJECT_PATH]/scratchpad/socketio-redis-test/ contains server prototype and Redis config
• Impact: Can proceed with horizontal scaling approach; no single-server bottleneck

TypeScript Satisfies with Zustand Stores

Type: Tactical Spike

• Question: Can Zustand v4.5.0 stores use TypeScript 5.3.3's satisfies operator for type-safe state?
• Approach Tested: Created sample notification store using satisfies for state shape validation
• Result: Zustand fully supports satisfies operator with proper type inference
• Evidence: Store compiles without errors, provides autocomplete, catches violations at compile time
• Artifacts: [PROJECT_PATH]/scratchpad/zustand-typescript-satisfies/notification-store.ts
• Impact: Can use type-safe patterns without 'as' assertions, reducing runtime errors

Virtual Scrolling with React Concurrent Features

Type: Tactical Spike

• Question: Does react-window v1.8.10 work with React 18.2.0 concurrent rendering for 1000+ items?
• Approach Tested: Created test component with 2000-item list using react-window and concurrent rendering
• Result: Maintains <16ms frame time, smooth 60fps scrolling
• Evidence: Performance profiling shows no layout thrashing, memory stable at ~45MB
• Artifacts: [PROJECT_PATH]/scratchpad/virtual-scroll-test/NotificationList.tsx with profiling results
• Impact: Confirmed approach meets performance requirements; can handle notification list scaling

</example>

---

## Technical Approach

<example>
```markdown
## Technical Approach
1. **Create notification store interface** (packages/web/src/stores/notification-store.ts:12)
   - Add `notifications: Notification[]` array to state
   - Add `unreadCount: number` computed property
   - Implement queue management with priority sorting

2. **Define notification message types** (packages/shared/src/types/events.ts:45)
   - Create `NotificationEvent` interface with type, priority, payload
   - Add to existing EventType enum for type safety
   - Include timestamp and unique ID generation

3. **Build WebSocket subscription handler** (packages/web/src/hooks/use-notification-stream.ts)
   - Subscribe to user-specific notification channel
   - Handle reconnection with missed notification catch-up
   - Implement client-side deduplication by event ID

4. **Create notification center component** (packages/web/src/components/ui/notification-center.tsx)
   - Dropdown panel triggered by bell icon in header
   - Virtual scrolling for large notification lists
   - Mark-as-read on hover with debounce

5. **Add preference management** (packages/api/src/services/user-preferences.ts:78)
   - Store notification settings per category
   - Apply filters at event emission point
   - Cache preferences for performance

6. **Implement batching logic** (packages/api/src/services/notification-batcher.ts)
   - Collect events in 100ms windows
   - Group by recipient and notification type
   - Send as single WebSocket message per batch

Describe the implementation steps in concrete but flexible terms.

Requirements

1. Number each major step sequentially
2. Include verified file paths where changes will occur
3. Add line numbers when referencing existing code (e.g., :78)
4. Describe WHAT to do, not HOW to implement it
5. Keep each step focused on a single concern

Line Number Guidelines

• Skip line numbers for new files
• Include them when referencing specific existing code
• Use "around line X" if the exact line might shift

Avoid

• Implementation details or algorithms
• Complete function signatures
• UI layout specifics
• Error handling details (unless critical to approach)

Code Example Guidelines

Include code examples that clarify complex structures without dictating implementation:

```typescript // Example: Notification data structure (clarifies format) interface Notification { id: string; type: 'comment' | 'mention' | 'system'; priority: 1 | 2 | 3; // 1 = high, 3 = low timestamp: number; read: boolean; data: Record; }

// Example: WebSocket event format (defines contract) type NotificationBatch = { type: 'notification.batch'; notifications: Notification[]; missedCount?: number; // For reconnection scenarios };

</example>

<instructions>
Include code examples ONLY when they clarify contracts or complex data structures.

Good code examples show:
1. Type definitions and interfaces for data structures
2. API contracts between systems
3. Expected data transformations (input → output format)
4. Integration points with existing code (with file references)
5. Configuration shapes or option objects

Never include:
1. Full function implementations
2. Step-by-step algorithms
3. UI component implementations
4. Error handling code
5. Business logic details

Keep examples minimal - just enough to clarify without constraining implementation choices.
</instructions>


---

## Dependency Analysis

<example>
```markdown
## Dependency Analysis

### High-Impact Files
- packages/shared/src/types/events.ts (743 imports) - Core event types used throughout system
- packages/web/src/hooks/use-websocket.ts (521 imports) - WebSocket connection hook all real-time features use
- packages/api/src/middleware/auth.ts (234 imports) - Auth required for notification filtering

### Key Integration Points
- packages/web/src/components/layout/header.tsx - Where notification bell icon mounts
- packages/api/src/services/event-emitter.ts - Central event dispatch for notifications
- packages/web/src/stores/index.ts - Store registry for new notification store

### External Dependencies
- @supabase/ssr: ^0.0.10 (authentication)
- zod: ^3.22.0 (validation, already in package.json)

Identify files that are critical dependencies or integration points for your implementation.

Structure Requirements

• High-Impact Files: List files with significant import counts that you'll modify
• Key Integration Points: Files where your new code connects to existing systems
• External Dependencies: Libraries needed (note if already in package.json)

Include actual import counts in parentheses (e.g., "auth.ts (234 imports)") to indicate risk level. List files where your new code connects to existing systems with brief descriptions.

---

Validation Commands

```markdown ## Validation Commands - Type check: 'cd packages/web && yarn typecheck' - Test: 'cd packages/web && yarn test' - Lint: 'cd packages/web && yarn lint' - E2E: 'cd packages/web && yarn test:e2e' ``` ⚠️ **MANDATORY SECTION**: Every plan MUST include validation commands.

Provide ALL quality validation commands that must pass for implementation to be considered complete.

Minimum Required Commands (must include at minimum):

1. Type checking (e.g., yarn typecheck, tsc --noEmit)
2. Unit/integration tests (e.g., yarn test)
3. Linting (e.g., yarn lint, eslint)

Additional Validation Commands (include when applicable):

• E2E tests (e.g., yarn test:e2e)
• Integration tests (e.g., yarn test:integration)
• Contract tests (e.g., yarn test:contract)
• Any other commands that verify correctness

Process:

1. Identify affected packages from your Technical Approach
2. Check each package's package.json for validation scripts
3. Format as executable commands from workspace root
4. Include ALL validation commands - never skip tests

For multiple packages:

## Validation Commands
### packages/[package-1]
- Type check: 'cd packages/[package-1] && yarn typecheck'
- Test: 'cd packages/[package-1] && yarn test'
- Lint: 'cd packages/[package-1] && yarn lint'

### packages/[package-2]
- Type check: 'cd packages/[package-2] && yarn typecheck'
- Test: 'cd packages/[package-2] && yarn test:e2e'
- Lint: 'cd packages/[package-2] && yarn lint'

Note: These commands will be executed by the orchestrator to verify implementation quality. ALL commands must pass with zero errors.

---

Other Package Commands (Optional)

```markdown ## Other Package Commands - Build: 'cd packages/web && yarn build' - Run dev server: 'cd packages/web && yarn dev' - Add dependency: 'cd packages/api && yarn add express@4.18.0' - Run simulation: 'cd packages/simulation && yarn tsx src/run.ts' ``` **OPTIONAL SECTION**: Include operational commands that are NOT validation but may be useful for development or deployment.

Include commands for:

• Building artifacts (e.g., yarn build)
• Running development servers (e.g., yarn dev)
• Adding dependencies (e.g., yarn add package@version)
• Running specific tools or scripts (e.g., yarn tsx src/script.ts)
• Database migrations (e.g., yarn migrate)
• Deployment (e.g., yarn deploy)

Do NOT include in this section:

• Type checking, testing, or linting (those go in Validation Commands)
• Any command that verifies code correctness

Skip this section entirely if there are no operational commands to document.

---

Risks & Mitigations

```markdown ## Risks & Mitigations - **Risk**: Browser notification API permissions vary by browser **Mitigation**: Graceful degradation to in-app only when API unavailable

• Risk: High-frequency events could overwhelm clients Mitigation: Server-side rate limiting at 100 events/second per user

• Risk: Notifications lost during WebSocket reconnection Mitigation: Include last-received timestamp in reconnect, server replays missed

• Risk: Storage quota exceeded with too many notifications Mitigation: Implement rolling window keeping only last 1000 notifications

</example>

<instructions>
Identify technical risks that could cause the implementation to fail or perform poorly.

Focus on:
1. Technical risks only (not project management risks)
2. Specific, discovered concerns (not generic worries)
3. Actionable mitigations (not "be careful")

Common risk categories:
- Browser compatibility differences
- Performance degradation at scale
- Network reliability issues
- State synchronization problems
- Resource limitations (memory, storage)
- Security or permission constraints

Format each risk as:
- **Risk**: [Specific technical concern]
  **Mitigation**: [Concrete solution or approach]

Include 3-5 most significant risks. More than 5 suggests over-analysis.
</instructions>

---

## Implementation References (Optional)

<example>
```markdown
## Implementation References
- Event patterns: packages/api/src/services/analytics-events.ts:123 - Similar event batching
- WebSocket setup: packages/web/src/hooks/use-chat.ts:45 - Real-time subscription pattern
- Dropdown UI: packages/web/src/components/ui/dropdown-menu.tsx:12 - Reusable dropdown
- Virtual scroll: packages/web/src/components/tables/data-table.tsx:234 - Virtual rendering
- Storage: https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas

Include this section ONLY when you have specific, helpful references.

Good references include:

1. Similar patterns in the codebase (with file:line references)
2. Reusable components or utilities
3. External documentation for complex APIs
4. Example implementations to follow

Guidelines:

• Include line numbers for precision
• Explain briefly why each reference is relevant
• Limit to 3-5 most helpful references
• Verify all file paths before including them

Skip this section if you don't have genuinely useful references.

---

Open Questions (Optional)

```markdown ## Open Questions

• Payment provider selection — decision needed by Dec 1
• Redis cluster sizing — needs load testing before finalization
• Authentication approach — resolved: using existing OAuth (see project log)

Assumptions (believed true, unvalidated):

• Users have reliable internet connection
• Peak load won't exceed 10x current baseline

</example>

<instructions>
Document uncertainties explicitly:
- Use checkboxes for trackable decisions ([ ] open, [x] resolved)
- Include deadlines or dependencies where applicable
- List assumptions separately—these are risks if wrong
- Update as questions resolve—add Decision Record to project log

Source: project-plan-report.md line 33, 52
> "Noting it in the PRD flags it for resolution... if some aspects are uncertain,
> acknowledge them in the plan rather than papering over them."
</instructions>

---

## User Scenarios (Optional)

<example>
```markdown
## User Scenarios

### Scenario: Real-time mention notification
1. Alice is editing document "Q3 Report"
2. Bob mentions @Alice in a comment
3. Within 500ms, Alice sees bell icon increment and toast notification
4. Alice clicks notification, navigates to comment
5. Notification marked as read automatically

Include 1-3 scenarios illustrating key user journeys: - Use specific names (Alice, Bob) for clarity - Include concrete values (500ms, not "quickly") - Show complete user experience from trigger to completion - Helps testers derive accurate test cases

Only include for complex features where prose requirements might be ambiguous.

### 1. Vague Goals ❌ "Improve notification system performance" ✅ "Process 100+ notifications/second without UI lag"

2. Over-Detailed Technical Approach

❌ "Create processNotification() function that takes a Notification object..." ✅ "Build notification processing pipeline with priority ordering"

3. Missing Scope Exclusions

❌ Only listing what's included ✅ Both Include AND Exclude sections

4. Generic Risks

❌ "Risk: Performance issues. Mitigation: Optimize the code" ✅ "Risk: High-frequency events could overwhelm clients. Mitigation: Server-side rate limiting at 100 events/second"

5. Guessed File Paths

❌ "Update notification service (probably in src/services/notifications.ts)" ✅ "Update notification dispatcher (packages/api/src/services/event-emitter.ts:234)"

6. Missing Version Information

❌ "React: latest" or "Node.js: current" ✅ "React: 18.2.0" or "React: react@18.2.0" (both acceptable)

### The Wishlist Plan **Symptoms**: 20+ goals, no clear priority, "wouldn't it be nice if..." **Fix**: Ruthlessly cut to 3-7 goals that directly solve the stated problem

The Implementation Manual

Symptoms: Step-by-step algorithms, complete function signatures, UI specs Fix: Stay at "what to build" level, leave "how" to implementers

The Eternal Draft

Symptoms: TBD throughout, vague language, "we'll figure it out" Fix: Resolve unknowns via spikes before planning, or mark as explicit blockers

The Kitchen Sink

Symptoms: Scope Include is long, Exclude is empty or minimal Fix: Exclude section should be longer—explicitly reject adjacent features

The Copy-Paste Template

Symptoms: Generic risks, placeholder text, inapplicable sections Fix: Every section must contain project-specific content or be omitted

The Stale Artifact

Symptoms: Plan doesn't match current implementation or decisions Fix: Update plan when scope changes, add Decision Record to project log

The Oracle

Symptoms: Requirements without rationale, "because I said so" decisions, missing trade-off documentation Fix: Add rationale inline or in dedicated section, document alternatives considered

Source: project-plan-report.md lines 72-73

1. **Precision**: Use verified file paths with line numbers 2. **YAGNI**: Only features solving the immediate problem 3. **Integration Over Innovation**: Reuse existing patterns 4. **Examples Clarify, Not Constrain**: Show data shapes, not implementations 5. **Test the Risks**: Focus on what could actually fail 6. **Scope Exclusions Prevent Creep**: Explicitly state what's NOT included

7. Testability: For each requirement, ask "How would we test this?" If no clear test exists, the requirement needs more specificity.

8. Ubiquitous Language: Use consistent terminology matching the codebase. If code says ShoppingCart, plan says "Shopping Cart" not "Basket." Source: project-plan-report.md lines 101-102

   "The PRD should speak the same language as the code and business domain... ensures no translation gap between requirements and implementation."

9. Evolution Readiness: Structure plans for change—modular sections, explicit uncertainties, version tracking.

10. Decisions in Log, Not Plan: Significant decisions are captured in the project log (log.md) as Decision Records. Plans reference outcomes, not decision history. This keeps plans focused on "what to build" while the log captures "why we chose this."

The best plan answers "what" and "where" while leaving "how" to the implementer.

### Quick Assessment (use before loading full methodologies)

For lightweight issues, apply these inline checks without loading methodology files:

1. Vagueness check: Flag terms "fast", "user-friendly", "intuitive", "scalable", "reliable" without definitions
2. Testability check: Ask "How would we test this?" — if no clear answer, requirement needs work
3. Scope check: Sparse Exclude section (< 3 items) suggests insufficient boundary thinking
4. Rationale check: Technology choices without "because" or "selected over" phrases lack justification

Load full methodology only when remediation guidance is needed or the issue is complex.

Full Methodologies

Select and load methodology documents based on the quality issues you encounter during assessment:

• Read methodology/vague-language-detection.md if requirements contain subjective terms like "fast", "user-friendly", or "scalable" without definitions. Provides systematic patterns for identifying ambiguous language and transforming it into specific, measurable criteria. Use when you cannot envision a clear test case for a requirement or when numeric thresholds are missing from performance claims.
• Read methodology/coherence-checking.md if plan sections appear to contradict each other or use inconsistent terminology. Provides verification processes for cross-referencing values, terms, and scope items across all plan sections. Use when performance targets differ between sections, terminology is inconsistent, or scope boundaries conflict with technical approach.
• Read methodology/rationale-capture.md if technical decisions lack justification or trade-offs are undocumented. Provides patterns for capturing technology selection reasoning, constraint origins, and exclusion rationale. Use when future maintainers would ask "why was this done?" or when scope exclusions lack explanation.
• Read methodology/scope-management.md if the Exclude section is sparse or features use speculative language like "might need" or "for future use". Provides YAGNI assessment framework and scope defense protocols for maintaining clear project boundaries. Use when features aren't tied to the problem statement or when scope creep indicators appear in Technical Approach.
• Read methodology/testability-assessment.md if you cannot answer "How would we test this?" for a requirement. Provides criteria for verifying requirements are observable, measurable, and deterministic with clear pass/fail conditions. Use when goals use subjective success criteria or acceptance criteria are abstract.
• Read methodology/nfr-completeness.md if non-functional requirements are missing or assumed but not documented. Provides checklists for performance, reliability, security, and scalability coverage with assessment questions for each category. Use when there are no latency targets for user-facing operations or when scalability expectations are based on hope rather than evidence.
• Read methodology/document-evolution.md if open questions are hidden in prose rather than explicit or sections aren't modular. Provides mechanisms for decision tracking via project log, open questions management, and modular section structure that supports iterative refinement. Use when assessing whether the plan can evolve healthily as implementation progresses.

## Quick Reference

Required Sections (in order)

1. Title: # Implementation Project: [Title]
2. Problem Statement: 2-4 sentences
3. Goals & Objectives: 3-7 checkbox items
4. Scope: Include AND Exclude sections
5. Framework & Technology Stack: package@version format
6. Technical Approach: Numbered steps with file paths
7. Dependency Analysis: High-impact files + integration points
8. Validation Commands: Typecheck, test, lint (minimum required)
9. Risks & Mitigations: 3-5 technical risks

Optional Sections

• Front Matter: Dependencies or preventAutoProgress
• Technical Spikes: 2+ critical unknowns requiring investigation
• Other Package Commands: Build, run, deploy commands
• Implementation References: Helpful code examples

Key Rules

✅ Verified file paths with line numbers ✅ WHAT to build, not HOW ✅ Exclude v2 features explicitly ❌ No implementation details ❌ No guessed file paths ❌ No vague goals