/facts

name: facts
description: >
  Manage .facts files — atomic, validatable truth statements about a project.
  Install, check, list, add, edit, remove, and lint facts via the CLI.
  ALWAYS read this skill when the user mentions facts in any capacity.

facts

A CLI for fact-driven development. You use it to specify what must be true about a project, then validate that reality matches.

Project: https://github.com/av/facts

Installing

If `facts` is not installed, install it with one of:

curl -fsSL https://raw.githubusercontent.com/av/facts/main/install.sh | sh

npm install -g @avcodes/facts

pipx install facts-cli

Verify with `facts --version`. The command is always `facts` — never `npx facts`.

Core idea

A `.facts` file is a flat list of atomic truth statements about a project. Each fact can optionally have a shell command that verifies it. The fact sheet serves as both specification (what should be true) and documentation (what is true) — the difference is just which direction you're working from.

- the API returns JSON
- label: project builds
  command: cargo build
- label: tests pass
  command: cargo test
  tags: [ci, core]

That's the entire format. Plain strings for simple facts, mappings when you need a command, tags, or explicit ID. Allowed mapping keys: `id`, `label`, `command`, `tags` — nothing else.

Essential commands

**Recommended short aliases** (all extra arguments are passed through):

• `ll` = `list --light` — the most common "skim" view (markdown headings + dim IDs)
• `ls` = `list`
• `rm` = `remove`
• `at <id> <tag>` = `edit <id> --add-tag <tag>` (supports multiple IDs and `--label` / `--new-id` etc. after the tag)
• `rt <id> <tag>` = `edit <id> --remove-tag <tag>`

These are the highest-ROI shortcuts for daily and agent use.

**See everything:**

facts ll
facts ll --tags "not implemented"
facts ll --has-command
facts list --light                      # or the alias: facts ll

**Validate:**

facts check                             # default: command-facts only; manual stay ?
facts check --tags "ci"
facts check --id abc                    # check a single fact by ID
facts check --section cli/check         # check one section
facts check --agent                     # opt in: .config agent or PATH preset
facts check --agent claude              # opt in: specific agent
facts check --no-agent                  # explicit skip (redundant with default)
facts check --has-command               # check only facts with commands
facts check --manual --agent claude     # check only manual facts with agent
facts check --strict                    # fail on unverified manual facts (CI)
facts check --strict --agent claude -q  # CI: verify everything, fail on gaps
facts check -q                          # quiet: exit code only (for CI)
facts check -v                          # verbose: show agent prompts and output

`check` is your primary feedback loop. It lints the files first (aborting on structural errors), then runs every command-fact and reports pass/fail/manual. Run it often. Exit 0 means all command-facts pass; manual facts don't affect the exit code unless an agent verifies them and finds failures, or `--strict` is used (which treats any unverified manual fact as a failure).

**Manual facts (`?` in output) are your responsibility.** They have no command — you verify them by reading the relevant code. For each `?` fact: read what it claims, check the code, then report PASS or FAIL with a one-line reason. Reporting "N manual" without checking each one is not acceptable — those facts exist because they describe behavior that matters.

**Configure the project for agent verification:**

facts config set agent claude           # persist agent choice in .facts
facts config set batch-size 5           # how many facts per agent call
facts config show                       # see current config
facts config rm agent                   # remove a config key

**Add facts:**

facts add "users can sign up" --section features/auth
facts add "signup returns 201" --command "curl -s -o /dev/null -w '%{http_code}' localhost:3000/signup | grep 201" --section features/auth

**Edit / tag facts (lifecycle transitions):**

facts at <id> "implemented"          # most common: quick add tag
facts rt <id> "spec"                 # quick remove tag
facts at <id> "spec" --new-id xyz    # extra flags still work
facts edit <id> --label "corrected statement"
facts edit <id> --command "new check command"
facts edit <id> --remove-command            # convert back to manual fact
facts edit <id> --remove-command --add-tag "draft"  # demote to manual + draft

Prefer `at`/`rt` (or the long `--add-tag` / `--remove-tag` forms) over the full `--tags` replacement. The latter replaces all tags silently. Use `--remove-command` to strip a validation command and convert a fact back to a manual fact (useful when demoting across the lifecycle).

**Remove facts:**

facts rm <id>     # or the long form: facts remove <id>

**Scaffold a new project:**

facts init

Run `facts <command> --help` for the full flag reference.

How facts work

**Files:** `.facts` is the default. Additional sheets use semantic names (`cli.facts`, `api.facts`). All `*.facts` files in the project root are discovered automatically.

**Sections:** Markdown headings (`#`, `##`, etc.) create hierarchical sections addressable by path (e.g. `cli/subcommands`). Sections are created when you add to them and removed when their last fact is deleted.

**Tags:** `@word` tokens for filtering. Inline for plain strings (`- some fact @mvp`), `tags:` key for mappings. Stripped from the label before display and ID hashing. Filter with boolean expressions: `--tags "mvp and not blocked"`.

**Lifecycle tags:** Three well-known tags drive the agent workflow:

• `@draft` — rough idea, needs refinement and atomization
• `@spec` — precise and actionable, ready to implement

-