| name | documentation-criteria |
| description | This skill should be used when the user asks to "create a PRD", "write an ADR", "create a design doc", "make a work plan", "create task files", or needs guidance on document templates, creation criteria, or determining which documents are required for a given change scope. |
Documentation Creation Criteria
Templates
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 |
| New Game Project | GDD → Market Analysis → [ADR] → Design Doc → Work Plan | After GDD approval |
| New Game Feature | Feature Spec → [GDD Update] → Design Doc → Work Plan | After Feature Spec approval |
| Art/Visual Change | Art Direction → Design Doc | After Art Direction approval |
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)
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
- 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:
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)
GDD (Game Design Document)
Purpose: Define game vision, core mechanics, progression, and systems
Includes:
- Core loop
- Game pillars
- Progression systems
- Balancing parameters
- Content specifications
Excludes:
- Technical implementation (→Design Doc)
- Market analysis (→Market Analysis)
- Art specifications (→Art Direction)
Market Analysis
Purpose: Validate market opportunity and competitive positioning
Includes:
- Competitor analysis
- Market sizing
- Target audience
- Monetization potential
- Risk assessment
- Go/No-Go recommendation
Excludes:
- Game design details (→GDD)
- Technical specs (→Design Doc)
Feature Specification
Purpose: Detailed specification of a single game feature or system
Includes:
- User stories
- Acceptance criteria
- Balancing parameters
- Edge cases
Excludes:
- Full game vision (→GDD)
- Implementation plan (→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)
- Phase 4 Quality Assurance Phase (required)
- Progress records (checkbox format)
Excludes:
- Technical rationale (→ADR)
- Design details (→Design Doc)
Phase Division Criteria:
- Phase 1: Foundation Implementation - Contract definitions, interfaces/signatures, test preparation
- Phase 2: Core Feature Implementation - Business logic, unit tests
- Phase 3: Integration Implementation - External connections, presentation layer
- Phase 4: Quality Assurance (Required) - Acceptance criteria achievement, all tests passing, quality checks
Three Elements of Task Completion Definition:
- Implementation Complete: Code is functional
- Quality Complete: Tests, static checks, linting pass
- Integration Complete: Verified connection with other components
Creation Process
- Problem Analysis: Change scale assessment, ADR condition check
- ADR Option Consideration (ADR only): Compare 3+ options, specify trade-offs
- Creation: Use templates, include measurable conditions
- 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):
| 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
- At creation: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
- When missing: Consider creating necessary common ADRs
- Design Doc: Specify common ADRs in "Prerequisite ADRs" section
- Compliance check: Verify design aligns with common ADR decisions
