documentation-criteria

# Documentation Creation Criteria ## Creation Decision Matrix | Structural Scale | Required Documents | Creation Order | |------------------|--------------------|----------------| | Small | None | Direct task execution | | Medium | Design Doc → Work Plan | Start with Design Doc | | Large | PRD → Design Doc → Work Plan | Continue after PRD approval | Insert an ADR immediately before the Design Doc only when a current-scope decision passes both ADR filters below. A qualifying ADR decision sets the scale floor to Medium. ## Structural Scale Classify the decision burden, not repository layout. File count is supporting evidence only. | Scale | Structural condition | |-------|----------------------| | Small | One coherent outcome follows existing patterns within one responsibility boundary | | Medium | One coherent outcome coordinates across a boundary or requires a durable design decision | | Large | Multiple independently valuable outcomes require separate design decisions | Multiple files or layers that serve one coherent outcome remain Medium. Large applies only when separate outcomes require separate design decisions. ## ADR Creation Conditions Check accepted ADRs that govern the changed responsibility, then apply both filters to each technical topic in the confirmed scope: 1. **Choice requires judgment**: Current requirements, accepted decisions, and representative repository patterns support at least two credible, materially distinct options. 2. **Decision is durable**: The choice materially changes a responsibility, dependency direction, shared contract, persistence model, technology dependency, reversibility, or lifecycle cost that future work must preserve. Create one ADR for each topic that passes both filters. Keep a topic in the Design Doc when one repository-supported implementation is evident or the choice remains cheaply reversible. Qualifying durable choices can include: - introducing or replacing a technology, platform, storage model, or external dependency; - changing ownership, dependency direction, a trust boundary, or a shared public contract when credible alternatives exist; - reversing or superseding an accepted architecture decision; - selecting an irreversible or high-cost compatibility or data migration strategy. Counts of files, consumers, nesting levels, states, or processing steps do not independently require an ADR. ## What Each Document Fixes Create an artifact only when its downstream consumer would otherwise need to infer the named decision. | Document | Decision it fixes | Consumer effect when missing | |----------|-------------------|------------------------------| | PRD | Product outcome, current requirements, acceptance criteria, and exclusions | Design would have to infer product scope | | ADR | One qualifying durable technical choice and the alternatives it resolves | Design and future changes could not distinguish an accepted decision from a local choice | | Design Doc | Repository-grounded implementation approach, contracts, change surface, and verification strategy | Planning and implementation would make design decisions locally | | Work Plan | Implementation order, real dependencies, and executable verification | Execution would choose sequencing and proof boundaries locally | ## Document Boundaries ### PRD Include product outcome, current requirements, success criteria, user-visible scope, exclusions, and unresolved product decisions. Keep technical implementation choices in the Design Doc or ADR. ### ADR Include the durable choice, materially distinct options, trade-offs, decision, consequences, and reversal conditions. Evaluate the number of options established by evidence; do not manufacture alternatives to satisfy a fixed count. ### Design Doc Include only information that constrains implementation or verification: - confirmed outcome and non-goals; - relevant existing code and accepted decisions; - selected implementation approach and contracts; - affected responsibility boundaries and integration points; - acceptance criteria and the narrowest sufficient verification strategy; - material risks, unknowns, and decisions deferred to implementation. Add a change-impact map, field-propagation map, API matrix, or diagram when the relationship would otherwise be difficult for the next consumer to reconstruct. ### Work Plan Include the fewest implementation units needed to preserve real dependencies and observable proof. Each task names its source, intended result, scope, dependencies, and verification. ## Creation Process 1. Confirm the outcome, current requirements, and non-goals. 2. Determine Structural Scale from repository evidence. 3. Apply the ADR choice and durability filters. 4. Create only the documents selected by the decision matrix. 5. Obtain approval for product requirements and major durable design decisions before they authorize implementation. ## Storage Locations | Document | Path | Naming Convention | |----------|------|-------------------| | PRD | `docs/prd/` | `[feature-name]-prd.md` | | ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | | Design Doc | `docs/design/` | `[feature-name]-design.md` | | Work Plan | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | Work Plans are transient execution state and remain excluded by `.gitignore` unless the repository explicitly chooses to version them. ## ADR Status `Proposed` → `Accepted` → `Deprecated` / `Superseded` / `Rejected` When a new ADR supersedes an accepted ADR, retain the old ADR, mark it `Superseded` with a reference to the new ADR, and add a reference to the old ADR in the new ADR. ## Quality Check - Every document serves a named downstream consumer. - Every retained section changes a decision, protects a boundary, or supplies necessary proof. - Repository observations, inferences, and unknowns are distinguishable. - Reuse and no-document outcomes remain valid when evidence supports them.