Refine Prompt

A prompt is a program written for a model. Refining one is not editing for style - it is predicting where the draft will make the model do something generic or lazy, and replacing that spot with a mechanism that forces the behavior you actually want. The governing idea: vague words optimize for the wrong thing. "Ask many questions" optimizes question count; "cover every fork" optimizes coverage. Same intent, and only one of them is executable.

Scope gate - pick the depth before you start

The scope gate matters because the full method has real cost (reading artifacts, building a simulation table). Spending it on a one-line tweak is the same mistake as "be thorough" - effort pointed at the wrong thing.

The method: Gather -> Diagnose -> Rewrite -> Verify

1. Gather

• Read the referenced artifact first - when one exists, reading is proportionate, and the user hasn't declined. Extract the real fork points, latent bugs, and honest constraints, then enumerate them by name in the prompt. A named decision can't be silently skipped; "leave no stone unturned" is an exhortation, "resolve these 7 decisions" hands over the actual stones. No artifact / too large / user declined -> enumerate assumptions in the prompt instead.
• Front-load context. Put a one-paragraph summary of the target artifact inside the prompt itself, so it survives being pasted into a fresh session and the model orients before its first tool call.
• Preserve the user's intent skeleton. Note every goal in the original. The refined prompt is the original compiled, never replaced - each goal must map to a mechanism, and no new scope gets invented.

2. Diagnose - simulate, don't judge

Build a table, one row per thing the model must act on - merge rows sharing a fix, cap it at 12, and note any remainder in one line:

Fill the middle column by role-playing a literal, slightly-lazy model - not the ideal reader you hope for. If a row predicts generic behavior (filler clarifying questions, restating the goal back, hedged "it depends" non-answers, offloading reading onto the user), mark it for rewrite. You are cataloguing predicted failures, not stylistic preferences - this is what gives the Verify step something concrete to check.

Consult the smell table below to name each failure and its fix.

3. Rewrite - swap smells for mechanisms

Rewrite every flagged row using the matching mechanism from the smell table. Keep the prompt lean: a mechanism that doesn't change predicted behavior is dead weight, cut it.

4. Verify - re-simulate the rewrite

Re-run the simulation table against the refined prompt. Iterate until no row predicts filler, capped at 3 rounds; at the cap, ship it and list the rows still predicting filler as stated known-weak spots. A rewrite is an unverified hypothesis until you do this. Then deliver:

1. The refined prompt.
2. A short change table: original phrase -> predicted failure -> mechanism applied. This makes the refinement itself checkable by the user, rather than a black-box "trust me".

If Diagnose flagged nothing, deliver the null verdict instead - an empty change table means there was nothing to compile.

Smell table - the core substitutions

The recurring failure patterns and what to replace them with. This is also the entire toolkit for a quick tweak (scope gate row 2).

Worked micro-example

Input row: "Ask the user as many clarifying questions as possible before starting."

Diagnose: model will generate a long list of shallow questions, many answerable from the spec, to look thorough. Optimizes count. No stop condition.

Rewrite: "Read SPEC.md. For each genuine fork you find, ask one question grouped with its siblings by theme, each with your recommended default and a one-line why. Anything answerable from the spec, answer yourself and cite the line. Stop when no material ambiguity remains; if you hit 3 rounds, list any leftovers as assumptions and proceed."

Change table row: "as many questions as possible" -> shallow filler optimizing count -> themed batches + defaults + anti-laziness valve + stop condition + round cap.

Saving the result (optional)

By default the refinement is delivered to chat only. When the user asks to save it ("save this", "write it to a file", "save to <path>"), also write the result to a markdown file - this applies whether the run used the full method or a quick tweak.

• Where. Default to .claude/prompts/ in the current project (create the directory if missing). If the user names a path or directory, use that instead.
• Filename. YYYY-MM-DD-<slug>.md, where <slug> is a short kebab-case name derived from the prompt's purpose (e.g. 2026-07-27-triage-agent-prompt.md). If that file already exists, append -2, -3, etc. - never overwrite.

• Contents. A single self-contained markdown document:

  # <title from the prompt's purpose>
  
  Refined <date> with refine-prompt.
  
  ## Original prompt
  
  <the prompt as received, verbatim>
  
  ## Refined prompt
  
  <the refined prompt>
  
  ## Changes
  
  <the 3-column change table from Verify>

  The file includes the original prompt even though the chat deliverable does not, so the before/after stays auditable once the chat is gone.

• After writing, report the path. Still show the deliverable in chat unless the user asked to save only. On a null verdict there is nothing to compile - say so and write no file.

Reference

references/principles.md - the rationale behind each mechanism, and which ones carry the most weight. Read it when a mechanism's fit is unclear or you are extending the smell table.