harbor: Skill for Claude Code

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