Skip to content

shinpr/claude-code-workflows / dev-skills/skills/documentation-criteria

documentation-criteria

Verified

Determines 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.

references/adr-template.md

View on GitHub
# [ADR Number] [Title]

## Status

[Proposed | Accepted | Deprecated | Superseded | Rejected]

A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`.

`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the outcome, desired-future requirements, and non-goals remain true.

## Context

[Describe the background and reasons why this decision is needed. Include the essence of the problem, current challenges, and constraints]

## Decision Point

- **Question**: [The technical choice requiring comparison and selection]
- **Why a decision exists**: [Evidence for at least two credible, materially distinct options]
- **Scope boundary**: [Requirement or existing contract this decision serves]

## Decision

[Describe the actual decision made. Aim for specific and clear descriptions]

### Decision Details

| Item | Content |
|------|---------|
| **Decision** | [The decision in one sentence] |
| **Why this** | [Why this option over alternatives (1-3 lines)] |
| **Known unknowns** | [Uncertainty that changes implementation or verification; otherwise N/A] |
| **Reconsider when** | [Observable condition that changes the option comparison; otherwise N/A] |

## Rationale

[Explain why this decision was made and why it is the best option compared to alternatives]

### Options Considered

Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below.

| Option | Product value from the requirements | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility |
|--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------|
| [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] |
| [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] |

**Selected**: [The smallest sufficient option whose total complexity is justified by product value from the requirements and repository evidence]

## Consequences

### Positive Consequences

- [List positive impacts on the project or system]

### Negative Consequences

- [List negative impacts or trade-offs that need to be accepted]

### Neutral Consequences

[List decision-relevant neutral changes, or N/A]

## Architecture Impact

[Describe how this decision affects existing architecture: (1) components that change, (2) new dependencies introduced, (3) architectural constraints added or removed]

## Related Information

- [Links to related ADRs, documents, issues, PRs, etc.]
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall