Feedback Learning

---
name: feedback-learning
description: Classify and record explicit corrective feedback without turning skills or instructions into append-only knowledge dumps.
---

# Feedback learning

Use this skill when a user explicitly corrects an implementation or design approach, rejects a pattern, or asks the agent to learn from feedback, except when the user invokes the literal `learn!` trigger.

Literal `learn!` requests are governed exclusively by `.github/instructions/learnings.instructions.md` and are outside this skill's scope. Do not replace or reinterpret that instruction.

## Goal

Preserve reusable knowledge in the smallest authoritative artifact. A correction is not automatically a permanent rule.

## Workflow

1. **Identify the correction**
   - What was wrong?
   - Why was it wrong?
   - What approach did the user prefer?
   - Which paths or subsystem does it affect?

2. **Search before writing**
   - Check applicable instructions, skills, design documents, tests, and scoped
     learning files.
   - Update an existing rule instead of adding a duplicate.

3. **Classify the feedback**

   | Feedback kind | Destination |
   |---------------|-------------|
   | Task-specific preference or one-off adjustment | Do not persist |
   | Concrete behavior that must not regress | Regression test |
   | Stable subsystem architecture or product invariant | Relevant design/specification document |
   | Universal repository rule | Applicable instruction file |
   | Reusable but not yet mature or proven guidance | `.github/learnings/<area>.md` |
   | Tool-driven workflow | Relevant skill |

4. **Generalize carefully**
   - Preserve the principle, not the incident chronology.
   - Do not include temporary symbol names, line numbers, or implementation
     details unless they define the durable contract.
   - Do not turn a single rejected implementation into a universal prohibition
     without broader evidence.

5. **Record once**
   - Design documents and tests are authoritative.
   - A learning inbox entry is temporary. When promoted, remove the inbox entry
     in the same change.
   - Never copy the same rule into a skill, instruction, and design document.
   - Before adding an inbox entry, compact the target file using the maintenance
     rules below.

6. **Validate**
   - Confirm the destination applies to the affected path.
   - Check links and remove superseded or contradictory guidance.

## Learning inbox format

Create or update `.github/learnings/<area>.md` using:

```markdown
# Area learning inbox

Last reviewed: YYYY-MM-DD

## Short topic

- **Scope:** `affected/path/**`
- **Learning:** Generalized guidance in one or two sentences.
- **Evidence:** Why this is reusable beyond the current task.
- **Disposition:** Candidate for `<design document, instruction, skill, or test>`.
```

Keep entries concise. Each area inbox is limited to ten topics and 8 KB. If a new entry would exceed either limit, promote, merge, or remove existing entries before deciding whether the new feedback deserves persistence.

## Reading learnings

Do not inject learning inboxes into every task. Search the relevant file's headings and `Scope` fields first, then read only matching entries. Learning inboxes supplement source code, tests, and design documents; they are not a prerequisite for unrelated work and are not authoritative over them.

## Compaction and garbage collection

Compact an inbox before every write. Also perform a full review when an inbox is at either limit or its `Last reviewed` date is more than 90 days old when read. During review:

- promote stable architectural guidance into the owning specification;
- encode concrete behavior in tests;
- merge overlapping entries into one general principle;
- remove obsolete, contradicted, already-promoted, or weakly supported entries;
- update `Last reviewed` after checking every retained entry against the current source and authoritative documentation.

An inbox may shrink to zero entries. Do not retain a learning merely because it might be useful someday.