okf-principles

okf-principles

Restructures instruction artifacts so an agent loads only what a question needs. The measured payoff is the tail, not the average: a split bounds the worst-case context per question and removes the cheap confident wrong answers blind scrolling produces - mean bytes may rise slightly, and that is not a failure. This file is the index: read the one principle file the task calls for, not all five.

The five principles

• Index first - the reader decides what to load, so structure must be inspectable before it is consumed. Read when splitting a monolith, writing an index, or indexing a vendored or generated file you cannot edit.
• Keyed identity - references are keyed, never positional, because agents rewrite. Read when adding rule IDs or fixing cross-references before a file move.
• Permissive reading - partial structure must still work. Read when writing reader-side instructions or migrating incrementally.
• No tooling required - plain text that survives being read as prose. Read when tempted to add a format, schema, or parser.
• Kind over location - a file declares what it is; folders are free to change. Read when organizing directories or labeling index entries.

Procedure for restructuring an existing skill

1. Inventory: list every file, its line count, and what questions it answers. A file answering unrelated questions is a split candidate. Mark any file that is vendored, generated, or third-party: those are never split - they get an index beside them instead (see rule ss-index-beside-foreign).
2. Split along question boundaries, not size. Each resulting file should answer one family of questions (per verb, per workflow, per format).
3. Write the index per index-first. Every entry needs a description an agent can route on, and coverage must match the index's claim - especially for an index promoted from inside a file, which inherits its old host's narrower scope silently (rule ss-coverage-matches-claim).
4. Key every rule worth citing per keyed-identity, then repoint existing cross-references at keys instead of paths and section names.
5. Add reader guidance per permissive-reading so a half migrated state stays usable.
6. Verify against the anti-goal with a fixed question set, judging the worst question rather than the mean (rule ss-measure-worst-case): one that loads more files or bytes than before names the boundary to merge back. Where a topic moved between files, leave a pointer at the old seam (rule ss-seam-pointers).