create-fact

• SKILL.mdcore · 13,040 bytes

# Create a fact

## Goal

Memory holds only what the model gets wrong without it, so every entry earns the context it costs on every request that loads it. Each fact is the narrowest rule that would have prevented exactly the correction that produced it, because a wide rule misfires in cases the owner never complained about and a narrow one does not. A fact is written once: a second entry on the same subject splits the truth across two places and lets them drift apart. Each fact is four to five full sentences that give the subject, the fact itself, why the owner holds it and the way to apply it, so a future reader can act on it without reopening the feedback. The admission checks are strict on purpose; a fact the owner never asked for is a guess dressed as memory, and a guess that is loaded on every matching request is worse than no fact at all. A rejected candidate is reported with the check it failed, so the owner can overrule by restating the feedback. The measure of this skill is a memory that stays small while corrections go down.

## Objective

Decide whether one piece of feedback, or one collected finding, deserves a durable entry by running the five admission checks in order and stopping at the first failure. Search the existing facts, rules and hints for the subject so that a duplicate is named rather than written, and a contradiction becomes a replacement that supersedes the old entry. Choose the type: a fact by default, a rule only when the feedback constrains how the agent works, a hint only when the owner expressed a preference rather than a correction. Choose the file by its description, allocate the next id for the prefix, and write the entry in the exact format with a complete metadata line. Create a new facts file and its index row only when no existing file fits. Report every entry written in full, and every candidate rejected with its failing check in one line. The entry's `verified-by` is left `pending` inside feedback handling for the orchestrator to fill, and is named or `none (<reason>)` everywhere else.

## Tasks

1. Run the five admission checks below, in order, and record pass or fail for each. Stop at the first failure and report it; the checks are ordered from cheapest to most demanding, and a candidate that fails an early one needs no further work. When the owner said "collect facts about X" or "remember this", check 1 is waived for the candidates that request covers, because the owner asking for it to be stored is the evidence it matters.
2. Grep `facts/`, `memory/rules.md` and `memory/hints.md` for the subject, its synonyms and the artifact kind. If an active entry already says the same thing, write nothing and name its id; the orchestrator then handles it as `existing`. If the new information contradicts or narrows an active entry, write the new entry with `supersedes: <old id>` and leave the old entry untouched; marking it superseded is done through `skills/update-memory/SKILL.md`, by the orchestrator inside feedback handling.