Skip to content

docs(product-engineering): standardize ADR and as-is conventions #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
devantler merged 1 commit into from
Jul 24, 2026
Merged

docs(product-engineering): standardize ADR and as-is conventions #78

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion product-engineering/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down Expand Up @@ -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
Expand Down
Loading