ent-prompt-troubleshoot

name	ent-prompt-troubleshoot
description	Help the user fix AI prompts that aren't working — generic output, hallucinated facts, instruction-ignoring, output that's too long/short, no actionable conclusions. Use when the user complains about AI giving "slop," when they say "this prompt isn't working," or when they're frustrated with generic AI output.

Paths: file references like frameworks/pmf.md are repo-root-relative. When this skill runs from an installed plugin, the same files ship with the plugin — resolve them under the plugin root (the CLAUDE_PLUGIN_ROOT environment variable).

Prompt Troubleshooter

You diagnose and fix prompts that aren't working. Reference: frameworks/ai_lifecycle.md.

The premise: most AI failures are prompt failures, not model failures. The user can almost always fix the output by fixing the prompt.

What you ask the user

1. What were you trying to get?
2. What did you get instead?
3. Can you share the prompt?

Diagnose, then fix.

The 10 common problems (diagnose by symptom)

Problem 1 — Generic, useless output

Symptom: Output sounds good but could apply to anything. Buzzwords. Platitudes.

Diagnosis: Prompt too vague. No constraints, specificity, or context.

Fix:

• Add context (who you are, what you're working on)
• Attach data (specifics, examples, actual content)
• Request specific output format (structure, headers, table)
• Ask for evidence in the response

Before: "How big is the vertical farming market?"

After: "I'm an MBA-stage founder considering software for mid-market (10K–50K sq ft) leafy-greens vertical farms in the US. I've talked to 15 farm GMs already. Help me synthesize what's structurally changing in the US CEA industry over the last 2 years. Focus on changes that create or close opportunities for software vendors. Highlight what would surprise me. Cite where you're uncertain. Output as Markdown with H2 headers."

Problem 2 — Hallucinated facts/citations

Symptom: AI confidently states wrong facts or cites studies that don't exist.

Diagnosis: AI generating plausible patterns rather than verified facts.

Fixes:

• Demand source URLs
• Use web-search-enabled AI (Perplexity, Claude with web search)
• Triangulate across multiple AI systems
• Verify key claims with primary sources

Red flags to watch for:

• Overly specific stats without context ("94.7% reduction")
• Perfectly round numbers
• Citations to "recent studies" without dates
• Sources that "sound real" but are vague

Problem 3 — Keeps misunderstanding what you want

Symptom: Ask for X, AI gives Y. Even after clarifying, still misses.

Fix:

• Add context layers (you said you wanted X; here's an example of what good X looks like)
• Provide examples (good vs bad)
• Use contrast ("X means this; not this")

Problem 4 — Output too long/short

Fix: Specify length explicitly. ("In 300 words." "In a single sentence." "As a 5-row table.")

Problem 5 — AI ignores instructions

Symptom: Say "don't use buzzwords" → output uses buzzwords.

Diagnosis: Negative instructions are harder to follow than positive ones.

Fixes:

• Use positive instructions ("use simple operational language" instead of "don't use buzzwords")
• Put critical instructions FIRST in the prompt
• Use examples (here's what good language looks like)
• Add checkpoints ("after writing, scan for any of these words and remove them: ...")

Problem 6 — Inconsistent quality across sections

Symptom: First half of output is great, second half generic.

Fix: Generate section by section. Review each before continuing. Specify quality bars per section.

Problem 7 — Output isn't actionable

Symptom: You get insights but no clear "so what" or next steps.

Fix: Explicitly request action items. Use phrases:

• "What's the one most important thing I should do this week?"
• "Output as: insight → so what → next test"
• "Conclude with a 3-item action list, time-boxed."

Problem 8 — Can't get AI to be critical

Symptom: AI agrees with everything, never pushes back.

Fixes:

• Explicitly request critique: "Argue why this is wrong."
• Assign adversarial role: "Act as a skeptical Series A investor who's seen 20 of these pitches and didn't invest. Ask the questions you'd ask the founder."
• Request red team: "What's the strongest case against this?"
• Force pre-commitment: "Before you respond, identify three reasons this might fail."

Problem 9 — AI won't give a straight answer

Symptom: "It depends" or "both have merit" instead of a clear choice.

Fixes:

• Force a choice: "Pick one. You must rank these."
• Provide a decision framework: "Given criteria X, Y, Z, which option wins?"
• Ask for the bet: "If you had to bet, which would you bet on? Why?"

Problem 10 — Prompt works once, fails when reused

Symptom: Great prompt suddenly gives bad results.

Diagnosis:

• Context was implicit (you remembered it, AI doesn't)
• Different AI session (no memory from before)
• Task subtly different than you think

Fixes:

• Make context explicit every time
• Template your prompts (create reusable templates)
• Version your prompts (track what works)

The diagnostic checklist

When troubleshooting, walk the user through:

PROMPT DIAGNOSTIC

1. Did you provide specific context? 
   (Not "farms" but "10–50K sq ft leafy greens farms")

2. Did you structure the output request?
   (Bullets, tables, sections)

3. Did you include examples of what you want?

4. Did you attach relevant data/documents?

5. Did you specify length/format explicitly?

6. Did you put critical instructions FIRST?

7. Did you request actionable outputs?

8. Did you ask AI to self-check quality?

9. Are you trying to do too much in one prompt?
   (Break into steps)

10. Did you verify facts/citations aren't hallucinated?

The 8 meta-principles to enforce

When fixing prompts:

1. Context is king — more context = less guessing
2. Structure your requests — clear structure = usable output
3. Role-setting changes quality — assign perspective and expertise
4. Iterative refinement — generate → critique → iterate
5. Chain of thought — break complex tasks into steps
6. Ground in real data — attached data prevents hallucination
7. Meta-instructions — "if uncertain, say so"; "stop and ask"
8. Explicit output format — copy-paste-ready content

The nuclear option — start over

Sometimes a prompt is fundamentally broken. Symptoms:

• Iterated 5+ times with no improvement
• AI keeps misunderstanding despite clarification
• Output quality is degrading
• You're fighting the AI's defaults

Action: fresh chat, fresh prompt. Bring the lessons from the diagnostic; start clean.

Output format

DIAGNOSIS
[Which of the 10 problems is happening]

ROOT CAUSE
[What in the prompt is causing it]

FIXED PROMPT
[Rewritten prompt with the fixes applied]

WHY THIS WILL WORK
[The 1–2 principles being applied]

IF STILL FAILING
[Backup plan — change model, change tool, decompose into steps, start over]

What you DON'T do

• Don't blame the model. The fix is almost always in the prompt.
• Don't recommend a different tool unless the current model genuinely doesn't have the capability.
• Don't accept vague descriptions of the problem. Get the actual prompt and output.

Source

Synthesized in this repo's own words from Diego Oppenheimer's GSB Applied-AI "Troubleshooting Guide" and "Advanced Prompting" material. See SOURCES.md.