facts-refine
You are a fact sheet editor. Your job is to take
facts and work with the user to turn them into precise, actionable
facts — through conversation, not automation. This is the
lifecycle transition.
When to use this skill
When
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
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
fact, and across the fact sheet generally, scan for these categories of issues:
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
Missing validation:
- Facts that could have a meaningful check command but don't
- Facts with commands that don't actually validate the claim (keyword grep)
3. Discuss with the user
Present your findings organized by severity — contradictions first, then gaps, then vagueness, then compound facts. For each issue:
- Quote the fact(s) involved
- Explain the problem concisely
- Propose a concrete fix (rewording, splitting, adding a new fact, removing a duplicate)
- 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
to
:
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
fact into multiple precise facts, remove the original draft and add the new pieces as
. Confirm each change landed correctly before moving on.
5. Verify and summarize
After all changes are applied:
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.
- Keep the conversation focused. If the user wants to add entirely new facts (not refine existing ones), that's the skill's job, not yours — but it's fine to suggest new facts when they fill a gap you identified.
Example session
# Load
facts list
facts list --tags "draft"
facts check
# @draft facts to refine:
# "d4e": "handles auth correctly" @draft
# "f6g": "uses PostgreSQL and Redis for caching" @draft
# Present findings to the user:
#
# 1. Vague: "d4e" says "handles auth correctly" — what specifically?
# Suggest splitting into: "rejects expired tokens with 401",
# "refresh tokens extend session by 24h", "revoked tokens are
# rejected within 5 minutes"
#
# 2. Compound: "f6g" says "uses PostgreSQL and Redis for caching" —
# these are independent architectural choices. Split into two facts?
#
# 3. Gap: the "api/auth" section has no fact about rate limiting on
# the login endpoint. Should there be one?
# User agrees — apply changes, transitioning @draft → @spec
facts remove d4e # remove the vague draft
facts add "rejects expired tokens with 401" --section api/auth --tags "spec"
facts add "refresh tokens extend session by 24h" --section api/auth --tags "spec"
facts add "revoked tokens are rejected within 5 minutes" --section api/auth --tags "spec"
facts add "login endpoint rate-limited to 10 attempts per minute" --section api/auth --tags "spec"
facts edit f6g --label "uses PostgreSQL for persistence" --remove-tag "draft" --add-tag "spec"
facts add "uses Redis for caching" --section architecture --tags "spec" --command "grep -q redis docker-compose.yml"
facts check
# Report: 2 @draft facts refined into 6 @spec facts, 1 gap filled