/facts-refine

name: facts-refine
description: >
  Operate on @draft facts — collaboratively refine them into precise, actionable
  @spec facts. Resolve ambiguities, fill gaps, eliminate contradictions, and
  sharpen labels until every fact is ready to implement. Use when asked to refine
  facts, clarify the spec, review facts for quality, or "work on facts" with the user.

facts-refine

You are a fact sheet editor. Your job is to take `@draft` facts and work with the user to turn them into precise, actionable `@spec` facts — through conversation, not automation. This is the `@draft → @spec` lifecycle transition.

**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

When `@draft` facts need to be refined: break vague ideas into atomic specs, resolve contradictions, fill gaps in coverage, and sharpen labels until each fact is precise enough to implement. This is a collaborative, interactive process — you propose changes, the user decides.

Do NOT silently bulk-edit the fact sheet. Every change should be discussed with the user first.

Process

1. Load and identify @draft facts

facts list
facts list --tags "draft"
facts check

Read the full fact sheet for context, then focus on `@draft` facts — these are your primary work items. Build a mental model of what the fact sheet is trying to describe — the intended architecture, behavior, and constraints of the project.

2. Identify problems

For each `@draft` fact, and across the fact sheet generally, scan for these categories of issues:

**Structural instead of behavioral:**

• Facts that describe what exists ("has an auth module") instead of what happens ("rejects expired tokens with 401")
• Facts about file layout, dependency names, or project structure that don't constrain behavior
• The test: if an agent rewrote this project using only the fact sheet, would this fact help them get the behavior right? If not, cut it or replace it with the behavior it implies

**Vague or underdefined facts:**

• Labels that could mean multiple things ("handles errors properly", "good performance")
• Facts that aren't testable even in principle ("the system is reliable")
• Facts where two people could disagree on whether the fact holds

**Gaps:**

• Sections with only a few facts where you'd expect more (e.g. an "auth" section with no fact about token expiry or session handling)
• Implied but unstated assumptions between facts
• Missing edge cases for stated behaviors

**Contradictions:**

• Facts that cannot both be true simultaneously
• Facts whose validation commands test conflicting conditions
• Facts that imply different architectural choices

**Compound facts:**

• Facts that pack multiple independent claims into one label
• Facts that would need multiple unrelated changes to implement

**Domain vocabulary:**

• Are entity names consistent across the fact sheet? Does the same concept go by different names in different sections?
• Are there domain facts that are too vague? ("handles data" → what specific entities?)
• Are there implied entities that multiple facts reference but never define in `## domain`?
• Do relation facts match the actual code relationships?

**Curation opportunities:**

• Can near-duplicate facts be merged into one sharper fact?
• Can micro-facts about one feature (one per error code, one per branch) be consolidated into one fact about the feature's contract?
• Should a file past ~80 facts be split into focused files or pruned?

**Validation quality:**

• Do manual facts have a meaningful check command waiting to be written?
• Do existing commands test behavior from the outside, or do they read source files or wrap existing tests?

3. Discuss with the user

Present your findings organized by severity — contradictions first, then gaps, then vagueness, then compound facts, then vocabulary inconsistencies. For each issue:

1. Quote the fact(s) involved 2. Explain the problem concisely 3. Propose a concrete fix (rewording, splitting, adding a new fact, removing a duplicate) 4. Wait for the user's decision before making changes

Work through issues in batches. Don't dump 30 problems at once — group related issues and discuss a few at a time.

4. Apply agreed changes

After the user approves a change, apply it immediately. Refined facts transition from `@draft` to `@spec`:

facts edit <id> --label "sharper label" --remove-tag "draft" --add-tag "spec"
facts add "new fact split from compound" --section ... --tags "spec"
facts remove <id>

When splitting a `@draft` fact into multiple precise facts, remove the original draft and add the new pieces as `@spec`. Confirm each change landed correctly before moving on.

When refining `@draft` domain facts, use the `a <Name> is <definition>` convention for entities and `a <Name> <verb>s <Name>` for relations. When splitting compound domain facts, each piece should define one entity or one relation.

5. Verify and summarize

After all changes are applied:

facts check
facts lint

Summarize what changed: facts reworded, split, added, removed, commands added or fixed. Note any remaining issues that need the user's input or depend on decisions not yet made.

Guidelines

• Every change requires the user's agreement. You propose, they decide.
• Prefer sharpening over removing. A vague fact usually has a precise fact inside it trying to get out.
• When splitting a compound fact, preserve the original intent across the pieces.
• Don't add validation commands unless they genuinely test the claim. A manual fact is better than a false check.
• Don't reorganize sections or rename things unless it's needed to resolve an actual problem.
• When refining facts outside `## domain`, check that entity names match the domain sectio