Reasons

How to Run

Try these in order until one works:

1. reasons $ARGUMENTS (if installed via uv tool install -e ~/git/ftl-reasons)
2. cd ~/git/ftl-reasons && uv run reasons $ARGUMENTS (from repo directory)
3. uvx --from ftl-reasons reasons $ARGUMENTS (fallback)

Key Concepts

• Premise: A node with no justifications — IN by default. Created when you add without --sl or --cp.
• Justified node: A node that is IN because its justification is valid. Goes OUT automatically when the justification fails.
• SL justification (Support List): Node is IN when ALL antecedents are IN. This is the main justification type.
• Multiple justifications: A node can have multiple justifications. It stays IN if ANY of them is valid. Only goes OUT when ALL fail.
• Retraction cascade: When a node goes OUT, all dependents whose justifications become invalid also go OUT — automatically, transitively.
• Restoration: When a retracted node comes back IN, dependents are recomputed — no manual rederivation needed.
• Outlist (non-monotonic): A justification can require nodes to be OUT (not just IN). "Believe X unless Y" — if Y goes IN, the justification fails. This enables default reasoning and defeasible inference.
• Nogood: A set of nodes that cannot all be IN simultaneously. When detected, dependency-directed backtracking traces to the responsible premise and retracts it.
• Challenge/Defend: Dialectical argumentation. Challenging a node makes it go OUT. Defending it neutralises the challenge. Multi-level chains are supported.

Subcommand Behavior

init

Run reasons init to create reasons.db in the current directory. Use --force to reinitialize.

add

Add 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:

• Extract the node ID (kebab-case the key phrase)
• Extract the description text
• Identify dependencies → --sl dep-a,dep-b
• Identify source → --source repo:path

Example: "The threshold is tool-use calibration, based on beliefs-improve-accuracy"