novox/hq

Files

T

jschoubben 3f6d939930 Every decision is a record; the ledger is gone

papa-hq has no ledger. Its root is AGENTS.md, CLAUDE.md, README.md, every
decision is a numbered record, and its graduation playbook has no path for
an unrecorded decision. hal-hq now matches.

The ledger's 41 entries classified as: 10 restating a record, 11 restating
design docs, 15 describing how this repository works with the reasoning
sitting in a README rather than anywhere citable, 3 small rules with no
home, 2 superseded stubs. Mostly a copy — and a hand-maintained index, the
exact pattern ADR 0022 had just rejected for the decision index on the
grounds it drifted after one addition. Keeping one copy of that while
removing another is not a position. It also collided by name with
02-DECISIONS/ in any directory listing.

Nothing was dropped. Records 0019-0025 give the repository decisions the
reasoning they never had: HQ is its own repository and is public, design
has two layers, work moves through playbooks, status lives in frontmatter,
issues have a front door, the numbering is the flow, HQ is the source of
the constitution. 0026 records the ledger's own removal.

The three orphan rules went to how-we-build, where a rule is enforced and
keeps the incident that earned it — the package rule was genuinely
unwritten anywhere. Two lab decisions stated only in the ledger went into
the lab design. "Deliberately not decided" went to the research effort and
design document each question actually belongs to.

The chronological view the ledger provided is now generated from record
frontmatter, which is what it was for.

The cost, stated in 0026 rather than glossed: a record is more work than a
table row, so the risk is a small decision going unrecorded because nobody
wanted to write a document. how-we-build takes rules cheaply, which is the
mitigation, not a solution.

2026-08-23 18:17:59 +02:00

2.0 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.

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.0 KiB Raw Blame History