Fleshed out documentation

docs/documentation.md

@@ -0,0 +1,51 @@
+# Documentation Practices
+
+These standards aim to keep documentation reliable as the codebase grows.
+
+## Principles
+
+- Single source of truth: one canonical doc per topic; link instead of duplicating.
+- Proximity: keep docs close to the code they describe when possible.
+- Freshness: update docs in the same PR as the code change.
+- Observable behavior: describe what someone can see or run to validate the behavior.
+
+## Required Docs By Area
+
+- Architecture and major decisions: `docs/architecture.md` and `docs/adr/`.
+- Feature delivery plans: `docs/execplans/` (required by `PLANS.md`).
+- Operational procedures: `docs/runbooks/`.
+- Risks and gaps: `docs/risks.md`.
+
+## When To Write An ADR
+
+Use an ADR for any decision that is cross-cutting or hard to reverse, including:
+
+- External providers or payment/auth strategy changes.
+- Async vs synchronous execution decisions.
+- Data model changes that affect multiple apps or services.
+
+ADRs live in `docs/adr/` and use the template in `docs/templates/adr.md`.
+
+## Runbook Expectations
+
+Every production-impacting flow should have a runbook that covers:
+
+- Symptoms and impact.
+- Detection and quick checks.
+- Safe remediation steps.
+- Rollback or escalation path.
+
+Use the template in `docs/templates/runbook.md`.
+
+## Writing Style
+
+- Be explicit: include exact commands, paths, and expected output where useful.
+- Keep sections short and focused.
+- Avoid unstated assumptions; if a step needs a specific directory, say so.
+
+## Review Checklist
+
+- Docs updated or explicitly confirmed unnecessary.
+- New runbook added when operational behavior changes.
+- ADR added for new cross-cutting decisions.
+- `docs/risks.md` updated for meaningful gaps added or closed.