Development record
2026-11-01 — ADOPTED (product thinker, 2026-11-01): abcd-managed repositories move to documentation that holds no prose of its own. What people write lives in the design record (the brief, what the product is and why, its users and roles, with its principles) or the how (how-to guides, and optionally tutorials, exercises and video), and everything else is generated from code and release facts. The rule binds a page section by section as abcd comes to render it; until then a repository's hand-written prose stays where it is. A hand edit to a rendered page is caught and offered back to its source rather than overwritten. Grounds: every-claim-has-one-home already rules a second copy out for the record, and abcd's own README drifted from the brief it restates; two state-of-the-art reviews (2026-11-01) supported explanation in the design record, generated reference, tested how-to and tutorial pages, and one site with separate owners. Recorded in itd-2611011151475128, itd-2611011151512956, itd-2611011239589823 and adr-2611011153058085 (proposed). Reverse by a later decision that names this one; the drafts carry the open questions (rendered or held, where the how lives) that planning settles.
2026-11-01 — ADOPTED (product thinker, 2026-11-01): abcd-managed repositories move to documentation that holds no prose of its own. What people write lives in the design record (the brief, what the product is and why, its users and roles, with its principles) or the how (how-to guides, and optionally tutorials, exercises and video), and everything else is generated from code and release facts. The rule binds a page section by section as abcd comes to render it; until then a repository's hand-written prose stays where it is. A hand edit to a rendered page is caught and offered back to its source rather than overwritten. Grounds: every-claim-has-one-home already rules a second copy out for the record, and abcd's own README drifted from the brief it restates; two state-of-the-art reviews (2026-11-01) supported explanation in the design record, generated reference, tested how-to and tutorial pages, and one site with separate owners. Recorded in itd-2611011151475128, itd-2611011151512956, itd-2611011239589823 and adr-2611011153058085 (proposed). Reverse by a later decision that names this one; the drafts carry the open questions (rendered or held, where the how lives) that planning settles.
Frontmatter
| id | dcn-2611011248594647 |
|---|---|
| type | decision |
| date | 2026-11-01 |
.abcd/work/decisions/dcn-2611011248594647-adopted-product-thinker-2026-11-01-no.md
open on GitHub ↗ · commit history ↗
mentions5
- adr-2611011153058085A re-render never discards hand-written text unasked
- dcn-26110115512169582026-11-01 — ADOPTED (product thinker, 2026-11-01), refining dcn-2611011248594647 and setting the stages of its section-by-section rule: (1) the sections derived from the repository's facts (install, requirements, first run, citation, badges, licence, links, contents) render now; (2) the brief-sourced sections become compulsory in abcd-managed repositories once the brief has an editing surface, because from then the owner's words live in the brief; (3) the text the README opens with is written by the product thinker; (4) the scope is the README and every page under docs/; (5) the how is optional per repository and, where it exists, holds how-to guides owned by the product team and learning material (tutorials, exercises, video) that educators and trainers may own, in the same repository, site and toolchain, kept current by tests; (6) every change that alters behaviour records a docs-impact state (needed, done, not needed) and the release cut refuses while a needed update is open, binding once the intent that carries it ships (it is open in itd-2611011239589823 where the state is recorded and which changes count); (7) editing for non-engineers starts with the forge's own editor and previews. Grounds: the product thinker's rulings in the planning conversation of 2026-11-01 and their confirmation of the routing table that day. Whether the reversal of itd-2610031348087517 stands is confirmed at the intents' planning interview. Reverse by a later decision naming this one.
- itd-2611011151475128Every documentation surface is rendered from its one home
- itd-2611011151512956Hand-written text in a rendered page is caught and offered back to its source
- itd-2611011239589823A project's how-to guides and learning material stay current with the product