git:20261011.042ae70 to git:20261012.0cb79b5
1 added, 18 removed. Audit A to A.
---
name: principle-encode-lessons-in-structure
description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text."
---
# Encode Lessons in Structure
- Encode recurring fixes in mechanisms (tools, code, metadata, automation) instead of textual instructions. Every error, human correction, and unexpected outcome is a learning signal. Capture it, route it, and close the loop.
-
- Textual instructions are easy to miss. Structural mechanisms enforce the rule without cooperation.
-
- **Pattern:**
- When you catch yourself writing the same instruction a second time:
- 1. Ask: can this be a lint rule, a metadata flag, a runtime check, or a script?
- 2. If yes, encode it. Delete the instruction
- 3. If no (requires judgment), make the instruction more prominent and add an example of the failure mode
-
- **Pick the strongest mechanism.** When more than one mechanism would work, choose the strongest the situation allows (an unrepresentable state that cannot compile, then a lint or banned API that fails CI, then a canonical helper, then a runtime check), because agents copy whatever the surrounding code already does and a weaker guard becomes the next template.
+ If the lesson needs judgment and cannot be encoded, make the instruction more prominent and add an example of the failure mode.
**Corollary:** If the fix is structural, only use the structural fix. The instruction is the symptom.
-
- When the human intervenes or tests fail, decide if it's a one-off or a pattern. Route it: one-off -> brain note, recurring fix -> skill or lint rule, systemic issue -> principle. Close the loop: don't just record; apply now or create a concrete todo.
-
- **Anti-patterns:**
- - Acknowledging without recording ("I'll keep that in mind" does not persist)
- - Recording without routing (a brain note about a lint rule that should exist is wasted unless the lint rule gets implemented)
- - Fixing without generalizing (fixing one instance while leaving the recurring pattern intact)