From 966e0076133eb54fde5e5b7ed49d45173df0e970 Mon Sep 17 00:00:00 2001 From: santidev21 Date: Wed, 30 Sep 2026 15:53:46 -0500 Subject: [PATCH] docs: add ADR home and a documentation policy - Add docs/adr/ for one-file decisions - Add Documentation Policy to AGENTS.md; forbid phase reports and progress logs --- AGENTS.md | 12 ++++++++++++ docs/adr/README.md | 9 +++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/adr/README.md diff --git a/AGENTS.md b/AGENTS.md index 33de5fb..82b4b6b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,8 +56,20 @@ docs/TECHNICAL-DESIGN.md docs/BACKUPS.md # backup, verification and restore runbook docs/DEPLOYMENT.md # deploy, rollback and operations docs/HANDOFF.md # next task prompt and backlog +docs/adr/ # one file per irreversible decision ``` +## Documentation Policy + +Docs capture decisions and current state, never session narration. + +- **Allowed:** this file, `README`, `docs/TECHNICAL-DESIGN.md`, `docs/adr/NNN-*.md` (one decision: + context, options, decision, consequences), the runbooks (`BACKUPS`, `DEPLOYMENT`) and + `docs/HANDOFF.md`. +- **Forbidden:** phase reports, progress logs, "what I did" narration and per-session summaries. + When a change needs a durable record, update the design doc or add an ADR — do not create a + report file. This applies to AI output too. + ## Commands | Task | Command | diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..cd85033 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,9 @@ +# Architecture Decision Records + +One file per irreversible or costly decision: `NNN-title.md` with **Context**, **Options**, +**Decision** and **Consequences**. Written by the human, in a few paragraphs — not generated as a +report. + +Use an ADR when a choice is hard to reverse or future-you needs the *why* (money as `long`, money +in exact pesos, ownership enforced twice, history indestructible). For everyday changes, update the +relevant [spec](../specs/) and the code instead.