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: ```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.