Drew T
3.8 KiB
docs/ — what goes where
Installed by decomp-architect (Step 4) on {{INSTALL_DATE}} for {{PROJECT_NAME}}. This folder holds the records and references the
project's wiki summarises and links; knowledge has a home by KIND, not by the session that produced it. A note written for
one session is scratch (.run/); the durable result it produced goes into one of the files below, and the note is archived.
| Kind of knowledge | Where it goes | The rule behind it |
|---|---|---|
| A compiler idiom proven on the bytes (the residual, the mechanism, the lever, the byte proof) | a numbered section of the cookbook, and its symptom index (regenerated by a tool, never edited) | the flywheel: consult before a match, feed back after |
| A strategic pivot: what was believed, what failed, the measurement, the hindsight | an entry in docs/decision-log.md, written while fresh |
capture the why while it hurts |
| A late discovery that would have sped up an earlier phase — what it is, when it was found, when it could have been found, what it would have saved | docs/accelerators.md |
the ledger a future project starts from |
| A procedure people run (the wave, the publication) | a runbook under docs/; a superseded runbook carries a banner at the top and is then archived |
one runbook is the procedure |
| An environment or tool fact (a version, a flag, a hook, a row per tool) | docs/ops-setup.md, in the same change as the tool |
keep the ops reference current |
| An address, with its source and its verification status | docs/memory-map.md |
address provenance and region tags |
| A file or container format | docs/formats.md (the medium's layout: {{CONTAINER_LAYOUT}}) |
— |
| The state of the open phase; then the phase's synthesis; then the one-page digest every session starts from | phase-ends/CURRENT_PHASE.md → phase-ends/PhaseEnd_Phase<N>.md → phase-ends/DIGEST.md |
the replayable checkpoint; the digest |
| How the project is used: building, verifying, contributing, its layout and conventions | the wiki (docs/wiki/), the source of truth for documentation |
— |
| A design note, a frontier analysis, a triage ladder, a worklist for one session | .run/<session>/ while live; once its result is in the record above, the note moves to the archive — it is never a reference |
see the archive |
Authored versus generated. Numbers are generated, never typed: every progress figure, badge, timeline row and census in a published document is produced by a tool from the tree, and the tool asserts the published copy is fresh; a generated file says so on its first line; edits go to the generator. A number that has to appear in prose is a dated snapshot with the command that produced it. Snapshots of a state that no longer exists are frozen, not regenerated.
Placeholders. A tracked document never pastes a literal double-brace placeholder token; it names the placeholder in prose. The install-time placeholder audit cannot tell a quotation from an unfilled placeholder, and it must stay a true signal.
Links. A document links the wiki page for a topic, not the docs/ file behind it; a wiki page links into docs/ only
through its Reference index; nothing links into the archive (docs/sunset/), whose index names files as backticked paths
with the version they were archived at. A backticked path is a citation, not a link; a link checker classifies cited
paths as TRACKED or UNTRACKED by asking git, never the disk.
The archive. A document leaves docs/ when its purpose is fulfilled and its information lives elsewhere: git mv into
docs/sunset/ under the same relative path, one row in the archive index (what it was, what came of it, where it lives
now), and a review row for the owner; deletion is the owner's decision, never part of the move; every referrer is
re-pointed first (a git grep over the tree must return only the two index files).