How the agent files feedback

The private log

The moment a blueprint or rcf-lite itself misbehaves, the agent writes a short entry to .rcf/feedback/ in your project, or in the main checkout when it is working in a linked git worktree. The store is gitignored, so it never lands in a commit, and the raw entry is unredacted, so it captures what actually happened. Recording is silent. The agent does not stop what it was doing, nothing goes over the network, and you find out on your own terms.

Each entry names what broke (a blueprint the agent applied, or a verb inside rcf-lite), a severity, a short title and enough evidence for a triage reader to open the right file. If you want the field-by-field shape, ask your agent to show you.

Worktrees and parallel sessions

In a linked git worktree, the store is the main checkout's .rcf/feedback/, so an entry the agent records in the worktree is still pending in the main checkout after git worktree remove. That needs the main checkout to ignore .rcf/feedback/. Until it does, rcf feedback add in the worktree exits 2, names the main checkout and points at rcf doctor --fix. When the main checkout does not hold the rcf project, the worktree keeps its own store.

A worktree can also hold a queue in its own .rcf/feedback/. That queue moves into the main checkout on the next rcf feedback command in the worktree, the session hooks included, once the main checkout ignores the store. Run rcf doctor --fix in the main checkout before you remove a worktree that holds a queue, or the queue goes with the worktree.

Several sessions can share one store. A command that writes to it while another is changing it waits for up to 10 seconds; if the other command is still busy then, it exits 1, names that command's process id and writes nothing, so no entry, ask or bundle is overwritten or lost. rcf feedback submit waits for up to 65 seconds to record an issue it has filed; if it cannot, it exits 1 naming the issue URL and the entry, and the next submit records the filing without filing it again. RCF_FEEDBACK_LOCK_WAIT_MS sets both waits, in milliseconds.

Nothing leaves until you say yes

rcf feedback add writes locally and stops there. To file a GitHub issue you run rcf feedback submit, and you have to say yes before it does. The issue is filed under your own gh login, so it appears in the repo as authored by you. There are no service accounts or shared tokens in the loop.

Between the two, rcf feedback preview renders what the issue would say. This is the read-before-you-send step. Redaction has already run on the previewed text, and preview prints a ledger of every substitution the redactor made so you can see what got stripped. Attachments, screenshots and binaries are never posted; the issue body is text, capped after redaction, and that is all.

Redaction runs first

Before an issue can be filed, the entry passes through a redactor that folds anything shaped like a secret or an identifier that would leak the machine you were on. Absolute paths, project remotes, emails, non-public hostnames and IPs, GitHub / AWS / Slack / Stripe tokens, JWTs, PEM blocks, Authorization: lines and password: ... style pairs are all replaced before the body renders. A final residual pass sweeps the fully assembled body for anything the per-field rules missed. If it finds a shape it does not like, submit refuses the entry rather than send a redacted-but-still-leaky body.

You see the ledger at preview. If the ledger shows something the redactor missed, discard the entry with rcf feedback discard and tell the agent; it can help you file a cleaner one, or fix the underlying capture.

The one nudge

At the first pause once a pending entry is about fifteen minutes old, at most once a session, the agent asks whether to file: pending titles, and defer / discard / submit. That is the only interruption feedback ever creates. If it is still noisy, rcf feedback opt-out silences it for the project and rcf feedback opt-in puts it back. add, preview and submit all still work under opt-out, for the times you want to hand-drive one.

The agent sessions rcf-lite launches itself, such as the verifier that rcf verify run starts against a URL, never ask. rcf-lite sets RCF_FEEDBACK_ASK=0 in them, so the hook stays quiet there while the agent can still record an entry. Your own sessions keep the ask, and setting RCF_FEEDBACK_ASK=0 yourself silences it for any session.

What you do

Nothing, most of the time. Your agent captures as it goes; you find pending entries when the session ends, or you can ask "any feedback pending?" at any point. When something is worth filing, ask the agent to preview it, read the redacted body and say yes.

If you want the full mechanism (the schema of record, the store layout, every redaction rule, hook install, exit codes, environment variables), ask your agent. It has the feedback schema of record and the reference pages already, and it will pull what you need.

Related

• Wire your agent: install rcf-lite and let init register the hooks.
• Harness block: the operating rules rcf init writes into your agent-instructions file, including the always-record rule for blueprint and core findings.