novox/hq

Files

T

jschoubben c0b35652d0 The numbering is the flow: decisions are 02, design is 03

papa-hq reads 01 research -> 03 decision -> 02 design. The order is a
scar, not a choice: 02-DESIGN existed from its initial commit, and when
adr/ was finally promoted on 2026-07-13 it took the next free number
rather than its place in the sequence. By then design was too settled to
renumber.

hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and
02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks
the process in the order it happens: research produces a decision, the
decision authorises a design.

00-GENESIS becomes 00-META, matching papa's rename from the same
restructure.

Every path reference rewritten across documents, frontmatter, playbooks
and skills. All links resolve; all 58 frontmatter blocks parse and their
path fields still point at files that exist.

2026-08-23 18:05:11 +02:00

2.7 KiB

Raw Blame History

Playbook 02 — Graduation and design change

Trigger. A research effort concludes, or an existing design must change.

Who runs it. Anyone, with the decision recorded before the design moves.

Graduating research

Check it against GENESIS. An effort graduates only if its conclusion is traceable to mission.md, context.md and effect.md. If it conflicts, either the effort is wrong or GENESIS is — say which, in writing, before proceeding.
Record the decision. Write a record in 02-DECISIONS/ taking the next free number. Format and rules are in 02-DECISIONS/README.md. State evidence, not assertion, and record the options that were rejected — that is the half worth keeping.

Write the design. Create the document under 03-DESIGN/01-to-be/ with frontmatter:

---
layer: to-be
status: designed
code: []             # owning code repo(s); set at build handoff, empty before
updated: YYYY-MM-DD
decisions: [02-DECISIONS/NNNN-....md]
---

Close the effort. Set the effort's 00-overview.md frontmatter to status: graduated and became: pointing at the design document and the decision record.
Add a ledger line. Append the decision to DECISIONS.md under today's heading, pointing at the record.

Amending an existing design

A design changes only through a decision.

Write the decision record. If it reverses an earlier one, the earlier record's status: becomes superseded-by: 02-DECISIONS/NNNN-....md — its text is never edited.
Edit the to-be design document and set updated: to today.
If the amendment came from an issue, set that issue's amended-design: to the document path.
Add the ledger line.

When something ships

Implementation state is a third axis, independent of both design and decision.

Write or update the matching document under 03-DESIGN/00-as-is/ so it describes what now runs — including anything that shipped differently from the intent. A design that shipped bent is an as-is fact, not a design amendment.
Set the to-be document's status: implemented and its code: to the owning repositories from repos.md.
status: implemented must be defensible from the owning repository's main branch, not from intent. If it cannot be checked, it is in-progress.

Do not

Do not move a to-be document into 00-as-is/. Write the as-is document; both stand.
Do not edit an as-is document to describe an intention. That is what the to-be layer is for.
Do not change a decision record's meaning. Supersede it.

2.7 KiB Raw Blame History