document-haness/.agents/skills/writing-tech-log-records/references/root-tree-contract.md

Root Tree Contract

The root tree is the explicit boundary between deep project analysis and Tech Log record generation.

Required document header

A root tree records:

• schemaVersion
• project
• sourceDocument
• sourceDocumentSha256
• sourceRevision
• generatedAt

The hash/revision prevents a scheduled generator from treating a tree derived from old code as current.

Required human-readable tree

Each Topic has a title, slug, and four branches:

PROJECT
<project>

TOPIC
<Topic title>
<topic-slug>

├── CASE
├── REFERENCE
├── OPEN QUESTION
└── DECISION

Empty branches are allowed. Do not manufacture nodes to fill all four kinds.

Node source contract

Every candidate includes a specification after the human-readable tree.

Case

Required:

• slug
• readiness
• one or more source anchors
• classification explaining the concrete incident/experiment/diagnosis
• relevant code/evidence when the conclusion depends on them
• missing-verification
• relations

A Case with NEEDS_EVIDENCE, BLOCKED, or REJECTED is not generated.

Reference

Required:

• slug
• readiness
• source
• classification explaining the reusable criterion
• scope
• exceptions
• relations

A Reference must be useful beyond retelling one Case. If removing the originating project's names leaves no rule, it is probably still a Case.

Open Question

Required:

• slug
• readiness: OPEN
• source
• known
• unknown
• next-verification
• decision-criterion
• relations

Do not generate a Question when the detailed analysis already contains a verified answer. Move the material to Case/Reference/Decision as appropriate and update the tree first.

Decision

Required:

• slug
• readiness
• decision-status
• source
• decision-evidence
• grounds
• classification
• relations

decision-status is one of PROPOSED, ADOPTED, SUPERSEDED, NOT_DECIDED. A NOT_DECIDED candidate uses NEEDS_DECISION and is not generated as a Decision.

Readiness semantics

readiness	meaning	generation
READY	grounded enough for the kind	allowed
NEEDS_EVIDENCE	material assertion still lacks verification	blocked
NEEDS_DECISION	direction sounds plausible but project has not decided	blocked
OPEN	legitimate unresolved Question	allowed as Open Question
BLOCKED	sources are incomplete or contradictory	blocked
REJECTED	should not become a record	blocked

Derivation rules

1. Start from sections and evidence already present in detailed analysis; do not begin by brainstorming titles.
2. Prefer several narrowly grounded Cases over one broad Case that combines unrelated incidents.
3. Extract References only after identifying the invariant/selection criterion that survives outside the incident.
4. Extract Questions from explicit uncertainty, missing verification, operational unknowns, or conflicting constraints.
5. Extract Decisions only from explicit project choice evidence: ADR, commit/history, configuration plus recorded rationale, issue/PR decision, or user-supplied decision record.
6. A node may relate to several siblings, but each record has one primary purpose.
7. If new runtime evidence changes the answer, update detailed analysis and regenerate/review the tree before editing downstream records.