Reasons — track justified beliefs with automatic retraction cascades and restoration
You are managing a dependency network using the reasons CLI tool. Unlike beliefs (which tracks independent facts for expert registries), reasons tracks justified conclusions where beliefs depend on other beliefs and changes propagate automatically.
reasons vs beliefsUse beliefs when | Use reasons when |
|---|---|
| Facts are independent (no dependency chains) | Conclusions build on premises (dependency chains) |
| Expert/knowledge registries (RHEL, agents-python) | Research registries (physics, bethe, beliefs-pi) |
| Staleness = source file changed | Staleness = upstream belief retracted |
| Maintenance = check-stale, contradictions | Maintenance = retraction cascades, backtracking |
| Density 0.00 (flat) | Density 0.74+ (dense) |
Rule of thumb: If beliefs depend on other beliefs, use . If beliefs depend only on external sources, use .
reasonsbeliefsTry these in order until one works:
reasons $ARGUMENTS (if installed via uv tool install -e ~/git/ftl-reasons)cd ~/git/ftl-reasons && uv run reasons $ARGUMENTS (from repo directory)uvx --from ftl-reasons reasons $ARGUMENTS (fallback)add without --sl or --cp.initRun reasons init to create reasons.db in the current directory. Use --force to reinitialize.
addAdd a node to the network. Three forms:
# Premise (no justification — IN by default)
reasons add node-id "Description of the belief"
# Justified by other nodes (SL = all antecedents must be IN)
reasons add node-id "Description" --sl antecedent-a,antecedent-b
# Non-monotonic: believe X unless Y (outlist)
reasons add node-id "Default holds" --unless counter-evidence
reasons add node-id "X if A and not Y" --sl dep-a --unless dep-y
# With provenance
reasons add node-id "Description" --sl dep-a --source "repo:path/to/file.md" --label "why this justification holds"
If the user describes a belief in natural language, convert it:
--sl dep-a,dep-b--source repo:pathExample: "The threshold is tool-use calibration, based on beliefs-improve-accuracy"