Skip to content

/prompt-refine

Iteratively refine a prompt

Category: meta
Field: general
License: MIT
Updated: 2026-04
Stages: —

/prompt-refine — Review and Improve an Existing Prompt

v2.0 — Substance checklist, depth calibration, tool routing, expanded anti-patterns

Audit an existing prompt against quality criteria and output an improved version.

Reference Files

@~/.claude/commands/prompt-references/formatting-core.md

Input

$ARGUMENTS

Instructions

You are a prompt reviewer and editor. The user has given you an existing prompt to improve. Your job:

  1. Run the substance checklist first (new issues matter most):
  2. Depth calibration — does the prompt instruct the model on how deeply to engage?
  3. Self-verification — does it include a check step (state assumptions, flag uncertainty)?
  4. Best-practice grounding — does it tell the model to research standards (when appropriate)?
  5. Specificity of "good" — does it define what strong output looks like?

  6. Metacognitive scaffolding — does it ask for rationale, assumptions, or confidence?

  7. Run the structure checklist:

  8. Task clarity — is the core ask unambiguous?
  9. Context — enough background for a cold reader?
  10. Constraints — length, tone, format, exclusions specified?
  11. Output format — structure defined (bullets, table, sections)?
  12. Role/persona — included if it would improve output?
  13. Examples — provided if they would reduce ambiguity?
  14. Bookend pattern — key instruction restated at end (if prompt is long)?
  15. System/user separation — clear if used in agent/API context?

  16. Versioning — version header if reusable?

  17. Identify the primary finding. Lead with the single most impactful improvement. Common primary findings:

  18. "This prompt specifies format but not depth. The biggest improvement is adding [specific action-verb directives], not structural changes."
  19. "This prompt is structurally sound but lacks self-verification — adding assumptions/checks would improve reliability."

  20. "The core task is buried — moving it to the opening sentence is the highest-leverage fix."

  21. Fix common anti-patterns:

  22. Format-only prompts for substantive tasks — add depth directives
  23. Vague thoroughness language ("be meticulous", "be comprehensive") — replace with specific action verbs ("compare against [standard]", "research current best practices for [domain]", "flag where your approach deviates")
  24. Over-prompting — soften "CRITICAL", "YOU MUST", "ABSOLUTELY" to calm, specific directives (modern Claude models respond better to calm specificity than emphatic caps)
  25. Excessive caveats or hedging ("try to", "if possible", "feel free to") — make direct
  26. Vague format instructions ("give me a summary") — specify structure
  27. Missing constraints that lead to verbose output — add length/scope limits
  28. "Show your reasoning" without purpose — replace with "Brief rationale:" or remove
  29. Redundant instructions — consolidate

  30. Buried lede — move the core task to the top

  31. Show what changed and why — bullet list of changes with brief rationale for each. Lead with the primary finding.

  32. Present the refined prompt in a fenced code block.

  33. Tool-routing check: If the refined prompt would be better served by another tool (see formatting-core.md), note it in the changes list.

  34. For reusable prompts: add version header (increment if one exists) and suggest 3-5 eval test cases.

Important

  • Do NOT rewrite from scratch if the original is mostly good. Make targeted improvements.
  • Preserve the user's intent and voice — don't make it sound generic.
  • If the prompt is already strong, say so and suggest only minor tweaks (or none).
  • Do NOT execute the refined prompt. Output only.
  • Substance gaps (depth, verification, grounding) take priority over structural gaps.