Feedback engineering

An observed agent failure becomes a check so the next occurrence is caught without your attention. Pick the carrier that fits the failure's constraint, prove what you changed, and record where the rule lives.

Reuse first. Before writing anything, search for an existing rule that can carry the constraint: an ESLint restricted-imports or custom rule, a type narrowing, an existing CI step, a test-utility assertion, a skill body, or a line in the project's root instruction file. Extending an existing rule beats adding a second mechanism that can drift from the first. See implementation.md for worked examples and the source evidence.

Choose the mechanism

Pick the carrier by what the failure actually is; each carrier constrains different properties, so the fit decides, not a cost ladder:

1. Type — the failure is an invalid shape a compiler can reject. Makes that state unrepresentable; it constrains what the compiler accepts, not runtime behavior.
2. Lint rule — the failure is a mechanical pattern across many files (custom rule when no built-in rule fits; see implementation.md for the source's custom-rule economics). Only a real check once you verify the configured invocation actually loads it, at a severity that fails the run.
3. Test — the failure is runtime behavior; assert the specific symptom, not "doesn't crash".
4. CI step / script — the failure needs repo-wide or cross-service state checked at a fixed gate.
5. Root-instruction line or skill — the failure is a judgment call needing context; these steer attention and they do not enforce by themselves.

False positives: prefer a check with legitimate exceptions handled explicitly (allow-lists, targeted suppressions) over no check. A new false positive is a diagnosis task — narrow the pattern or record a justified exception — not a reason to delete the rule. Do not claim a rule that fires on correct code is always worse than no check; that trade-off is judged per case.

Proportionate proof. An instruction-only change needs a wording review (read the new line back against the observed failure and inspect selected loading when affected); an executable change (lint rule, test, script) uses test-first sequencing at the existing behavioral boundary: first show the prohibited case currently slips through, then implement the smallest correction and prove that case is blocked while a known-good case passes. Reuse adequate existing checks. Recurrence is the normal trigger, not a quota: a single defect justifies a guard when the user explicitly asks for one.

Input / output contract

• Input: the observed failure and its evidence, and the repo where the check will live. Recurrence across runs or an explicit user request establishes that a standing check is wanted; infer fitting scope from the failure rather than asking.
• Output: (a) the rule or check added, (b) the proof proportionate to the mechanism per above, and (c) one line in the project's existing convention record saying what the rule enforces and why.

Acceptance

Proportional to the work: a one-line instruction change needs the wording reviewed against the recorded failure; a custom lint rule needs its fixtures (failing + passing) run and a green run of its tests, with the lint invocation confirmed to include the new rule.

Known failure cases

• Encoding a one-off as a permanent rule without a user request (noise forever).
• Assuming a rule is enforced because it is written: verify the selected invocation, severity, and config actually load it. A rule in a config no script runs is documentation, not a check.
• Suppressed or any-escaped checks that make the rule green without changing behavior.

Do not activate when

• The failure happened once and the fix is the task itself (unless the user explicitly asked for a guard).
• The user wants a bug diagnosed (use a bug-diagnosis skill).
• The request is general refactoring with no observed failure behind it.

Source patterns

For concrete repository examples and the limits of their evidence, read source-patterns.md when they match the task. These are research references, not imported repository instructions.