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

1.9 KiB

Raw Blame History

Playbook 01 — Research

Trigger. An idea, technology or approach worth investigating before it is committed to design. Also: an as-is document that raises a question nobody can answer.

Who runs it. Anyone.

Steps

Take the next free number: highest 01-RESEARCH/NNN-* plus one, zero-padded to three digits. Never skip or reuse a number.
Create 01-RESEARCH/NNN-descriptive-name/ and a 00-overview.md in it carrying:
```
---
status: active
initiated: YYYY-MM-DD
touches: []          # areas, subsystems or as-is design docs the effort bears on
---
```
Then a short prose summary: what is being investigated, why, and what it touches.
Do the research in further documents in the same folder — notes, option analyses, evidence, draft designs. Anything goes. Keep the summary in 00-overview.md current as the effort changes shape.

What makes research worth reading

State evidence, not assertion. "Zero of 124 modules declare brain as a dependency" outranks "the dependency rule is not followed". An effort that measured nothing has not finished.

Research describes real observations but never identifies the mesh it observed. The shape of a finding survives anonymisation intact — a node publicly named but behind a household NAT carries the whole lesson without naming anything.

Do not

Do not put status in prose. It lives in 00-overview.md's frontmatter, and the prose must not restate it.
Do not set became: while the effort is open — playbook 02 sets it at closure.
Do not write into 03-DESIGN from an open effort.

Closing

An effort never just stops. It closes through playbook 02 as graduated or abandoned, always with became: pointing at what it turned into. Nothing is deleted — what was rejected, and why, is the more expensive half to rediscover.

1.9 KiB Raw Blame History