/prompt-engineering

name: prompt-engineering
description: "Prompt engineering patterns for writing agent prompts and skill files — constraint budgets, register shifting, HARD GATE patterns, anti-personas. Use when writing or reviewing agents/*.md or skills/*/SKILL.md. TRIGGER when: agent prompt, skill file, prompt engineering, model-tier compensation, HARD GATE, prompt quality. DO NOT TRIGGER when: user-facing docs, README, CHANGELOG, config files."
allowed-tools: [Read, Grep, Glob]

Prompt Engineering Patterns

Compact, actionable patterns for writing agent prompts and skill files. See [docs/PROMPT-ENGINEERING.md](../../docs/PROMPT-ENGINEERING.md) for full rationale and academic citations.

---

Constraint Budget (MOSAIC finding)

| Range | Compliance | |-------|-----------| | 1–6 | Reliable | | 7–15 | Unpredictable | | >15 | Degraded |

**Rule**: Max 6 hard constraints per section. Hard gates at the END of sections (Claude recency effect).

---

Register Shifting Checklist

Before finalizing any hard gate or enforcement directive, verify the verbs:

• [ ] Tier 1 (deep): `audit`, `verify`, `critically analyse`, `enumerate` — use for HARD GATEs
• [ ] Tier 2 (balanced): `review`, `check`, `describe` — use for standard task instructions
• [ ] Tier 3 (minimal): `look at`, `mention`, `note` — advisory only; never in enforcement

**FORBIDDEN**: Tier 3 verbs in REQUIRED or FORBIDDEN lists.

---

Persona Anti-Pattern

**FORBIDDEN for analytical agents** (reviewers, auditors, analysts, planners):

• ❌ `You are a [role]...` persona prefixes
• ❌ `Act as an expert in...` framing
• ❌ `Imagine you are...` setups

**Source**: PRISM (arxiv:2603.18507) — expert personas reduce knowledge-retrieval accuracy for analytical tasks.

**Correct pattern**: Role description + behavioral directive.

# BAD
You are a senior security engineer. Review this code.

# GOOD
Perform a security audit. Enumerate all CWE categories present.

---

HARD GATE Pattern Template

### HARD GATE: [Topic]

**[One-sentence scope statement]**

**REQUIRED** (all must be met):
- Specific action A
- Specific action B

**FORBIDDEN** — You MUST NOT do any of the following:
- ❌ You MUST NOT [prohibited action]
- ❌ You MUST NOT [prohibited action]

**Why**: [One sentence — increases compliance]

---

Model-Tier Compensation Template

<model-tier-compensation tier="[haiku|sonnet|opus]">
## Model-Tier Behavioral Constraints ([Tier Name])

- Do NOT [specific tendency to suppress].
- ALWAYS [specific required behavior].
</model-tier-compensation>

Rules:

• Include `tier` attribute for automated validation
• No meta-commentary about model weaknesses (model-visible; may reinforce behavior)
• Actionable directives only — positive framing where possible
• Place at TOP of agent prompt before role description

---

Self-Refine Loop (when quality matters)

Use for planning, security scans, and architecture tasks. 2–3 passes optimal (NeurIPS 2023).

## Pass 1: GENERATE
[Initial output]

## Pass 2: FEEDBACK
Critically analyse Pass 1. Enumerate:
- Gaps (missing)
- Errors (wrong)
- Ambiguities (unclear)

## Pass 3: REFINE
Apply Pass 2 feedback. Produce final output.

**Anti-pattern**: "Review your answer and improve it" — Tier 3, will be ignored. Use Tier 1: "Critically analyse for gaps and enumerate missing cases."

---

Stick+Carrot Pattern

Every block (hook or agent) MUST include a required next action:

# STICK only (bad)
BLOCKED: Cannot edit agents/*.md outside the pipeline.

# STICK + CARROT (good)
BLOCKED: Cannot edit agents/*.md outside the pipeline.
REQUIRED NEXT ACTION: Use /implement to run the pipeline with your changes.

Hook JSON format:

{
  "decision": "block",
  "reason": "What failed and why.",
  "requiredNextAction": "Specific step to take next."
}

---

Anti-Patterns Summary

| Anti-Pattern | Why Wrong | Fix | |-------------|-----------|-----| | `>15 constraints` per section | MOSAIC: degraded compliance | Split into subsections ≤6 each | | Persona prefix for analytical tasks | PRISM: reduces accuracy | Role description + directive | | Hedge words in hard gates | Weakens enforcement | Delete or replace with MUST | | Prose-buried constraints | Low compliance | Convert to numbered list | | Meta-commentary about model weaknesses | May reinforce behavior | Reframe as behavioral directive | | Block without carrot | Model loops | Add REQUIRED NEXT ACTION |

---

Cross-Reference

See [docs/PROMPT-ENGINEERING.md](../../docs/PROMPT-ENGINEERING.md) for:

• Full MOSAIC constraint budget analysis
• PRISM persona findings detail
• Self-Refine NeurIPS 2023 citations
• XML sectioning rationale
• Complete anti-pattern catalog