documentation-criteria

name	documentation-criteria
description	Determines which PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires and where each is stored. Use when deciding documentation scope or creating or reviewing a technical document.

Documentation Creation Criteria

This skill owns document routing: which durable decisions the change needs to record and where each document lives. Each template linked from Storage Locations owns the document's content and structural requirements.

What Each Document Fixes

• PRD — Fixes the business outcome, current requirements, exclusions, and acceptance criteria that later work traces to. Its AC IDs are stable traceability keys for design and verification. Implementation design belongs in the Design Doc, technical option selection in an ADR, and task order in the Work Plan.
• ADR — Fixes one durable technical choice and the materially distinct options it beat, allowing later work to distinguish an accepted decision from an incidental implementation. Complete implementation design belongs in the Design Doc.
• UI Spec — Fixes screen structure, transitions, component and state contracts, interactions, and visual acceptance before implementation. Create one only while those decisions remain open; reuse an approved UI Spec or proceed to the Design Doc when representative repository evidence already determines them.
• Design Doc — Fixes the complete implementation design for the confirmed scope: responsibilities, flows, contracts, change impact, and verification boundaries. Implementation treats approved design decisions as read-only authority.
• Work Plan — Fixes dependency order, task boundaries, executable verification, and the earliest useful proof point. It references design details instead of reproducing them.
• Task File — Carries one executable Work Plan outcome, its governing sources, investigation starting points, write responsibility, and observable verification into implementation.

Creation Decision Matrix

Structural Scale	Base Documents	Creation Order
Small	None	Direct implementation
Medium	Design Doc, Work Plan	Design Doc -> Work Plan
Large	PRD, Design Doc, Work Plan	PRD -> Design Doc -> Work Plan

Add a UI Spec before the Design Doc for frontend/fullstack work when its decisions remain open. Complete any qualifying ADR batch before the Design Doc. A qualifying ADR raises the scale to Medium at minimum.

For a Large change, satisfy the PRD requirement by creating a new PRD, updating the relevant PRD, or creating a reverse PRD when no current product document exists. At any scale, update an existing PRD when the product scope changes.

Structural Scale

Classify decision burden rather than repository layout. File count is supporting evidence only.

Scale	Decision burden
Small	One coherent outcome, one evident repository-supported implementation within one responsibility boundary, and no unresolved durable choice
Medium	One coherent outcome that coordinates a boundary or contains a potentially durable choice
Large	Multiple independently valuable outcomes that require separate design decisions

A cross-layer implementation can remain Medium when it serves one coherent outcome.

ADR Decision Filters

Apply the Choice filter, then the Durability filter, to each technical topic inside the confirmed implementation scope. Check accepted ADRs before creating another record.

1. Choice requires judgment — confirmed requirements, accepted decisions, and representative repository evidence leave at least two credible, materially distinct options.
2. Choice is durable — selecting among them materially changes responsibility, dependency direction, a shared contract, persistence, technology, reversibility, or lifecycle cost that future work must preserve or understand.

Create one ADR for each topic that passes both filters and review the complete batch together. Group choices that must be selected or reconsidered together; separate independently revisitable decisions. Local implementation details and other cheaply reversible choices belong in the Design Doc.

Storage Locations

Document	Path	Naming Convention	Template
PRD	docs/prd/	[feature-name]-prd.md	prd-template.md
ADR	docs/adr/	ADR-[4-digits]-[title].md	adr-template.md
UI Spec	docs/ui-spec/	[feature-name]-ui-spec.md	ui-spec-template.md
UI Spec Assets	docs/ui-spec/assets/{feature-name}/	Prototype code files	-
Design Doc	docs/design/	[feature-name]-design.md	design-template.md
Work Plan	docs/plans/	YYYYMMDD-{type}-{description}.md	plan-template.md
Task File	docs/plans/tasks/	See the task-decomposer filename table	task-template.md

Work Plans are excluded by .gitignore.

References

Each template defines its document's content, status rules, required evidence, optional diagrams, and completion checks. Load only the template for the document being created or reviewed.