hypothesis-tree
Builds, updates, and reviews a persistent hypothesis tree for an investigation.
The tree lives in a single markdown file at docs/hypothesis_tree.md (or the project's equivalent docs location).
Each hypothesis carries falsifiable criteria, linked evidence, and a next experiment.
Trigger: /hypothesis-tree <subcommand>.
The rule
A hypothesis needs a falsifiable criterion and a named next experiment. Without both, do not add the node.
Arguments
$ARGUMENTS is a subcommand plus parameters:
add "H: <statement>"- add a new hypothesis node.update <ID> --evidence-for|--evidence-against "<description>" --file <path>- attach evidence to an existing node.update <ID> --confidence <level>- change confidence, permitted only alongside evidence.review- display every hypothesis with staleness indicators.prune- propose archiving hypotheses with no evidence updates in 14 or more days.
Tree node schema
Every hypothesis in the tree file follows this structure:
### H<N>: <Statement>
- **Status:** ACTIVE | SUPPORTED | REFUTED | ARCHIVED
- **Confidence:** HIGH | MEDIUM | LOW
- **Falsifiable criterion:** <What specific observation would disprove this?>
- **Evidence FOR:**
- [<description>](<relative path to file>) - <date added>
- **Evidence AGAINST:**
- [<description>](<relative path to file>) - <date added>
- **Next experiment:** <Concrete action that would strengthen or weaken this hypothesis>
- **Last updated:** <YYYY-MM-DD>
Workflow
Phase 1: Parse the subcommand
Read the subcommand from $ARGUMENTS and route: add to Phase 2a, update to Phase 2b, review to Phase 2c, prune to Phase 2d.
With no argument, or help, display the usage summary and stop.
Phase 2a: Add a hypothesis
- Parse the hypothesis statement from the arguments.
- Verification gate: confirm the statement carries both a falsifiable criterion (what would disprove it) and a next experiment (what concrete action tests it). If either is missing, prompt the user. Do not add the node without them.
- Read the tree file, creating it if it does not exist.
- Assign the next sequential ID (H1, H2, H3, ...).
- Write the node using the schema above.
- Set Status to ACTIVE and Confidence to LOW. New hypotheses always start at LOW.
- Set Last updated to today's date.
Verification gate: read the file back and confirm the node was written correctly.
Phase 2b: Update a hypothesis
- Parse the hypothesis ID and the evidence from the arguments.
- Read the tree file and confirm the ID exists.
- If
--file <path>was given:- Verification gate: confirm the file exists on disk.
- Verification gate: read the file and confirm it actually contains something supporting the stated claim.
- If the file does not exist, or does not support the claim, STOP and report it to the user. Do not write the entry.
- Append the evidence entry with today's date.
- If
--confidence <level>was given, update it, but only when the new evidence justifies the change. - Update Last updated to today's date.
- If the evidence now clearly supports or refutes the hypothesis, suggest a Status change to the user.
Verification gate: read the updated node back and confirm the evidence was appended correctly.
Phase 2c: Review all hypotheses
- Read the tree file.
- For each hypothesis compute: days since last update, a staleness indicator (FRESH under 7 days, AGING 7 to 14 days, STALE over 14 days), and the evidence balance as a count of FOR versus AGAINST.
- Display the summary table:
=== HYPOTHESIS TREE REVIEW ===
ID Status Confidence Evidence (F/A) Staleness Statement
H1 ACTIVE HIGH 4/1 FRESH <truncated statement>
H2 ACTIVE LOW 1/0 STALE <truncated statement>
H3 REFUTED - 2/3 FRESH <truncated statement>
- Flag every ACTIVE hypothesis that is STALE. Those need attention.
- Flag every hypothesis with zero evidence entries. Those need data or should be pruned.
Verification gate: cross-check that every file path referenced by an evidence entry still exists on disk, and report the broken links.
Phase 2d: Prune stale hypotheses
- Read the tree file.
- Identify hypotheses that are either ACTIVE with no evidence update in 14 or more days, or have zero evidence entries and were created 7 or more days ago.
- Display the archival candidates. Never auto-archive.
- Wait for user confirmation before changing any Status to ARCHIVED.
- For confirmed archives, move the node into an
## Archivedsection at the bottom of the file. Nothing is deleted.
Verification gate: read the file back and confirm the archived hypotheses moved correctly.
Phase 3: Report
After any subcommand, display:
- What changed: added, updated, or archived.
- Current tree statistics: total hypotheses, and counts of active, supported, refuted, and archived.
- Any recommended next actions: stale hypotheses, broken evidence links, nodes with no evidence.
