Documentation Criteria

Documentation Creation Criteria

Creation Decision Matrix

| Condition | Required Documents | Creation Order | |-----------|-------------------|----------------| | New Feature Addition | PRD → [ADR] → Design Doc → Work Plan | After PRD approval | | ADR Conditions Met (see below) | ADR → Design Doc → Work Plan | Start immediately | | 6+ Files | ADR → Design Doc → Work Plan (Required) | Start immediately | | 3-5 Files | Design Doc → Work Plan (Recommended) | Start immediately | | 1-2 Files | None | Direct implementation |

ADR Creation Conditions (Required if Any Apply)

1. Type System Changes

• Adding nested types/structures with 3+ levels: e.g., A { B { C { D } } }
• Rationale: Deep nesting has high complexity and wide impact scope
• Changing/deleting types used in 3+ locations
• Rationale: Multiple location impacts require careful consideration
• Data representation responsibility changes (e.g., transfer object→domain model)
• 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)

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
• Scope boundary diagram

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 decisions

Includes:

• Decision (what was selected)
• Rationale (why that selection was made)
• Option comparison (minimum 3 options) and trade-offs
• Architecture impact
• Principled implementation guidelines

Excludes:

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

Design Document

Purpose: Define technical implementation

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 type definitions
• Data flow and component design
• E2E verification procedures at integration points
• 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)

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]

API Contract Change Matrix:
  Existing: [Function/operation signature]
  New: [Function/operation signature]
  Conversion Required: [Yes/No]
  Compatibility Strategy: [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
• Copy E2E verification procedures from Design Doc (cannot delete, can add)
• Stage 4 Quality Assurance Stage (required)
• Progress records (checkbox format)

Excludes:

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

Stage Division Criteria:

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

Three Elements of Task Completion Definition:

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

1. ADR Option Consideration (ADR only): Compare 3+ options, specify trade-offs
2. Creation: Use templates, include measurable conditions
3. Approval: "Accepted" after review enables implementation

Storage Locations

| Document | Path | Naming Convention | Template | |----------|------|------------------|----------| | PRD | docs/prd/ | [feature-name]-prd.md | template-en.md | | ADR | docs/adr/ | ADR-[4-digits]-[title].md | template-en.md | | Design Doc | docs/design/ | [feature-name]-design.md | template-en.md | | Work Plan | docs/plans/ | YYYYMMDD-{type}-{description}.md | template-en.md |

*Note: Work plans are stored in docs/plans/ and excluded by .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

Required diagrams for each document (using mermaid notation):

| Document | Required Diagrams | Purpose | |----------|------------------|---------| | PRD | User journey diagram, Scope boundary diagram | Clarify user experience and scope | | ADR | Option comparison diagram (when needed) | Visualize trade-offs | | Design Doc | Architecture diagram, Data flow diagram | Understand technical structure | | Work Plan | Phase structure diagram, Task dependency diagram | Clarify implementation order |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shinpr
• Source: shinpr/agentic-code
• License: MIT

Install and usage instructions live in the source repository linked above.