Documentation and ADRs

Agentit-owned adaptation. The exact MIT-licensed source and attribution remain in vendor/agent-skills/documentation-and-adrs/SKILL.md and vendor/licenses/addyosmani--agent-skills/LICENSE. The core's scope and BUILDER/REVIEW cadence govern this procedure.

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.

Document meaningful increments

At a useful milestone or once a material decision stabilizes, update the existing canonical documentation while the context is fresh. Record the problem, observable change, chosen approach and reason, relevant alternatives/trade-offs, verification/limits and next action when unfinished. A short paragraph or PR description is often enough; reserve a full ADR for consequential durable choices.