/prompt-principles

name: prompt-principles
description: 'Prompt principles for manifest-dev: how its maintainer wants the shipped skills, references and other prompts written and checked, and why. Use before planning, writing, restructuring, reviewing or verifying a change to a prompt, a skill or an agent in this repository.'

Edit rule: each line is a principle with its reason and when it yields. Decisions go to the decision records, rules a check can hold go to the check, and a line is added only on a person's yes, after sharpening an existing line is ruled out.

• Show a prompt change working by driving the behavior cases it touches, new or existing eval cases, through `scripts/verify drive` — a case the change must catch and one where it must not fire, under a pass rule fixed before the runs — rather than asking the maintainer to judge the words — the maintainer judges a prompt change by what it makes a run do, and a drive is the evidence they rely on; a suite that rewards one direction pulls later tuning further that way; a whole eval suite runs only when they ask, because each run is many paid sessions. Where the change adds something that runs on every use, report each arm's cost and wall time beside its verdict. Yields when the text must be approved as written, such as a public post, or when no case can reach the behavior; then say so.
• Settle a prompt change on one run per arm and accept the noise: each touched case once on the skills before the change and once after, adding runs only where that pair does not settle it — a must-catch case passes or fails on both arms, or a verdict is borderline — every run is a paid model session and more runs get expensive, while one pair is good enough once its noise is accepted. Yields when the decision would be costly to reverse and rests on one borderline pair, or when the maintainer asks for a fuller measurement.
• When a skill grows a flag or a mode, keep what every invocation needs inline in `SKILL.md`, move that mode's bulk to a file under `references/` loaded only when the mode resolves, and keep the trigger in `SKILL.md`, written as an instruction on an event the run can observe, in a `Modes` or `What loads` table beside the flags; after adding a reference, check that the default path reaches it — otherwise the default invocation carries the whole file to use a fraction of it, and a trigger inside the deferred file can only be read after the load it was meant to gate; a passive mention or a bare pointer does not load, and the miss is silent. Yields when a mode's mechanics run to a paragraph: an indirection costs a load and a reader's place, and can strand a subtle trigger.
• A shipped skill carries its own copy of every term, step, rule and probe its behavior depends on, defined where it first uses it, and defers none to the glossary, another skill, its caller, a host-shipped skill or a section a reader may never reach — a skill installed in someone else's project gets its own `SKILL.md` and the references its loading layer names, never this repository's `CONTEXT.md`, and the misses were found on standalone runs: a completion path named a skill that did not ship; `figure-out`'s gloss of *fog* at first use is the pattern. Yields for plain words that carry no project meaning, and inside one skill or between files a run loads together: there a rule has one owning section and the others point to it, because copies drift — one review found 29 defects, most of them one rule changed in one file while another still stated the old one.
• A shipped skill names the capability it needs, never how one setup reaches it — a fixed path, a tool list, an API or MCP server, another CLI — and says nothing only this repository needs — everyone has a different setup, and the skills run on other harnesses. Hard limit, no trade-off.
• A shipped prompt states what the work owes, the maintainer's rulings, what a run cannot read elsewhere, and corrections of defaults a run was seen to take; how to get there is the run's, and the text holds nothing its own reader does not act on — no account of what a caller, a sibling skill or an earlier version owns. A thin result is the correct one — spelled-out method spends attention on every run, overfits it to one path and holds a better model to today's method. Yields when a drive or session shows a run missing something: it goes back in as an outcome, not as steps.
• When a shipped rule is stated and still broken, do not state it more firmly or add a sibling beside it: replace the failed text with something a run can execute and a reviewer can check (a shape, a named standard, a bound with a rule for what to cut), make it a gate or a check, remove the choice, or give the output one cold reading by a context that did not write it — models comply reliably with a concrete output shape and unreliably with quality adjectives, and more words in a layer nothing verifies change nothing. Yields when output reads as padded to fill the shape: then the shape is the suspect.
• Where a prompt needs a call made, name what to weigh and let the model judge; do not stand a size threshold, a per-mode matrix, a closed list, a fixed template, a required tool or a numeric score in for the judgment, and correct a model's default by naming the specific pattern, as a default it may still choose — stand-ins are brittle and game-able, force-fit the novel case and claim precision nobody has, and a general exhortation only swaps one default for its neighbour. Yields when a prose hint was seen to make a model invent the mechanism (then give the literal action), and when an interaction grammar must survive intact (then ship an executable example).
• Write a prompt's limits so they do not rest on the reading model's temperament: a loop pushed against stopping early states the condition at which it stops, a bar says what a finding must name to count, and a property that decides behavior is declared, never inferred — the prompt that corrects one model's bias ampl