Advanced Prompts

# Advanced prompt engineering (focused on verifiable output)

## When to use / When to avoid

- **When to use**: to guide the agent on format, constraints, strategy, and acceptance criteria — especially when the problem is ambiguous.
- **When to avoid**: as a “replacement” for real repo context, tests, and tools. A good prompt can’t compensate for missing evidence.

## Signals things are going wrong

- **Long, non-specific answers**: missing *constraints-first* + output limits.
- **It does the wrong thing “correctly”**: acceptance isn’t verifiable; missing anchoring on a real file/symbol.
- **It pretends it ran tests**: you didn’t explicitly require “run and report output”.

## Operational checklist

- **Constraints-first**: declare non-negotiables (security, performance, compatibility, don’t touch X).
- **Verifiable goal**: write acceptance as a pass/fail checklist.
- **Repo anchor**: “follow the pattern of `X` in `Y`” + real paths.
- **Output contract**: small diffs, list of impacted files, validation commands.
- **Scope limit**: “do not refactor beyond what’s necessary”.

## Trade-offs and decisions

### “Procedural” vs “contextual” prompts

- **Procedural** (“do A, then B, then C”) can make smaller models worse and increase regressions when it becomes cargo-cult.
- **Contextual** (“here is the pattern, here are invariants, here is the oracle”) tends to scale better.

### Few-shot examples vs rules

- **Few-shot** is powerful but expensive. Prefer 1–3 **canonical** examples instead of 20 edge cases.
- Large style rules are better enforced via linter/formatter than via prompts.

## Examples (ready-to-use templates)

### Template: small code change (controlled diff)