rafa instinct

rafa records lessons in .rafa/instincts/: one record per task finding that carries a resolution. Lessons that reach a confidence floor are handed to later tasks that need them. rafa instinct checks, reads and curates those records.

Spends: nothing. Changes: flag marks one lesson as wrong so no later bundle blesses it; promote prints and writes nothing; the rest read only.

Actions

Action	Does
check	check every record under an instincts directory against the instinct schema
list	list the records the project and user instinct scopes hold
show	show one instinct record whole, from the project or user scope
flag	flag one held lesson as wrong, so no later bundle blesses it
promote	print the lessons that recurred enough to promote, writing nothing

rafa instinct check

Check every record under an instincts directory against the instinct schema.

rafa instinct check <dir>

Runs the checker over an instincts directory, ~/.rafa/instincts or a project's .rafa/instincts, with every check run on every record so one run names every rule a record breaks: layout (a record is <dir>/<id>.md, flat, and its frontmatter id is its file name), the instinct schema (the required fields, confidence in range, and evidence non-empty for source: task-report), and the resolution and locality of what its body names. The Learning adapter's instincts.ndjson and flags.ndjson are no records and are passed over. The exit code is the number of failing records, capped at 255, and warnings never count. It declares no flag: --fix fills a skill's fields, and with no project root a project-looking path is left unchecked. With --output=json a clean run gives the reports as the data of the terminal result event.

Argument	Type	What it is
dir	string, required	The instincts directory to check: ~/.rafa/instincts, or a project's .rafa/instincts.

Examples:

• rafa instinct check .rafa/instincts: Checks this project's records, exiting with the number that broke a rule.
• rafa instinct check ~/.rafa/instincts --output=json: Writes a start event, then a result event whose data is the reports, when none of them failed.

Output formats: text, json.

rafa instinct list

List the records the project and user instinct scopes hold.

rafa instinct list [--blessed] [--conflicts]

Lists every instinct record the two scopes hold — this project's .rafa/instincts and ~/.rafa/instincts — with, for each, the id its file name gives it, its kind/domain pair, its signal, its confidence and its trigger. A record that breaks a rule of the instinct schema shows the number of rules it broke instead, which rafa instinct check then names. The local Learning adapter's instincts.ndjson and flags.ndjson are its store and no records, and are passed over. A scope whose directory is not there says so. The exit code is 0 whatever the rows say: this command reports and rafa instinct check gates. --blessed lists instead the lessons the learning adapter learning.adapter names would hand a task, at learning.bless.minConfidence, most trusted first, writing nothing; an adapter that cannot be made or a pull it refuses is exit code 1. --conflicts lists instead each trigger a scope holds with more than one action, which a merge flagged and no bundle blesses, its actions side by side with their confidence and usage. The two views are one at a time. With --output=json the scopes and their records, or the view asked for, are the data of the terminal result event.

Flag	Type and default	What it does
--blessed	boolean	List the lessons the configured learning adapter blesses, each with its confidence, usage, trigger and action, instead of every record. Takes no value.
--conflicts	boolean	List each trigger held with more than one action, its actions side by side with their confidence and usage, instead of every record. Takes no value.

Examples:

• rafa instinct list: Lists both scopes, each record with what it is about.
• rafa instinct list --blessed: Lists the lessons a task would be handed, most trusted first.
• rafa instinct list --conflicts: Lists each flagged trigger with its actions side by side.
• rafa instinct list --output=json: Gives the scopes and every record parsed as the data of the terminal result event.

Output formats: text, json.

rafa instinct show

Show one instinct record whole, from the project or user scope.

rafa instinct show <id>

Shows one instinct record: its frontmatter fields, its Action and Cause sections, its evidence, and the action_hash computed from the action, which no file stores. The id is the record's file name, which is what rafa instinct list prints, so a record whose frontmatter id disagrees with its file is still reachable. The scopes are searched nearest the work first, so this project's .rafa/instincts shadows ~/.rafa/instincts, and a line says when the other scope holds that id too. A record that breaks a rule of the instinct schema is refused with exit code 1 and its issues named, as is an id no scope holds. With --output=json the record is the data of the terminal result event.

Argument	Type	What it is
id	string, required	The record's file name without .md, as rafa instinct list prints it.

Examples:

• rafa instinct show worktree-missing-node-modules: Shows that record from whichever scope holds it, the project scope first.
• rafa instinct show worktree-missing-node-modules --output=json: Gives the record as the data of the terminal result event.

Output formats: text, json.

rafa instinct flag

Flag one held lesson as wrong, so no later bundle blesses it.

rafa instinct flag <id> <reason>

Flags one lesson the project holds as wrong, through the learning adapter learning.adapter names in .rafa/config.yaml. A flagged id is left out of every bundle the loop pulls afterwards, whatever a later merge writes under it; under the local adapter the flag is one line appended to .rafa/instincts/flags.ndjson and no record file changes. An id no held record carries is refused with exit code 1 in the adapter's words, a user-scope id included, as is a blank reason. With --output=json the id, the reason and the adapter kind are the data of the terminal result event.

Argument	Type	What it is
id	string, required	The id of a lesson the project holds, as rafa instinct list prints it.
reason	string, required	Why the lesson is wrong, quoted as one word; stored beside the flag.

Examples:

• rafa instinct flag worktree-missing-node-modules "bun install runs on fork since 0.9": Keeps that lesson out of every bundle the loop pulls from now on.
• rafa instinct flag worktree-missing-node-modules "stale" --output=json: Gives the id, the reason and the adapter kind as the data of the terminal result event.

Output formats: text, json.

rafa instinct promote

Print the lessons that recurred enough to promote, writing nothing.

rafa instinct promote

Prints the lessons the project holds that recurred enough to promote: the blessed set of the learning adapter learning.adapter names in .rafa/config.yaml, narrowed to the lessons at least learning.promote.after distinct sources confirmed at a confidence of at least learning.promote.minConfidence, most trusted first. It is the list the next wrap-up session would be asked to promote. Nothing is written: no lesson is marked promoted and no file changes. A kind no registry holds, an adapter that cannot be made or a pull it refuses is exit code 1. With --output=json the adapter kind, the two keys' values and the lessons are the data of the terminal result event.

Examples:

• rafa instinct promote: Lists each promotable lesson with its confidence, usage, trigger and action.
• rafa instinct promote --output=json: Gives the adapter kind, the two keys' values and the lessons as the data of the terminal result event.

Output formats: text, json.