Documentation Creation Criteria

Templates

• prd-template.md - Product Requirements Document template
• adr-template.md - Architecture Decision Record template
• ui-spec-template.md - UI Specification template (frontend/fullstack features)
• design-template.md - Technical Design Document template
• plan-template.md - Work Plan template
• task-template.md - Task file template for implementation tasks

Creation Decision Matrix

ADR Creation Conditions (Required if Any Apply)

1. Contract System Changes

• Adding nested contracts with 3+ levels: Contract A { Contract B { Contract C { field: T } } }
  • Rationale: Deep nesting has high complexity and wide impact scope
• Changing/deleting contracts used in 3+ locations
  • Rationale: Multiple location impacts require careful consideration
• Contract responsibility changes (e.g., DTO→Entity, Request→Domain)
  • Rationale: Conceptual model changes affect design philosophy

2. Data Flow Changes

• Storage location changes (DB→File, Memory→Cache)
• Processing order changes with 3+ steps
  • Example: "Input→Validation→Save" to "Input→Save→Async Validation"
• Data passing method changes (parameter passing→shared state, direct reference→event-based communication)

3. Architecture Changes

• Layer addition, responsibility changes, component relocation

4. External Dependency Changes

• Library/framework/external API introduction or replacement

5. Complex Implementation Logic (Regardless of Scale)

• Managing 3+ states
• Coordinating 5+ asynchronous processes

Detailed Document Definitions

PRD (Product Requirements Document)

Purpose: Define business requirements and user value

Includes:

• Business requirements and user value
• Success metrics and KPIs (measurable format)
• User stories and use cases
• MoSCoW prioritization (Must/Should/Could/Won't)
• MVP and Future phase separation
• User journey diagram (required)
• Scope boundary diagram (required)

Excludes:

• Technical implementation details (→Design Doc)
• Technical selection rationale (→ADR)
• Implementation phases (→Work Plan)
• Task breakdown (→Work Plan)

ADR (Architecture Decision Record)

Purpose: Record technical decision rationale and background

Includes:

• Decision (what was selected)
• Rationale (why that selection was made)
• Option comparison (minimum 3 options) and trade-offs
• Architecture impact
• Principled implementation guidelines (e.g., "Use dependency injection")

Excludes:

• Implementation schedule, duration (→Work Plan)
• Detailed implementation procedures (→Design Doc)
• Specific code examples (→Design Doc)
• Resource assignments (→Work Plan)

UI Specification

Purpose: Define UI structure, screen transitions, component decomposition, and interaction design for frontend features

Includes:

• Screen list and transition conditions
• Component decomposition with state x display matrix (default/loading/empty/error/partial)
• Interaction definitions linked to PRD acceptance criteria (EARS format)
• Prototype management (code-based prototypes as attachments, not source of truth)
• AC traceability from PRD to screens/components
• Existing component reuse map and design tokens
• Visual acceptance criteria (golden states, layout constraints)
• Accessibility requirements (keyboard, screen reader, contrast)

Excludes:

• Technical implementation details (-> Design Doc)
• API contracts and data layer design (-> Design Doc)
• Test implementation (-> acceptance-test-generator skeletons)
• Implementation schedule (-> Work Plan)

Required Structural Elements:

• At least one component with state x display matrix and interaction table
• AC traceability table mapping PRD ACs to screens/states
• Screen list with transition conditions
• Existing component reuse map (reuse/extend/new decisions)

Prototype Code Handling:

• Prototype code provided by user is placed in docs/ui-spec/assets/{feature-name}/
• Prototype is an attachment to UI Spec, never the source of truth
• UI Spec + Design Doc are the canonical specifications

Design Document

Purpose: Define technical implementation methods in detail

Includes:

• Existing codebase analysis (required)
  • Implementation path mapping (both existing and new)
  • Integration point clarification (connection points with existing code even for new implementations)
• Technical implementation approach (vertical/horizontal/hybrid)
• Technical dependencies and implementation constraints (required implementation order)
• Interface and contract definitions
• Data flow and component design
• Acceptance criteria (measurable format)
• Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
• Complete enumeration of integration points
• Data contract clarification
• Agreement checklist (agreements with stakeholders)
• Code inspection evidence (inspected files/functions during investigation)
• Field propagation map (when fields cross component boundaries)
• Data representation decision (when introducing new structures)
• Applicable standards (explicit/implicit classification)
• Prerequisite ADRs (including common ADRs)
• Verification Strategy (required)
  • Correctness proof method (what "correct" means for this change, how it's verified, when)
  • Early verification point (first target to prove the approach works, success criteria, failure response)

Required Structural Elements:

Change Impact Map:
  Change Target: [Component/Feature]
  Direct Impact: [Files/Functions]
  Indirect Impact: [Data format/Processing time]
  No Ripple Effect: [Unaffected features]

Interface Change Matrix:
  Existing: [Function/method/operation name]
  New: [Function/method/operation name]
  Conversion Required: [Yes/No]
  Compatibility Method: [Approach]

Excludes:

• Why that technology was chosen (→Reference ADR)
• When to implement, duration (→Work Plan)
• Who will implement (→Work Plan)

Work Plan

Purpose: Implementation task management and progress tracking

Includes:

• Task breakdown and dependencies (maximum 2 levels)
• Schedule and duration estimates
• Include test skeleton file paths from acceptance-test-generator (integration and E2E)
• Verification Strategy summary (extracted from Design Doc)
• Final Quality Assurance Phase (required)
• Progress records (checkbox format)

Excludes:

• Technical rationale (→ADR)
• Design details (→Design Doc)

Phase Division Criteria (adapt to implementation approach from Design Doc):

When Vertical Slice selected:

• Each phase = one value unit (feature, component, or migration target)
• Each phase includes its own implementation + verification per Verification Strategy
• Final Phase: Quality Assurance (cross-cutting verification, all tests passing)

When Horizontal Slice selected:

1. Phase 1: Foundation Implementation - Contract definitions, interfaces/signatures, test preparation
2. Phase 2: Core Feature Implementation - Business logic, unit tests
3. Phase 3: Integration Implementation - External connections, presentation layer
4. Final Phase: Quality Assurance (Required) - Acceptance criteria achievement, all tests passing, quality checks

When Hybrid selected:

• Combine vertical and horizontal as defined in Design Doc implementation approach
• Final Phase: Quality Assurance (Required)

All approaches: Final phase is always Quality Assurance. Each phase's verification method follows Verification Strategy from Design Doc.

Three Elements of Task Completion Definition:

1. Implementation Complete: Code is functional
2. Quality Complete: Tests, static checks, linting pass
3. Integration Complete: Verified connection with other components

Creation Process

1. Problem Analysis: Change scale assessment, ADR condition check
   • Identify explicit and implicit project standards before investigation
2. ADR Option Consideration (ADR only): Compare 3+ options, specify trade-offs
3. Creation: Use templates, include measurable conditions
4. Approval: "Accepted" after review enables implementation

Storage Locations

*Note: Work plans are excluded by .gitignore

ADR Status

Proposed → Accepted → Deprecated/Superseded/Rejected

AI Automation Rules

• 5+ files: Suggest ADR creation
• Contract/data flow change detected: ADR mandatory
• Check existing ADRs before implementation

Diagram Requirements

Required diagrams for each document (using mermaid notation):

Common ADR Relationships

1. At creation: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
2. When missing: Consider creating necessary common ADRs
3. Design Doc: Specify common ADRs in "Prerequisite ADRs" section
4. Compliance check: Verify design aligns with common ADR decisions