The Prompt Fixer That Diagnoses Before It Rewrites

Paste a flawed prompt into almost any “prompt optimizer” and you get the same move: your prompt goes into a magic template — 4-D framework! 27 patterns! — and comes back longer, restructured top to bottom, with no record of which change mattered or whether it still does the same task. It reads better. Whether it works better is a separate property, and the tool never checks.

We run a directory that bench-tests Claude skills for a living, and we wanted the opposite of that. So we built prompt-discipline, and it treats a prompt the way you’d treat a bug report: name the failure mode first, apply the smallest fix that addresses it, then say exactly how to A/B the change. It’s free and MIT-licensed: github.com/Skillproofdev/prompt-discipline.

The gap: rewriters don’t diagnose, diagnosers need infrastructure

Before writing a rule we surveyed 43 prompt-engineering skills in our catalog plus the standalone tools — Anthropic’s own Console prompt improver, PromptPerfect, DSPy, getsentry’s prompt-optimizer. The field splits into two camps that never overlap.

Template rewriters transform every input the same way. There’s no step that asks what is actually wrong here — a vague prompt and a contradictory prompt get the same treatment, and the output is reliably longer. This isn’t a strawman: Anthropic’s own Console improver openly warns that its rewrites come out longer and slower. Longer is the product.

Eval-first pipelines — DSPy, trace-driven optimizers — have the right epistemics. They actually measure. But they need infrastructure: production traces, an MCP server, a worktree harness, a labeled dataset you assemble first. You don’t reach for them to fix the prompt you’re editing right now.

Nobody packages the middle thing: a dependency-free skill that does diagnosis-first → minimal-diff → A/B test plan, with no traces and no server to stand up. That gap is the whole skill.

Nine rules, three of them the point

The skill is a set of hard rules applied in order (full SKILL.md). The familiar parts are there — output format as a positive contract (a key list with types, not “respond in JSON”), examples over adjectives, do-not-lists rewritten as do-instructions, role→data→instructions→examples→query ordering. The three that define it:

1. Diagnose before you touch anything. Classify what’s actually wrong — ambiguity, missing context, no output contract, conflicting instructions, format-drift risk, over-prompting, or “not a prompting problem at all” — and quote the offending span for each finding. No diagnosis, no rewrite. “This prompt is fine” is a valid, complete output.
2. Minimal diff, one change per failure. Every edit maps to exactly one diagnosed failure, shown as old → new with a one-line rationale. Working parts stay verbatim. Where the Console improver pads, this one usually comes out shorter — dead incantations (“you are the world’s best…”, “take a deep breath”, stale “think step by step” scaffolds) get cut.
3. A test plan, not a promise. Every rewrite ships with 2–3 concrete test inputs including an edge case, what a pass looks like, and the A/B procedure: same inputs, same model, 3–5 runs each, compare pass rates. If edits were stacked, it names which one to revert first. It never promises “this will fix it” — you changed variables; the test decides.

The benchmark — and a caveat you need first

Ten genuinely flawed prompts, each paired with a task that has a mechanically checkable answer: extraction against known ground truth, formatting that must parse (json.loads / csv.reader), classification against labeled examples. Three arms per case — the original prompt, a base rewrite (plain Claude told “improve this prompt”), and a skill rewrite (identical session with this SKILL.md loaded). All rewrites then run as tasks on the same model.

Read this before the table: the run is n=1 per case per arm, not the pre-registered n=5. Sampling variance is unmeasured. Any single-case gap (0.1) is inside the noise floor. Treat every number here as provisional pending an n=5 replication — we do.

Arm	Task success	Format-compliance	Median prompt-length Δ
A — original prompt	0.70 (7/10)	0.70 (7/10)	—
B — base rewrite (“improve this prompt”)	0.80 (8/10)	0.70 (7/10)	+99.5 words
C — skill rewrite (this SKILL.md)	0.90 (9/10)	0.80 (8/10)	+44.5 words

Against the pre-registered test the skill passes: it ties-or-beats the base rewrite on success (0.90 ≥ 0.80) and compliance (0.80 ≥ 0.70), clears the +15 pp bar over the original (+20 pp), and does it while adding less than half the prompt bloat — median +44.5 words vs the base rewrite’s +99.5. That last number is the most robust finding in the whole run: C is leaner on all ten cases, and it’s the only arm that ever goes negative (case-10, −10 words, cutting a prohibition pileup out of a system prompt). Both naive rewriting and disciplined rewriting inflate terse prompts; the naive one roughly doubles the cost.

Where it’s thin, and where it lost

The success and compliance edges are real but fragile, and we’re not going to pretend otherwise.

On 7 of the 10 cases, all three arms tie. The success margin rests almost entirely on case-06 (ticket classification), the only case the skill wins outright: C produced correct, per-item-parseable labels (15/15) while the base rewrite got 13/15 in a format that wouldn’t parse. Pull that one case and the top-line gap mostly evaporates. That’s what n=1 with a lot of ties looks like — honest, not damning, but you should know it.

Case-09 is a loss for the skill on its own terms. A tone-fix prompt with a missing audience — exactly the situation Rule 2 exists for (“state your assumption when intent is undecidable”). The rule didn’t fire. The skill’s rewrite dropped the missing-audience problem, and C failed alongside A and B. A skill losing at the thing it’s specifically designed to catch is the most useful kind of negative result, so it stays in the table.

Case-02 compliance is 0 across all three arms. A prompt with contradictory instructions: every arm resolved the contradiction in content (got the right number) but none forced a single-value output, so all three scored 0 on format. Neither rewriter — disciplined or not — thought to enforce the contract. Shared blind spot, reported not hidden.

We test other people’s skills for a living, and our methodology requires the losses next to the wins. These are the losses.

Install

git clone https://github.com/Skillproofdev/prompt-discipline ~/.claude/skills/prompt-discipline

Restart Claude Code. It triggers on “improve this prompt”, “why does my prompt fail”, “optimize prompt”, and when you’re writing or revising system prompts and agent instructions — and it declines jailbreak/safety-bypass requests and image/video-generation prompts, which have their own grammar. It joins our discipline series: token-discipline cuts what a session costs, research-discipline cuts what research gets wrong, and this one cuts prompt rewrites down to the change that actually mattered.

FAQ

How is this different from Anthropic’s Console prompt improver? The Console improver is a template rewriter — it restructures the whole prompt and openly warns the result comes out longer and slower. prompt-discipline diagnoses the specific failure first, changes only what maps to that failure, and in our benchmark added less than half the length while usually coming out shorter. Different goal: the Console tool produces a polished prompt; this one produces the smallest defensible diff plus a way to prove it.

Why publish a benchmark you admit is n=1? Because the alternative in this niche is publishing no numbers at all, which is the norm we’re reacting against. n=1 with the caveat stated plainly is more honest than a confident claim with no measurement behind it. The median-length finding is solid across all ten cases; the success and compliance edges are provisional and labeled as such, pending an n=5 replication.

Does it always rewrite my prompt? No. If the prompt is fine, the skill says so and stops — “this prompt needs no changes; here’s the one risk to test” is a valid, complete output. It also refuses to pad a diagnosis just to justify applying a template, and it declines jailbreak requests outright rather than “improving” them.

Will this fix my prompt? It won’t promise that, and neither should any tool that hasn’t run your task. The skill changes variables and hands you a concrete A/B procedure — same inputs, same model, 3–5 runs — so the test decides, not the vibe of a cleaner-looking prompt.