Handle feedback

Goal

Every piece of human feedback is written down once, verbatim, before anything is done with it, so the owner's words are never paraphrased away and every later memory entry can be traced back to them. Each piece then becomes exactly what it should and nothing more. That means a fact or rule when the model would otherwise repeat the mistake, a deterministic test or a verifier so code catches the mistake from then on, and updates to the existing entries the feedback contradicts or confirms. Three subagents make those three decisions separately, each from the same inputs and each writing to its own files, so no single reading of the feedback can quietly skip one outcome or overwrite another's work. Nothing is left pending: when this skill ends, the feedback entry says what was kept and where, or why nothing was. The rejected artifact is regenerated with the new memory applied, so the owner sees the correction take effect in the same request rather than in the next one. The repo measures itself by fewer corrections over time, and this skill is the only place a correction is turned into something that prevents the next one. A correction that is logged but never becomes a check is the failure this skill exists to prevent.

Objective

Log the feedback as an FB entry holding the owner's verbatim words and the context in which they were said. Launch the three feedback subagents, fact, test and update, with the same inputs and with write scopes that do not overlap, so they can run at the same time without one undoing another. Stitch their three reports into one consistent memory: point each new fact or rule at the test or verifier that now checks it, apply the operations the update agent could only report, and mark every superseded entry. Fill the disposition line so the log says what this piece of feedback became. Regenerate the rejected artifact with the new entries applied and confirm the new test passes on it. Regenerate the footprint and run the full suite until it is green. The skill is done when the feedback log, the memory files, the tests and the artifact all agree with the owner's words.

Tasks

1. Append the feedback to memory/feedback-log.md as a new entry, numbered as the highest existing FB number plus one, in the exact shape below. The verbatim line holds the owner's words unchanged, including typos, because the admission checks and later audits depend on what was actually said. The context line names the run, the artifact path and where the artifact was rejected or confirmed, so a future reader can find the evidence. Write disposition: pending and nothing else on that line; it is filled in task 6.

   ### FB-<nnn>: <subject in under eight words>
   > verbatim: "<the owner's words>"
   context: <run, artifact path, and where it was rejected or confirmed>
   disposition: pending
   -- added: YYYY-MM-DD | source: owner | status: active

2. If the feedback approves an artifact as a whole ("this is exactly right", "do it like this from now on"), copy that artifact into memory/examples/<slug>.md with the three-line header from memory/examples/README.md before launching anything. The test subagent can then write a snapshot check against the example, and verifiers can read it as a positive example. A partial approval or a correction never produces an example; a rejected artifact goes to tests/fixtures/ through the test subagent instead.
3. Launch the three subagents, in parallel where the harness allows. Give each one the same inputs: the FB id, the verbatim text, the context line, the artifact paths, and the correction or the accepted version. Each has a write scope that no other subagent touches:
   • feedback-fact (Claude Code agent feedback-fact; elsewhere prompts/feedback-fact-agent.md) writes only facts/, memory/rules.md, memory/hints.md, and a new row in the AGENTS.md facts index when it creates a facts file.
   • feedback-test (agent feedback-test; prompts/feedback-test-agent.md) writes only tests/, verifiers/ and memory/verification.md.
   • feedback-update (agent feedback-update; prompts/feedback-update-agent.md) writes only memory/failures.md, memory/decisions.md, memory/open-questions.md, memory/scope.md, memory/glossary.md, memory/pointers.md and memory/workflows.md. For entries in the other two scopes it reports the operation under for-orchestrator instead of applying it.
4. Stitch the three reports once all three have returned. On each new fact or rule, replace verified-by: pending with the first test the test report lists for this FB id, as tests/<file>.py::<function>, or with the verifier path when a verifier was registered instead, or with none (<reason from the test report>) when neither exists. Apply every line under for-orchestrator in the update report by editing only that entry's metadata line, as skills/update-memory/SKILL.md describes. Where the fact agent wrote supersedes: <old id>, set status: superseded | superseded-by: <new id> on the old entry. For a narrow whose replacement the fact agent did not write, write the narrower entry now through skills/create-fact/SKILL.md and link both.
5. Handle the two signals that mean memory already existed but did not work. If the update report lists ids under not-taking-effect, or the fact report names an existing entry for a correction, that entry has no check or its check misses the mistake: run skills/create-test/SKILL.md for it now and set its verified-by to the new test. If that entry is a hint, the owner has now corrected a preference, so supersede it with a fact through skills/create-fact/SKILL.md; a hint corrected twice is a fact with a check.
6. Replace the disposition: pending line with disposition: fact <ids or none> | tests <paths or none> | updates <ids or none>, naming every id and path the three reports kept. Write disposition: not kept (<reason>) only when all three subagents kept nothing, and give the failing admission check as the reason. The integrity test fails on a disposition that names an id or path that does not exist, so copy them from the reports, not from memory.
7. Regenerate the rejected artifact with the new entries applied, then run python scripts/footprint.py --write and python -m pytest -q tests. Fix integrity failures in the entries written during this handling, since those are yours. A new feedback test that still fails means the artifact is still wrong: regenerate the artifact again, and never edit the test to make it pass.

