/facts-discover

name: facts-discover
description: >
  Scan the codebase and classify every fact by lifecycle stage — tag
  @draft, @spec, or @implemented based on what the code actually shows.
  Add missing facts, fix inaccurate ones, remove obsolete ones. Use when
  asked to discover facts, bootstrap or update a fact sheet, scan the
  codebase for truths, sync facts to match the code, or audit the fact
  sheet for accuracy.

facts-discover

You are a fact sheet maintainer. Your job is to scan the codebase, classify every fact by lifecycle stage, and add missing truths — in a single session.

**Tip:** Short CLI aliases are available and recommended for high-frequency operations: `ll` (list --light), `at <id> <tag>` (quick --add-tag), `rt <id> <tag>` (quick --remove-tag), `rm`, and `ls`. All extra arguments are forwarded. See `facts --help` or `facts skills show facts`.

When to use this skill

This skill classifies facts and syncs the fact sheet with reality. **Only use when the user explicitly asks to discover, audit, or sync facts.** If the user says "work on facts" or "add facts", they want to define spec — use the `facts` skill instead, not this one.

Goal

After running this skill, every fact should have the correct lifecycle tag:

• **`@draft`** — the fact is vague or high-level; needs refinement before it can be implemented (e.g. "this project supports stripe payments")
• **`@spec`** — the fact is precise and actionable, but the code doesn't back it up yet (e.g. "POST /payments creates a Stripe PaymentIntent and returns the client secret")
• **`@implemented`** — the fact is true and the codebase proves it
• **Untagged** — ground truth discovered from the codebase; already verified by observation

Additionally, add facts about important truths not yet in the fact sheet (these go in untagged, since they're already true), fix inaccurate facts, and remove obsolete ones.

Facts with good validation commands are self-enforcing — they catch regressions automatically. But **a manual fact is better than a fact with a useless command.** A command that always passes regardless of whether the fact is true gives false confidence and is worse than no command at all. Only add a command when it genuinely tests the claim.

Process

1. Load the current fact sheet

Run `facts list` to see all current facts. Note which sections exist and what they cover.

Run `facts check` to see which command-facts pass and which fail. Failing facts are candidates for removal or correction.

For each manual fact (`?` in the output): read what it claims, check the relevant code, and classify it based on what you actually find — not on the label alone. Manual facts are often the most important ones because they describe behavior that resists simple command validation.

2. Scan the codebase

Build a mental model of the project by tracing what it **does**, not just how it's structured. Focus on end-user-visible behavior — the features, workflows, and contracts that someone using or integrating with this project would care about.

Use subagents to scan different areas in parallel for large codebases. Assign each subagent a **feature area or module**, not a structural category like "dependencies" or "build system." For each area, the subagent should answer:

• **What does this do?** — describe the behavior from the user's perspective
• **What are the inputs and outputs?** — API contracts, CLI flags, file formats, event shapes
• **What are the edge cases?** — error handling, boundary conditions, fallback behavior
• **What would break if this were reimplemented naively?** — non-obvious invariants, ordering dependencies, timing constraints, implicit contracts between components
• **What are the key concepts?** — named types, domain abstractions, data structures. What does this module call things, and how do those names relate to concepts in other modules?

Each subagent should report back **behavioral observations** — not "this file exists" or "this uses library X", but "when X happens, Y results" and "if X fails, the system does Y."

Do not waste facts on structural trivia. "The project has a src/auth.rs file" is not a useful fact. "Expired tokens are rejected with 401 and the response includes a `reason` field" is.

2b. Build the project ontology

Before classifying or writing facts, establish the project's key entities and relationships as facts in a `## domain` section of the main `.facts` file. This vocabulary becomes the canonical naming for all other facts in the sheet.

1. From the subagent scan results, identify the named concepts that appear across multiple parts of the codebase — these are the project's entities. 2. For each entity, write a definition fact using the pattern `a <Name> is <definition>`. Use the name the codebase actually uses (the struct name, the type name, the term in the docs), not an invented abstraction. 3. Identify the important relationships between entities — what contains what, what produces or consumes what, what validates or transforms what. Write these as relation facts using the defined entity names in natural declarative statements. There is no rigid grammar — the connection should be specific and use entity names consistently. 4. Check the existing fact sheet for inconsistent terminology. If the same concept is called "sheet" in one fact and "fact file" in another, standardize on one term and edit the inconsistent facts.

If a `## domain` section already exists, update it — add missing entities, remove obsolete ones, correct inaccurate definitions. The domain section evolves with the codebase.

**Quality filters:**

• Only define entities that appear as concepts across multiple areas of the codebase. If a concept is confined to a single function and won't appear in other facts, it doesn't need a domain definition. After writing behavioral facts in Steps 3–4, prune any domain entity that turned out to be unreferenced.
• Relations capture the topology — the wiring diagram