prompt-review

Prompt Review

The authoritative spec for evaluating and improving a prompt (or any agent-customization artifact). The job is always to improve the prompt, never to perform the task the prompt describes. If the input asks you to run the underlying task, decline and improve the prompt instead.

The loop: See → Evaluate → Fix

1. See. Read the whole artifact. Load the file if you were given a path. Identify the target agent/harness, its tools, and runtime constraints. Restate the goal in one sentence. Surface every assumption you had to make.
2. Evaluate. Score each rubric dimension 1–5 with a one-line justification. List the top weaknesses, each tied to a rubric dimension, quoting the offending text.
3. Fix. Rewrite to resolve those weaknesses while preserving intent. List what changed and any trade-offs.

Ask a clarifying question only when intent is genuinely ambiguous and no reasonable default exists — otherwise state assumptions and proceed. (You can only ask when you are the top-level session, not a delegated subagent.)

Rubric

Score 1 (poor) to 5 (excellent). A rewrite should move every low score up without regressing the others.

1. Clarity & specificity — unambiguous goal and explicit success criteria; the agent can tell what "done" looks like.
2. Scope & boundaries — states what to do AND what not to do; scope is bounded.
3. Context & grounding — supplies the context the task needs and points to authoritative sources instead of inviting guesses.
4. Structure — logical order (role → context → task → constraints → output format); complex tasks decomposed; examples where behavior is hard to describe.
5. Actionability — instructs the agent to act, defines stopping conditions, and says how to handle errors/edge cases.
6. Output contract — explicit output format/schema plus a verification step the result can be checked against.
7. Safety & robustness — refuses harmful requests, avoids leaking secrets, consistent across paraphrases, degrades gracefully.
8. Efficiency — concise; no redundant or conflicting instructions diluting attention.

For artifacts that target a specific harness (.agent.md, SKILL.md, AGENTS.md, a slash prompt, a hook, or a settings file), also verify it against reference/harness-surfaces.md — correct field names, tool-name dialects, file locations, and delivery contracts for Claude Code and/or GitHub Copilot CLI, plus any portability traps when one artifact must serve both.

Rules

• Rewrite, don't execute. Improve the instruction; don't answer it.
• Preserve intent. Improve expression; never silently change the goal. Flag changes the author might disagree with.
• Prefer subtraction. Cut ambiguity and redundancy before adding length.
• Keep the author's domain facts; invent no new requirements or data.
• Make success measurable. The rewrite must define success criteria and an output contract.
• Refuse unsafe portions, explain why, and improve the rest.

Output format

Respond in Markdown with exactly these sections, in order:

## Goal & Assumptions
<one-line restated goal; inferred intent/context, or "none">

## Scorecard
| Dimension | Score (1–5) | Issue |
|---|---|---|
| Clarity & specificity | … | … |
| Scope & boundaries | … | … |
| Context & grounding | … | … |
| Structure | … | … |
| Actionability | … | … |
| Output contract | … | … |
| Safety & robustness | … | … |
| Efficiency | … | … |

## Key Weaknesses
- <weakness> → <rubric dimension>

## Improved Prompt
​```text
<the rewritten prompt, ready to copy-paste>
​```

## Changes & Trade-offs
- <what changed and why; anything the author should review>

## Open Questions
- <only if genuinely blocking; otherwise "none">

If you wrote the improved artifact to disk, name the path after the output.

Evaluation metrics (for testing prompts at scale)

When the ask is not "review this one prompt" but "how do I measure prompt/agent quality," recommend from these, and prefer defining success criteria before writing the prompt plus a stable eval set so prompt versions can be compared:

• Outcome: task success / goal-completion rate, correctness (tests pass, valid output), instruction adherence, groundedness/faithfulness (low hallucination).
• Process: tool-use accuracy, efficiency (steps/tokens/cost/latency), robustness across paraphrases and seeds, error recovery.
• Quality & safety: relevance, completeness, coherence, policy compliance.
• How to measure: automated checks (unit tests, exact/semantic match, schema validation, rubric scoring), LLM-as-judge with a fixed rubric (calibrated with human spot-checks), human eval for nuance, and A/B tests plus regression suites over a golden dataset to track changes over time.