Instructions

• Log before launching. The FB id is allocated by the log entry and is the thread that ties the three reports, the test file name, the fact's source key and the disposition together. A subagent launched before the entry exists has no id to write into its files, and the integrity test will reject what it wrote. If the harness crashes between the log and the launch, the pending entry is the recovery point: the next run sees it and launches the subagents again.
• Pass each subagent only its inputs, never this conversation. Each prompt lists exactly what it may write, and that list is what makes parallel runs safe; do not widen it in the launch message, and do not ask a subagent to do another's job. A subagent that sees the conversation inherits the reasoning that produced the mistake, which is what fresh context is meant to prevent. The inputs are small: the FB id, the verbatim text, the context line, the artifact paths, and the correction or accepted version.
• The three decisions are independent, which is why they can run at once. The fact agent decides whether anything durable exists in the feedback; the test agent decides how code or a verifier can check it; the update agent decides what existing memory the feedback changes. None of them needs another's output, and no file is written by two of them, so there is nothing to serialize. Stitching exists because the links between their outputs, the verified-by key, the superseded-by key and the disposition, can only be written once all three have returned.
• Without subagents, run the three prompts yourself, one after another. Use the order fact, test, update, and for each one read only that prompt and its inputs before acting, as if you were the fresh context. Keep each prompt's write scope while you are inside it, and produce its output block before moving to the next. Then stitch as usual; the scopes still matter because the stitching step assumes each file was written by one actor.
• When two reports conflict, the owner's latest words win. If the update report says to retire an entry that the fact agent has just superseded with a replacement, the replacement stays active and the old entry is marked superseded, never retired and superseded at once. If the fact agent admitted an entry the update agent says already exists, keep the new one only if it narrows or contradicts the old one, and otherwise drop the new one and name the existing id in the disposition. Record any conflict you had to resolve in the request report so the owner can overrule it.
• "Collect facts about X" is feedback too, with one difference. It waives the first admission check in the fact agent and allows up to ten facts in one handling. The test and update agents still run, because collected facts need checks and may contradict older entries. The disposition then lists every admitted id.
• A strong confirmation is handled, not skipped. The update agent confirms the entries the owner restated, the test agent may add a snapshot check against the example written in task 2, and the fact agent usually admits nothing because the model was not wrong. If the owner says "remember this" about something the model got right, the fact agent treats it as a collect request for that one fact, since the owner asking for it to be stored is the evidence it matters.

Checklist

• The FB entry exists with verbatim text and context before any subagent ran. Open memory/feedback-log.md and confirm the entry's number is the highest and its verbatim line matches the owner's message character for character. A paraphrase here would poison every downstream decision. The entry's date is today's, in ISO form.
• Each subagent wrote only inside its scope. Compare git status against the three scopes in task 3; a file outside every scope, or a file inside two scopes, means a prompt was not followed and the write must be reviewed before stitching. The scopes are the only thing that makes the parallel run safe. Report any excursion in the request report.
• Every new fact or rule has a real verified-by. It names a test as tests/<file>.py::<function> that exists, a verifier file that exists, a script, or none (<reason>) with the reason copied from the test report. No pending remains anywhere once the disposition is filled; the integrity test enforces this and the request cannot end otherwise.
• Every operation under for-orchestrator was applied. Each id the update agent listed now carries the status, superseded-by, confirmed or scope key the operation calls for, and each superseded entry points at an active successor. Nothing was deleted or reordered to do it.
• The disposition names every id and path that was created. Cross-check against the three reports: every admitted entry id, every test path, every verifier path and every update id appears, and nothing that was not created appears. not kept carries the reason.
• The suite is green after the footprint was regenerated. python scripts/footprint.py --write ran before python -m pytest -q tests, every test passed, and the regenerated artifact passes the new feedback test. No test was edited, skipped or deleted during the handling.

Output

One paragraph in the request report: the FB id, what was kept and in which files, which tests or verifiers now check it, which existing entries changed status and to what, what was dropped and which admission check it failed, and any conflict between the reports and how it was resolved. The paragraph cites ids, so the owner can open each one.

Runtime behavior

• Runs inside the main request, immediately when the feedback arrives and before any further generation on the same artifact, so the next generation already uses the new memory.
• Does not commit. The end-of-request footprint commit records the change with the delta in its message, which is how the owner sees the memory footprint move.
• Never rewrites a memory file whole. Append entries, edit metadata lines in place, and replace the FB entry's disposition: line in place; the files are shared with the subagents and with past entries, and a whole-file rewrite is how memory gets lost.
• Launches subagents in parallel where the harness allows and waits for all three before stitching. A subagent that fails or times out is launched again with the same inputs; its partial writes are reviewed through git status first.