# Documentation And Adrs > Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase. Use when this capability is needed. - Skill: `tomevault-io/documentation-and-adrs-16` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/documentation-and-adrs-16` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-and-adrs-16/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/documentation-and-adrs-16 --- # Documentation and ADRs ## Per-Slice Mandate Update PRD, SPEC, and/or ADR **in the same commit** as the code change. Not after the PR merges, not in a follow-up -- in the same commit. ## ADR Status Lifecycle `PROPOSED` -> `ACCEPTED` -> `SUPERSEDED` | `DEPRECATED` Don't delete old ADRs. When a decision changes, write a new ADR that references and supersedes the old one. ## Common Rationalizations | Rationalization | Reality | |---|---| | "The code is the documentation" | Code describes what was built; PRD/SPEC/ADR describes why, what was decided, and what was rejected. Code does not replace decisions. | | "I'll update the docs after the PR is merged" | After merge, no one remembers the trade-offs. The docs update must happen in the same slice commit. | | "The SPEC is a draft, I'll formalize it when the feature is done" | The SPEC is the contract. If not updated as you implement, it drifts from code and becomes misleading for the next session. | --- > Source: [jota-batuta/batuta-agent-skills](https://github.com/jota-batuta/batuta-agent-skills) — distributed by [TomeVault](https://tomevault.io).