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.1 KiB

Raw Blame History

name, description

name	description
hal-graduate	Use when a hal-hq research effort concludes and becomes design, or when a design must change. Triggers on "graduate this research", "this is decided", "write the ADR", "close the effort", "the design changed".

hal-graduate

Closes a research effort into a decision and a design, or amends an existing design. Authoritative playbook: 00-META/process/02-graduation.md — read it; this skill adds only the scaffolding.

Steps

Check against GENESIS — mission.md, context.md, effect.md. If the conclusion conflicts, say which is wrong, in writing, before proceeding.
Write the decision record in 02-DECISIONS/, next free number, frontmatter per 02-DECISIONS/README.md. reconstructed: false — this one is being taken, not recovered. Record the rejected options.
Write the design under 03-DESIGN/01-to-be/ with layer: to-be, status: designed, empty code:, today's updated:, and decisions: pointing at the record.
Close the effort — the research 00-overview.md gets status: graduated and became: pointing at both.
Add the ledger line to DECISIONS.md under today's heading.

Amending an existing design

A design changes only through a decision. Write the record first; if it reverses an earlier one, set that record's status: superseded and superseded-by: — never edit its text. Then edit the design and set updated:.

When something ships

Write or update the matching 03-DESIGN/00-as-is/ document so it describes what now runs, including anything that shipped differently from the intent. Set the to-be document's status: implemented and its code:. The to-be document does not move — both stand.

status: implemented must be defensible from the owning repository's main branch. If it cannot be checked, it is in-progress.

Do not

Do not move a to-be document into 00-as-is/.
Do not edit an as-is document to describe an intention.
Do not change a decision record's meaning. Supersede it.

2.1 KiB Raw Blame History