documentation-criteria_skill

Overview

This skill defines clear criteria and templates for creating PRDs, ADRs, Design Documents, and Work Plans. It helps teams decide which documents are required, in what order to create them, and where to store them. Use it to standardize document content, diagram requirements, and approval flow for production-ready changes.

How this skill works

The skill inspects change characteristics (feature scope, number of files, contract/data flow/architecture impact) against an ADR decision matrix to recommend required documents and creation order. It provides templates, mandatory sections, diagram requirements, storage paths, and automation rules (e.g., when ADRs are mandatory). It also maps required handoffs: which information belongs in PRD, ADR, Design Doc, or Work Plan.

When to use it

• Planning a new feature that affects multiple components or users
• Changing data contracts, storage, or data flow patterns
• Introducing or replacing external libraries or APIs
• Preparing implementation for work spanning 3+ files or teams
• Reviewing whether an ADR, Design Doc, or Work Plan is required

Best practices

• Run the decision matrix early: count affected files and check ADR conditions before implementation
• Keep PRD focused on business value and measurable success metrics; move technical choices to ADR/Design
• Record at least three options and trade-offs in ADRs for traceable decisions
• Include required diagrams (user journey, architecture, data flow) and measurable acceptance criteria
• Copy E2E verification procedures from the Design Doc into the Work Plan and include a required QA phase

Example use cases

• A new feature touching 6+ files triggers ADR → Design Doc → Work Plan with architecture and impact maps
• A contract responsibility change (DTO→Entity) requires an ADR to document rationale and options
• A small UI tweak touching 1-2 files proceeds directly to implementation without formal docs
• Introducing a new external API requires an ADR documenting options and a Design Doc for integration details
• Preparing a phased rollout: PRD defines MVP and success metrics, Work Plan lists phase tasks and QA checkpoints