documentation-and-adrs

SKILL.md

Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.

When to Use

Making a significant architectural decision

Choosing between competing approaches

Adding or changing a public API

Shipping a feature that changes user-facing behavior

Onboarding new team members (or agents) to the project

When you find yourself explaining the same thing repeatedly

When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

Architecture Decision Records (ADRs)