prompt-doctor

prompt-doctor

Overview

Pre-flight critic for user prompts. Diagnoses the 5 dimensions agents need to execute well: scope, metric, baseline, subject, success criterion. Proposes a sharper version. Optionally learns the user's stylistic patterns over time (learning mode).

Core principle: a prompt is executable when an agent can decide unambiguously what counts as "done". If any of the 5 dimensions is missing or implicit, the agent has to guess — and will guess wrong.

When to Use

Use when:

• User pastes a draft prompt and asks for critique
• User invokes /prompt-doctor "<draft>" explicitly
• User says "this prompt is too vague / basic / weak", "make this sharper", "antes de mandar esto..."
• A user message arrives that is itself a vague task request (stream-of-consciousness, missing scope/criterion) — propose invocation: "Your prompt looks vague. Run it through /prompt-doctor first?"

Do NOT use when:

• User wants execution, not critique ("just do it")
• Prompt is already well-scoped (skeleton fully satisfied)
• User is asking a simple factual question, not requesting agent work

The 5-Dimension Skeleton

Every executable prompt answers these. If a dimension is N/A, say so explicitly — "no baseline" is a valid answer; silence is not.

#	Dimension	Question	Example answer
1	Scope	What is in, what is out?	"Refactor auth.ts only. No changes to callers."
2	Metric	How is success measured?	"All existing tests pass + lint clean + diff < 200 lines"
3	Baseline	Compared to what?	"vs. current implementation on master" or "no baseline"
4	Subject	Who/what is the context, persona, or target?	"senior Go dev reading this in 6 months" or "this codebase, Node 20"
5	Success criterion	When do you stop?	"When tests pass and I approve the diff"

Domain Detection

Detect domain from keywords in the draft, then apply the matching template's checklist on top of the 5-dimension skeleton.

Domain	Trigger keywords (any language)	Extra checklist
Coding	implementa, testea, debug, refactoriza, fix, build, deploy, ship, write code, escribe función	+ Target files/modules, + Test strategy (unit/integ/e2e), + DoD (Definition of Done)
Analysis	compara, analiza, evalúa, audita, revisa, observa, compare, audit, review	+ Axes of comparison, + Weights/priority, + Output format (table/report/verdict)
Writing	escribe, redacta, paper, post, README, blog, documento, draft, write	+ Audience, + Length/format, + Tone, + Caveats to include up front
Meta / discovery	cómo puedo, por qué, qué pasa si, how do I, what if, should we	+ Decision being made, + Constraints, + Alternatives already considered
Default	none match	Skeleton only

Operating Modes

Mode 1: Critique-only (default)

1. Apply 5-dimension skeleton.
2. Detect domain, apply extra checklist.
3. Output:
   • Diagnosis: table of dimensions with status (✓ / ✗ / partial) + what's missing
   • Improved version: rewrite incorporating reasonable defaults for gaps (flag the defaults)
   • Question: what does the user need to confirm/override?

Mode 2: Critique + execute

Same as Mode 1, then if user replies "ok" / "ejecuta" / "go", execute the improved version.

Mode 3: Learning mode (always-on side effect)

When the user accepts or refines the improved version, capture the pattern to memory:

• Path: ~/.claude/memory/feedback_prompt_patterns.md (create if missing; append otherwise)
• Format: one entry per accepted pattern, dated, with original + improved + which dimension was the gap
• Use to bias future critiques toward the user's stylistic preferences (e.g. always wants caveats up front, always prefers ≤200-word reports, always works in Spanish chat / English deliverables)

After 5+ patterns saved, summarize the user's prompt style in ~/.claude/memory/user_prompt_style.md (overwrite each time with current synthesis).

Output Format

## Diagnosis

| Dimension | Status | Gap |
|-----------|--------|-----|
| Scope     | ✓      | —   |
| Metric    | ✗      | How is "works" measured? |
| Baseline  | partial| Implicit: vs. master. Confirm? |
| Subject   | ✓      | —   |
| Success   | ✗      | When do I stop? |

(+ domain checklist if applicable)

## Improved version

> [rewritten prompt with defaults filled in, defaults flagged with [DEFAULT: ...]]

## Confirmation
- Accept the flagged defaults?
- Execute the improved version, or iterate?

Common Mistakes

• Asking for clarification on every dimension — propose defaults for low-risk gaps, only ask for high-risk ones. User shouldn't have to answer 5 questions.
• Critiquing without rewriting — diagnosis alone is useless. Always produce the improved version.
• Generic rewrites — the improved version must inherit the user's specific context (repo, language, prior conversation), not be a template.
• Ignoring user's style — if memory has user_prompt_style.md, respect it (e.g. don't force caveats if user explicitly wants short prompts).
• Re-asking dimensions the user already gave — read context first. If the draft says "in this repo" and you know the repo, don't ask "what subject?".

Anti-patterns to flag in user prompts

When critiquing, watch for these recurring weaknesses:

• Stream of consciousness ("I want you to do X and also Y and well also look at Z") (es: "quiero que hagas X y también Y y bueno tambien que mires Z") → Fix: enumerate as discrete tasks, prioritize, scope each.
• Vague qualifiers ("better", "faster", "good", "clean") (es: "mejor", "más rápido", "bien", "limpio") → Fix: replace with measurable threshold or comparison.
• Implicit baseline ("make it better than before") (es: "hazlo mejor que antes") → Fix: name the comparison artifact (commit, file, version).
• Missing deliverable shape ("give me an analysis") (es: "dame un análisis") → Fix: specify format (table / bullets / report / code diff / verdict + reasoning).
• No stop condition ("optimize this") (es: "optimiza esto") → Fix: "stop when X holds" or "stop after N iterations".
• Persona drift (no audience stated) → Fix: "for a senior Go dev reading this in 6 months" or "for myself reviewing in 1 week".

Quick reference card

diagnosis → 5 dimensions (✓/✗/partial)
          + domain checklist (coding/analysis/writing/meta)
          + anti-patterns flagged
improved version → rewrite with [DEFAULT: ...] markers
confirmation → 1-2 high-risk questions only
learning mode → save pattern on accept