Prompt audit

prompt-audit

Most AI-coding failures trace back to thin prompts. A prompt that takes 30 seconds to write and 2 minutes for Claude to "execute" produces code that takes 2 hours to fix. This skill catches that before it happens.

When to use

Use whenever the user is evaluating, drafting, or about to send a prompt for non-trivial coding work. Triggers include:

• "Is this prompt good?"
• "Audit / review / check my prompt"
• "Will Claude understand this?"
• "How do I improve this prompt?"
• The user pastes a prompt and asks anything about it
• You notice the user is about to send a vague prompt for a complex task — proactively offer to audit it

Don't audit:

• Single-line throwaway prompts the user is happy with
• Pure conversation / clarification messages (not actual task prompts)

The six essential elements

A good coding prompt for non-trivial work has all six. Missing any one drops the success rate noticeably.

#	Element	What it answers	Why it matters
1	Goal	What problem are we solving? Who uses the result?	Without a goal, Claude optimizes the wrong thing
2	Scope	Which files / modules can change? Which can't?	Without scope, Claude touches things it shouldn't
3	Existing patterns	What in the codebase should we mimic?	Without patterns, Claude reinvents conventions inconsistently
4	Constraints	Performance, dependencies, compatibility	Without constraints, Claude makes choices the user won't accept
5	Verification	What tests prove this is correct?	Without verification, "done" is undefined
6	Done definition	When can we mark this complete?	Without done, Claude over-builds or under-builds

Workflow

Step 1 — Parse the prompt

Read the prompt the user shared. Identify which of the 6 elements are present, partially present, or missing. Be honest — "we should follow good patterns" is not a real existing-pattern reference; an actual file path is.

Step 2 — Score each element

For each element, classify as:

• ✅ Clear — concrete, actionable, unambiguous
• ⚠️ Vague — present but too abstract to be useful
• ❌ Missing — not addressed at all

Step 3 — Diagnose with reasons

For each gap, explain to the user why this matters in the specific task at hand — not just generic best-practice scolding. Example:

"Your scope is missing — and because this prompt mentions auth/, Claude will likely modify shared auth middleware that 30+ other endpoints depend on. That's a core-code change that needs explicit human ownership."

Step 4 — Watch for over-constraint too

The opposite failure mode: a prompt that dictates every variable name, every line of pseudocode, every internal step. This makes the model worse, not better. If you see this, flag it:

"Your prompt over-constrains the implementation. The model performs best when given goals + constraints + patterns, then trusted to write the code. Treat the prompt like onboarding a junior — explain what matters, not what to type."

Step 5 — Produce a rewrite

Always produce an improved version, even if the original was decent. Use this structure:

[Goal]
<Who uses this, what done means>

[Scope]
- Can modify: <list>
- Must not modify: <list>

[Existing patterns]
- Mirror <specific file or module>
- Convention: <e.g., service.ts + route.ts + *.test.ts>

[Constraints]
- <Performance, dependencies, compat>

[Verification]
- 3 e2e tests: <happy + 2 errors, described at user level>
- Manual: <if applicable>

[Done]
- <Concrete checklist>

If the user's task isn't big enough to need all six, drop the unused ones rather than padding with placeholders.

Step 6 — Show before/after side by side

End the audit with a direct comparison so the user sees the gain. Example:

Before (6 words): "Add a user activity report endpoint."
After (~250 words): <full structured prompt>
Why the rewrite is better: scope is now explicit, existing pattern named, verification defined, done measurable.

Red flags worth calling out

When you spot any of these in the original prompt, surface them explicitly:

• Touches core code without acknowledging it. "Just add this to the auth middleware..."
• No verification at all. "It should work."
• Vague pronouns. "Make it better." "Fix this." (Better what? This what?)
• No file paths anywhere. Hard to ground without paths.
• Implies multiple PRs in one prompt. "Build the auth flow and the user dashboard and the reporting." Suggest splitting.
• Domain the user clearly doesn't know. Hard to PM a domain you don't understand. Ask: "How will you tell if this is right?"
• Asks the AI to write the spec. "Figure out what we should build." Not Claude's job — that's product work.

Output format

Use this structure for the audit:

## Audit summary
<1-2 sentences: overall verdict>

## Element check
| Element | Status | Notes |
|---|---|---|
| Goal | ✅ / ⚠️ / ❌ | <observation> |
| Scope | ✅ / ⚠️ / ❌ | <observation> |
| Existing patterns | ✅ / ⚠️ / ❌ | <observation> |
| Constraints | ✅ / ⚠️ / ❌ | <observation> |
| Verification | ✅ / ⚠️ / ❌ | <observation> |
| Done | ✅ / ⚠️ / ❌ | <observation> |

## Red flags
<bullet list, or "None">

## Improved version
<full rewrite>

## Why the rewrite is better
<2-3 specific gains>

Stopping condition

End the skill when:

• The user has the rewritten prompt
• Or the user pushes back: "It's fine as is." (Don't keep relitigating.)