feedback-learning

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:

# 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.