Documentation Creation Criteria

Creation Decision Matrix

ADR Creation Conditions (Required if Any Apply)

1. Type System Changes

• Adding nested types with 3+ levels:

  type A = { b: { c: { d: T } } }

  • Rationale: Deep nesting has high complexity and wide impact scope
• Changing/deleting types used in 3+ locations
  • Rationale: Multiple location impacts require careful consideration
• Type responsibility changes (e.g., DTO->Entity)
  • 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 (props->Context, direct reference->events)

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)

• 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)

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

ADR (Architecture Decision Record)

• 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")

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

Design Document

• 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 type definitions
• Data flow and component design
• E2E verification procedures at integration points
• Acceptance criteria (EARS format: When/While/If-then/none)
• 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)

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

Work Plan

• Task breakdown and dependencies (maximum 2 levels)
• Schedule and duration estimates
• Copy E2E verification procedures from Design Doc (cannot delete, can add)
• Phase 4 Quality Assurance Phase (required)
• Progress records (checkbox format)

• Technical rationale (->ADR)
• Design details (->Design Doc)

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

1. Implementation Complete: Code is functional
2. Quality Complete: Tests, type 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

docs/prd/

[feature-name]-prd.md

docs/adr/

ADR-[4-digits]-[title].md

docs/design/

[feature-name]-design.md

docs/plans/

YYYYMMDD-{type}-{description}.md

docs/plans/tasks/

{plan-name}-task-{number}.md

.gitignore

ADR Status

Proposed

Accepted

Deprecated

Superseded

Rejected

AI Automation Rules

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

Diagram Requirements

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

Templates

references/

• Design Document template
• Product Requirements Document template
• Work Plan template
• Architecture Decision Record template
• Task File template