From c702f11b6f18a1ab1a68b63511b7352c7e530ce5 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Thu, 23 Jul 2026 22:52:46 +0200 Subject: [PATCH] docs(product-engineering): standardize ADR and as-is conventions --- product-engineering/SKILL.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/product-engineering/SKILL.md b/product-engineering/SKILL.md index aa507d5..86af6ea 100644 --- a/product-engineering/SKILL.md +++ b/product-engineering/SKILL.md @@ -79,7 +79,9 @@ Issues are the unit of advance work — this is where new work enters the queue. already exists, drive *that* to merge per the **Trust gate** instead of duplicating. 2. **Implement at the root cause, with tests.** Work in an isolated per-run working copy. Tests that pin the new behaviour and its edge cases are part of the change, not optional. For a non-trivial - design, write or extend a design note/ADR first and link it. + design, write or extend a design note/ADR first and link it. In a repository that uses ADRs, + every ADR lives under **`docs/adr/`**; do not create or keep ADRs in another folder. This rule does + not require a repository without ADRs to introduce them. 3. **Feature-flag-first for non-trivial features.** Build every new non-trivial feature behind a flag, **default-off, tested in both states**; flip it on only after validation, as a separate, reversible step. Use the standard, tool-neutral flag mechanism the product's **Portfolio map** @@ -136,6 +138,10 @@ Docs are part of the product. - **Improve (on the docs Cadence).** Pick an under-served area and make it genuinely better: fix inaccuracies and stale examples, fill missing how-tos, tighten onboarding flow, repair dead links. Verify examples actually run. `docs:`-only PRs are real advance work, not filler. +- **Describe the as-is, never the journey.** Documentation, code comments, and resource descriptions + state the current behaviour, architecture, constraints, and rationale directly. Do not narrate how + they arrived there through prior states, migrations, before/after comparisons, or origin stories. + When history affects a current constraint, document the constraint and its present rationale. - **Agent & instruction files are docs too.** The files that steer AI tools (the canonical instructions file and any per-tool shims or path-scoped rule files) silently mislead every future agent when stale — hold them to the same same-PR definition of done, and fold a freshness pass