document-haness/.agents/skills/deriving-tech-log-root-tree/references/decomposition-checklist.md

Tech Log Tree Decomposition Checklist

Selection

• Every analysis candidate carries a disposition, and KEEP_IN_SSOT is used.
• dispositionReview: PENDING is 0 — nothing reached the tree by recall alone.
• Each PROMOTE node passes the independence test.
• Candidates were discovered from final/document.md, not from analysis/**.
• Material found only in analysis/** was added to final/document.md first.
• candidateScope is declared, and no candidate came from outside it.

Source integrity

• The tree records the source document hash, ledger hash, and project revision.
• Every node has at least one source anchor.
• Source anchors actually contain the material implied by the title.
• Runtime-dependent claims name evidence or use NEEDS_EVIDENCE.
• readiness states how well evidenced the node is. It does not state whether the record has been written or published.

Topic quality

• Every Topic has one reader question, and every node in it helps answer that question.
• No two Topics share a reader question.
• Topic is an engineering problem space rather than a directory name.
• A large Topic is split when its records no longer share useful relations/criteria.

Case

• There is a specific incident, experiment, failure, diagnosis, or verification sequence.
• The title can be understood without inventing a historical story.
• The conclusion is bounded by actual evidence.
• Observations that answer the same question with the same conclusion are one Case, as a table or sub-sections — not several partial Cases.

Concept

• It was added because a Case, Decision, or Question needs it, not by sweeping headings.
• basis-version names what the explanation was written against.
• The title names a mechanism, not an absence, a count, or an analysis-scope fact.
• No analysis section number or finding grade survives in the title.

Setup

• Someone other than the author has to run it; it is not one Case's reproduction steps.
• The commands and configuration values come from the analysis, not from memory.
• pinned-versions names the versions the procedure was established on.
• A project is set. No verification date is invented to stand in for the versions.

Reference

• The rule is reusable beyond the originating incident.
• It is not the Case summary rewritten declaratively.
• Scope and exception can be stated from sources.

Open Question

• The answer is not already in the analysis.
• Known/unknown/next verification are separable.
• The design or a decision actually turns on the answer.
• Candidate options are included only when sources really considered them.

Decision

• A project choice is explicitly recorded or user-supplied.
• technology is present is not being treated as rationale.
• The accepted cost is stated, not only the benefit.
• NEEDS_DECISION is used if the direction is only a recommendation.

Duplication and shape

• No two nodes have the same primary purpose.
• Relations are used instead of copying one record into another.
• Node count is bounded by what a reader would read, not by the analysis denominator.

Parity

• Every node traces back to a PROMOTE candidate, and every PROMOTE candidate has a node.
• counts matches what build-tech-log-tree.py produces.
• unlisted is empty — no record file exists outside the contract.
• python3 scripts/verify-tech-log-tree.py <project> reports 0 errors.