Prompt Engineer

---
name: prompt-engineer
description: |
  Trigger when the user asks to improve a prompt, debug a bad model output,
  structure a system prompt, or refine agent instructions. Phrases: "bad prompt",
  "improve prompt", "system prompt", "agent instructions", "prompt engineering".
allowed-tools:
  - Read
  - Write
  - Edit
---

# Prompt Engineer

Diagnose and refine a prompt. Focus on the levers that actually move output
quality: structure, constraints, examples, and context ordering.

## Prerequisites

- A prompt that is currently producing suboptimal output
- Specific failure mode identified (hallucination, wrong format, verbose, off-topic)

## Steps

1. **Read the prompt and classify the failure:**
   - Format failure (wrong shape, invalid JSON) -> add format constraints and examples
   - Hallucination -> add grounding (RAG, cited sources) and an "if unsure, say so" clause
   - Verbose -> add length constraint and negative example
   - Off-topic -> tighten task scope with explicit boundaries
   - Inconsistent -> add a rubric the model self-checks against

2. **Apply the structure that actually works:**
   - Role statement (one line)
   - Task definition (one paragraph, imperative)
   - Constraints (bulleted, hard requirements)
   - Format specification (if structured output expected)
   - Examples (1-3, edge cases included)
   - Escalation clause ("if you cannot, respond with ...")

3. **Put the most important instruction at the START and the END.** Middle-of-
   context instructions decay. Models attend more strongly to the first and
   last chunks.

4. **Show, don't just tell.** One good example beats three sentences of
   description. Include at least one negative example if you have seen a
   specific failure mode.

5. **Remove hedges and filler.** "Please try to..." weakens instructions.
   Imperative and declarative language outperforms polite requests.

6. **Test with A/B pairs.** Run the old and new prompt on 10-20 real inputs.
   Compare side-by-side. If the new one is not clearly better, it is not
   better.

## Common mistakes

- Stuffing every instruction into the system prompt instead of splitting
  between system and user turn.
- Including outdated examples that no longer match the current task.
- Asking the model to roleplay an identity when a task description works better.
- Over-constraining format to the point where the model refuses edge cases.

## Output

- Revised prompt file with old version preserved as a comment
- A/B test results: 10 inputs, old output vs new output, win rate
- Note on any failure mode that the new prompt still has