serradura/okf/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).

1. Split along question boundaries, not size. Each resulting file should

answer one family of questions (per verb, per workflow, per format).

1. 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).

1. Key every rule worth citing per

keyed-identity, then repoint existing cross-references at keys instead of paths and section names.

1. Add reader guidance per

permissive-reading so a half migrated state stays usable.

1. 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).

Anti-goals

Do not port machine-oriented metadata (trust tiers, provenance chains, attestation, changelogs) into a skill. Those solve multi-agent corpus problems; a skill has one author and lives in version control. Do not add frontmatter keys beyond what the host harness defines unless a machine must read them; prefer expressing structure in the index body, which no harness parses. <!-- rule: ss-no-ceremony -->