git:20251230.9a88ee8 to git:20251231.cb53cf6

1 added, 3 removed. Audit A to A.

---

name: documentation-criteria

- description: >

- Guides PRD, ADR, Design Doc, and Work Plan creation with templates and decision matrix.

- Use when: planning features, writing specs, creating technical documents, or deciding which docs are needed.

+ description: "Guides PRD, ADR, Design Doc, and Work Plan creation. Use when: planning features, writing specs, or creating technical documents."

---

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

- **Prerequisite ADRs** (including common ADRs)

**Required Structural Elements**:

```yaml

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

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

|----------|------|------------------|----------|

| 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