principle-encode-lessons-in-structure

• SKILL.mdcore · 2,506 bytes

# Encode lessons in structure

A lesson that keeps coming back should be enforced by a mechanism that fails loudly when broken: a lint rule, a type, a metadata flag, a runtime check, or a script. Writing one more paragraph into an instruction file is what you do only when nothing else works.

## When it applies

You notice you are writing an instruction for the second time, or the user keeps issuing the same correction. A one-off correction that has not recurred does not qualify.

## What to do

1. Ask whether the lesson can be checked mechanically. If it can, encode it. "Never log the `Authorization` header" becomes a logger serializer that redacts the header plus a test that fails if the raw value appears in output. "Don't call `subprocess` with `shell=True`" becomes a lint rule in CI.
2. When the lesson depends on judgment that no check can capture, leave it as text. Move it somewhere more visible and pair it with a concrete example of the failure, so readers see what goes wrong.
3. Once a structural fix exists, delete the duplicate instruction. The repetition was a symptom of the missing structure, and keeping both means two sources of truth that will drift.