shinpr/claude-code-workflows / dev-skills/skills/documentation-criteria
documentation-criteria
VerifiedDetermines which of PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires, and where each is stored. Use when deciding documentation scope, or when creating or reviewing a technical document.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| references/adr-template.md | markdown | 3.1 KB |
| references/design-template.md | markdown | 19.8 KB |
| references/plan-template.md | markdown | 2.3 KB |
| references/prd-template.md | markdown | 4.7 KB |
| references/task-template.md | markdown | 1.8 KB |
| references/ui-spec-template.md | markdown | 8.8 KB |
references/design-template.md
View on GitHub# [Feature Name] Design Document
## Overview
[Explain the purpose and overview of this feature in 2-3 sentences]
### Referenced UI Spec (when applicable)
- UI Spec path: [docs/ui-spec/xxx-ui-spec.md]
- Component structure and state design are inherited from UI Spec
## Background and Context
### Prerequisite ADRs
List the accepted ADRs that govern the changed responsibility, including accepted common (cross-cutting) ADRs, and verify this design aligns with each recorded decision.
- [docs/adr/ADR-XXXX.md]: [Related decision items]
- Reference common technical ADRs when applicable
### External Resources Used
Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table.
| Resource (project-tier label) | Feature-specific identifier | Notes |
|-------------------------------|-----------------------------|-------|
| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] |
### Requirement Convergence
Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context.
- **Outcome**: [one observable result this change must produce]
- **Non-Goals**: [capability the user excluded | None — user confirmed there are none]
- **Open questions**: [field the user left as weak-but-explicit | None]
### Standards and Assumptions
#### Applicable Standards
- [ ] [Standard/convention] `[explicit]` - Source: [config / rule file / documentation path]
- [ ] [Observed pattern] `[implicit]` - Evidence: [file paths] - Confirmed: [Yes/No]
#### Assumed Behaviors
Behavioral or factual claims the design relies on (framework/library defaults, capabilities assumed already provided, features assumed already implemented). Each claim carries evidence. Before verification, use `Confirmed: No` for a specific unresolved premise and state the exact evidence needed and its design effect. A premise that can change the Selected Design must be resolved before approval. After verification, `Confirmed: No` is valid only for residual implementation uncertainty whose possible outcomes leave the Selected Design valid, with a matching Risks and Mitigation row that restates the claim as its Risk and names how it will be verified or guarded. Mark the subsection N/A when the design relies on no such claims.
- [ ] [Claim — e.g., "framework X defaults to Y", "service already returns Z"] - Evidence: [file:line / command output / doc URL / exact evidence needed] - Design effect: [what changes if false | Selected Design remains valid] - Confirmed: [Yes/No]
#### Bounded Self-Verification Evidence (when applied)
Include only when a fresh review-triggered design update executed a capability probe. Keep the durable record compact; raw logs and temporary artifacts are discarded during probe cleanup.
| Applied finding | Premise | Method and observed boundary | Observation | Limitation | Design effect |
|---|---|---|---|---|---|
| [finding ID] | [exact premise] | [bounded method and consumer-visible postcondition] | [observed result] | [remaining limitation that constrains the design effect, or None] | [Selected Design change or confirmation] |
#### Quality Assurance Mechanisms
How quality is enforced in the change area. Each item is either adopted (will be enforced during implementation) or noted (observed but not adopted, with reason).
- [ ] [Tool/check name] — Enforces: [what] — Config: [path] — Covers: [file paths/patterns, or "project-wide"] — Status: `adopted` / `noted (reason)`
- [ ] [Domain-specific constraint] — Enforces: [what] — Source: [path] — Covers: [file paths/patterns, or "project-wide"] — Status: `adopted` / `noted (reason)`
### Problem to Solve
[Specific problems or challenges this feature aims to address]
### Current Challenges
[Current system issues or limitations]
### Requirements
#### Functional Requirements
- [List mandatory functional requirements]
#### Non-Functional Requirements
- **[Quality attribute]**: [level] - Source: [requirement that states it | selected in Design Convergence because the requirements leave it unset]
## Acceptance Criteria (AC) - EARS Format
Each AC is written in EARS (Easy Approach to Requirements Syntax) format.
Keywords determine test type and reduce ambiguity.
**EARS Keywords**:
| Keyword | Usage | Test Type |
|---------|-------|-----------|
| **When** | Event-triggered behavior | Event-driven test |
| **While** | State-dependent behavior | State condition test |
| **If-then** | Conditional behavior | Branch coverage test |
| (none) | Ubiquitous behavior | Basic functionality test |
**Format**: `[Keyword] <trigger/condition>, the system shall <expected behavior>`
The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement.
Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless a requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs.
### [Functional Requirement 1]
- [ ] **When** [accepted trigger occurs], the system shall [observable result]
- [ ] **If** [accepted condition holds], **then** the system shall [observable conditional result]
- [ ] **While** [accepted state holds], the system shall [observable state-dependent result]
- [ ] (ubiquitous, no keyword) The system shall [observable invariant]
## Existing Codebase Analysis
### Implementation Path Mapping
| Type | Path | Description |
|------|------|-------------|
| Existing | src/[actual-path] | [Current implementation] |
| New | src/[planned-path] | [Planned new creation] |
### Integration Points (Include even for new implementations)
- **Integration Target**: [What to connect with]
- **Invocation Method**: [How it will be invoked]
### Code Inspection Evidence
| File/Function | Relevance |
|---------------|-----------|
| [path:function] | [similar functionality / integration point / pattern reference] |
### Fact Disposition Table
One row per codebase analysis `focusAreas` entry. This table is the single binding between existing-behavior facts and the design — other sections that describe existing behavior reference the row by Focus Area name.
| Fact ID | Focus Area | Disposition | Rationale | Evidence |
|---------|------------|-------------|-----------|----------|
| [fact_id from focusAreas] | [area name from focusAreas] | preserve / transform / remove / out-of-scope | [for transform: state new outcome; for remove: state reason; for out-of-scope: state which scope boundary excludes it; for preserve: brief confirmation] | [evidence value carried verbatim from focusAreas] |
## Design
### Change Impact Map
```yaml
Change Target: [Component/feature to change]
Direct Impact:
- [Files/functions requiring direct changes]
- [Interface change points]
Indirect Impact:
- [Data format changes]
- [Processing time changes]
No Ripple Effect:
- [Explicitly specify unaffected features]
```
### Interface Change Matrix
| Existing | New | Conversion Required | Compatibility Method |
|----------|-----|--------------------|--------------------|
| [Function/method/operation name] | [Function/method/operation name] | [Yes/No] | [Approach: adapter, wrapper, deprecation, etc.] |
### Architecture Overview
[How this feature is positioned within the overall system]
Add an architecture or data-flow Mermaid diagram only when the changed relationships stay unclear in prose or a compact table; otherwise keep the prose form.
### Data Flow
```
[Express data flow using diagrams or pseudo-code]
```
### Integration Points List
| Integration Point | Location | Old Implementation | New Implementation | Switching Method | Verification Method |
|-------------------|----------|-------------------|-------------------|------------------|-------------------|
| [Integration Point] | [Class/Function] | [Existing Process or N/A] | [New Process] | [DI/Factory/config/etc.] | [How to verify this switching works] |
### Main Components
#### [Component] (repeat per component)
- **Responsibility**: [Scope of responsibility for this component]
- **Interface**: [APIs and contract definitions provided]
- **Dependencies**: [Relationships with other components]
### Data Representation Decision (When Introducing New Structures)
| Criterion | Assessment | Reason |
|-----------|-----------|--------|
| Semantic Fit | [Yes/No] | [Does existing structure's meaning align?] |
| Responsibility Fit | [Yes/No] | [Same bounded context?] |
| Lifecycle Fit | [Yes/No] | [Same creation/mutation/deletion timing?] |
| Boundary/Interop Cost | [Low/Medium/High] | [Cost of sharing across boundaries?] |
**Decision**: [reuse / extend / new] — [rationale in 1-2 sentences]
### Selected Design
Describe the complete selected end-to-end path. Candidate paths and rejected additions remain active analysis; an accepted ADR may retain alternatives as decision history. Mark this whole section `N/A — reverse-engineer/as-is document` for a reverse-engineer/as-is document.
[Selected responsibilities, control/data flow, and use of existing system capabilities]
For each added design surface—user decision, setting, mode, concept, output, persistent state, implementation path, public contract, abstraction, service, or component split—record:
- **Addition**: [selected design surface]
- **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk]
- **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition]
- **Subtraction result**: [outcome, required boundary, or proof that becomes unmet when removed, traced to its originating requirement, accepted decision, or repository rule or contract]
Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces.
### Data Contracts
When a UI Spec states that a surface displays a value, the contract feeding that surface carries it. A field set that cannot render a specified display is incomplete, not a simplification.
#### [Component or Boundary] (repeat per component/boundary)
```yaml
Contract: [interface / function / API / schema name]
Input:
Type: [Data shape, contract, or schema]
Preconditions: [Required items, format constraints]
Validation: [Validation method]
Output:
Type: [Data shape, contract, or schema]
Guarantees: [Conditions that must always be met]
On Error: [Exception/null/default value]
Invariants:
- [Conditions that remain unchanged before and after processing]
```
### Field Propagation Map (When Fields Cross Boundaries)
A boundary here includes a **serialized boundary** — a value encoded on one side and parsed on the other through a medium such as a query string, CLI argument, environment variable, config entry, message/queue payload, storage key, or file — not only cross-process calls. For those, record the exact encoded representation and how the consumer parses it, so producer and consumer agree.
| Field | Boundary | Status | Serialized Format | Consumer Parse Rule | Detail |
|-------|----------|--------|-------------------|---------------------|--------|
| [field name] | [Component A → B] | preserved / transformed / dropped | [exact representation the producer emits when the boundary is serialized; "—" otherwise] | [how the consumer decodes and validates that representation; "—" when not serialized] | [logic or reason] |
### State Transitions and Invariants (When Applicable)
```yaml
State Definition:
- Initial State: [Initial values and conditions]
- Possible States: [List of states]
State Transitions:
Current State → Event → Next State
System Invariants:
- [Conditions that hold in any state]
```
### UI Error State Design (when feature includes frontend)
| Component / Screen | Loading | Empty | Error | Partial |
|-------------------|---------|-------|-------|---------|
| [Component name] | [Skeleton / spinner] | [Empty state + CTA] | [Error message + Retry] | [Cached display + Banner] |
### Client State Design (when feature includes frontend)
| State Category | State | Management Method | Sync Strategy | Reset/Clear Behavior |
|---------------|-------|-------------------|---------------|----------------------|
| Server state | [Fetched data] | [Cache library / custom hook] | [Polling / WebSocket / manual refresh] | [Cleared on clear-all / preserved] |
| Local UI state | [Modal open, tab selection] | [useState / useReducer] | - | [Reset to default / preserved] |
| Temporary state | [Form input, draft] | [useState / form library] | [Auto-save / manual save] | [Cleared on reset / persisted] |
Fill the Reset/Clear Behavior column when the feature has a reset or clear-all operation. A state that must return to its unused/default value on reset is a state-lifecycle negative (an observable contract: the state stays unused after reset) — record it so it is verified rather than assumed.
### UI Action - API Contract Mapping (when feature includes frontend)
| UI Action | API Endpoint | Request | Response | Error Contract |
|-----------|-------------|---------|----------|----------------|
| [Button click / form submit] | [POST /api/xxx] | [Request body fields] | [Response fields] | [Error codes and UI handling] |
### Error Handling
| Error Category | Example | Detection | Recovery Strategy | User Impact |
|---------------|---------|-----------|-------------------|-------------|
| [Validation / External / Infrastructure / Business logic] | [Specific error] | [How detected] | [Retry / Fallback / Propagate / Log-and-continue] | [User-facing message or silent handling] |
### Logging and Monitoring
Include this section only when the feature changes an observable operational boundary or an accepted requirement/project policy requires diagnostics, metrics, or alerts.
- **Log events**: [Key events to log: state transitions, external calls, error occurrences, performance thresholds]
- **Log levels**: [Which events at DEBUG/INFO/WARN/ERROR]
- **Sensitive data**: [Fields to mask or exclude — coordinate with Security Considerations]
- **Monitoring**: [Metrics to track, alert thresholds, dashboard requirements]
## Implementation Plan
### Implementation Approach
**Selected Approach**: [Approach name or combination]
**Selection Reason**: [Reason considering project constraints and technical dependencies]
### Technical Dependencies and Implementation Order
#### Required Implementation Order (in dependency order, one entry per component/feature)
1. **[Component/Feature]**
- Technical Reason: [Why this needs to be implemented at this position]
- Prerequisites / Dependent Elements: [Components depended on or that depend on this]
### Migration Strategy
[Technical migration approach, ensuring backward compatibility]
## Security Considerations
Evaluate the following for this feature's trust boundaries and data flow:
- **Authentication & Authorization**: What authentication is required for new entry points? What authorization checks protect resource access?
- **Input Validation**: Where does external input enter the system? How is it validated before processing?
- **Sensitive Data Handling**: What data requires protection (encryption, masking, access control)? What data is safe to include in logs and error responses?
Mark items as N/A with brief rationale when the feature has no relevant trust boundary.
## Test Boundaries
### Mock Boundary Decisions
| Component/Dependency | Mock? | Rationale |
|---------------------|-------|-----------|
| [External API / DB / File system / etc.] | [Yes/No] | [Why this boundary was chosen] |
### Data Layer Testing Strategy
- **Schema dependencies**: [List tables/models this feature reads from or writes to, with paths to their definitions]
- **Test data approach**: [How test data is provided — fixtures, factories, seed scripts, or real database]
- **Mock limitations acknowledged**: [What cannot be reliably tested with mocks alone for this feature]
Mark as N/A with brief rationale when the feature has no data layer dependencies.
### Integration Verification Points
- [List critical integration points that require testing beyond unit-level mocks]
## Verification Strategy
Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 levels (L1: functional operation works as end-user feature; L2: tests that prove the changed behavior pass; L3: build succeeds without errors) define completion verification granularity at task execution time.
### Correctness Proof Method
- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "generated queries execute without error on target DB"]
- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "contract test with real API"]
- **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"]
### Early Verification Point
- **First verification target**: [The smallest unit that proves the approach works — e.g., "first repository migration", "single API endpoint", "one screen flow"]
- **Success criteria**: [Observable outcome — e.g., "CSV download produces identical output to legacy", "API returns 200 with expected schema"]
- **Failure response**: [What to do if early verification fails — e.g., "reassess approach before proceeding", "return to the governing decision gate"]
### Output Comparison (When Replacing or Modifying Existing Behavior)
How will behavioral equivalence be verified between existing and new implementation?
- **Comparison input**: [Identical input used for both implementations — e.g., "same DB snapshot", "same API request payload"]
- **Expected output fields**: [Specific fields/columns to compare — e.g., "all output columns", "response body fields: id, status, amount"]
- **Diff method**: [How to compare — e.g., "file-level diff", "JSON field-by-field comparison", "row count + spot check"]
- **Transformation pipeline coverage**: [Each step from codebase analysis `dataTransformationPipelines` and what the comparison covers]
Mark as N/A with brief rationale when the design introduces entirely new behavior with no existing equivalent.
## Design Boundaries
Record boundaries needed by a current requirement, downstream implementation, or verification. This section contains selected design boundaries rather than discovered candidates or unselected future possibilities.
- **Intentional limitations**: [Current behavior or responsibility deliberately kept outside the selected design, with the governing scope reason]
- **Existing extension points used**: [Interfaces or hooks the selected design uses, with each named current consumer | None]
## Risks and Mitigation
Include only evidenced residual risks that can change rollback, contract handling, or verification strategy while leaving the Selected Design valid.
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High/Medium/Low | High/Medium/Low | [Countermeasure] |
## References
- [Related documentation and links]
## Update History
| Date | Version | Changes | Author |
|------|---------|---------|--------|
| YYYY-MM-DD | 1.0 | Initial version | [Name] |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |