Update to Headcount: Technology

{
  "description": "Turns rough intent or a weak prompt into a reliable one — diagnosing why output is inconsistent, restructuring the instruction, and adapting it across models. Use this when a prompt is not producing what was wanted, when output varies run to run, when writing a prompt for a repeated task, when moving a prompt between models, or when someone describes what they want an AI to do and needs it written properly.",
  "included_files": [],
  "name": "prompt-optimizer",
  "skill_md_contents": "---\nname: prompt-optimizer\ndescription: Turns rough intent or a weak prompt into a reliable one — diagnosing why output is inconsistent, restructuring the instruction, and adapting it across models. Use this when a prompt is not producing what was wanted, when output varies run to run, when writing a prompt for a repeated task, when moving a prompt between models, or when someone describes what they want an AI to do and needs it written properly.\n---\n\n# Prompt optimizer\n\n## Diagnose before rewriting\n\nBad output has a small number of causes, and the fix differs entirely by cause:\n\n- **Underspecified** — the model is guessing at something you know. Most common by far.\n- **Overspecified** — so many constraints that they conflict, and the model satisfies some\n  arbitrarily.\n- **Wrong shape** — asking for a paragraph when you want a table, or a decision when you want\n  options.\n- **No success criterion** — nothing in the prompt says what good looks like, so quality varies with\n  nothing.\n- **Buried instruction** — the actual task is in the middle of context and gets weighted like\n  context.\n- **Genuinely hard** — the task needs information the model does not have, and no prompt fixes that.\n  Say so rather than iterating.\n\nRead the actual bad output before rewriting. The failure mode names the cause.\n\n## What reliably helps\n\n- **Say what to do, not what to avoid.** Negative instructions are weaker than positive ones and\n  often summon the thing named.\n- **Give the shape of the output** — the sections, the length, the format. If format matters, show\n  an example rather than describing it.\n- **Provide one worked example** where the task is judgment-heavy. Examples carry more instruction\n  per token than description does, and one good one beats three mediocre.\n- **State the audience and purpose.** \"For a technical reader deciding whether to adopt this\" changes\n  the output more than most adjectives.\n- **Ask for reasoning before the answer** on analytical tasks — order matters, since a conclusion\n  stated first is defended rather than derived.\n- **Give an out.** Tell it what to do when the input is insufficient, or it will invent something.\n\n## What does not help\n\nPoliteness, threats, incentives, insisting on importance, and stacked superlatives. These consume\ntokens and change little. So does repeating an instruction in three phrasings — it usually signals\nthe instruction is unclear rather than reinforcing it.\n\n## Structure\n\nPut the task first, context second, and any output format last where it will be closest to\ngeneration. Long context between instruction and output is where instructions get lost.\n\nFor repeated prompts, separate the fixed instruction from the variable input explicitly, so the\nmodel can tell which is which.\n\n## Testing\n\nA prompt is not done because one run looked good. Run it three to five times on the same input and\nlook at the variance — that is the actual quality. Then run it on the awkward inputs: empty, far too\nlong, ambiguous, adversarial.\n\nFix the worst case, not the average. The average is what you see in testing; the worst case is what\nyour users see.\n\n## Producing variations\n\nWhen a prompt matters enough to optimize, produce genuinely different versions rather than variants\nof one phrasing:\n\n- **Terse** — instruction only, minimal framing. Often outperforms, and it is cheapest.\n- **Structured** — explicit sections, numbered constraints, defined output shape.\n- **Exemplar-led** — one worked example carrying most of the instruction.\n- **Role-framed** — audience and stance set before the task.\n\nTest all four on the same inputs. Which wins is genuinely hard to predict, and the intuition that a\nlonger prompt is better is wrong about as often as it is right.\n\n## Scoring output\n\nJudge against criteria written before seeing results, or you will rationalize whatever came back.\nFor most tasks: did it do the task, is it correct, is it the right shape and length, is it usable\nwithout editing. Score each run rather than forming an overall impression — impressions are\ndominated by the best run, and the worst run is what matters.\n\n## Moving between models\n\nDo not assume a prompt transfers. Models differ in how they weight system versus user instruction,\nhow they handle long context, and how they respond to formatting. Re-test on the target model, and\nbe especially suspicious of prompts tuned through many small iterations — those are often fitted to\none model's quirks.\n\n## Never\n\n- Rewrite a prompt before reading the failing outputs. You will fix the wrong thing.\n- Change more than one thing between test runs.\n- Judge a change on a single output. Sampling variance will fool you.\n- Keep an instruction because it was already there. Every line has to earn its tokens.\n"
}