/directional-prompting

name: directional-prompting
description: Write prompts, system instructions, agent directives, slash commands, and skill descriptions using two stacked layers — outcome-first (define the destination, success criteria, stopping condition) plus directional language (every sentence names the path with positive verbs). Triggers when writing or reviewing any prompt, system message, AGENTS.md, CLAUDE.md, skill description, agent instruction, tool description, slash command body, eval rubric, or anywhere an LLM reads instructions. Use when the user says "write a prompt", "improve this prompt", "audit this system prompt", "outcome-first", "success criteria", "directional", "make this prompt positive", or when authoring any new skill, agent, or directive.
metadata:
  author: saint
  version: "2.0.0"

Directional Prompting

Two layers, both required.

**Layer 1 — Outcome.** Open with a block that names the destination. The goal, what "done" looks like, when to stop, the true invariants. This is the frame.

**Layer 2 — Direction.** Inside that frame, every sentence names the path forward with positive verbs. "Trace", "build", "use", "read", "return", "ask", "check". The correct behavior is described so clearly and completely that the wrong behavior has no room to exist.

Outcome without direction reads as wishful — the model knows where to go but not how to step. Direction without outcome wanders — the model walks crisp paths to nowhere. Both layers together: a model that knows the destination and walks toward it on every token.

Why both

Modern frontier models (Claude Opus 4.7, GPT-5.5) follow instructions literally. The Claude 4.7 guide: *"Positive examples showing how Claude can communicate with the appropriate level of concision tend to be more effective than negative examples or instructions that tell the model what not to do."* The GPT-5.5 guide: *"GPT-5.5 is strongest when the prompt defines the target outcome, success criteria, constraints, and available context, then lets the model choose the path."*

Both labs converge on the same shape. Name the destination. Name the path. Skip the prohibitions.

Layer 1 — The outcome block

Every non-trivial prompt opens with this:

Goal: <one sentence>

Success means:
  - <required output element 1>
  - <required output element 2>
  - <constraint: format, tone, length, schema>

Stop when: <explicit stopping condition>

Optional fourth field for agentic prompts:

Constraints: <only the true invariants — safety, required output fields, hard limits>

Rules for the block:

1. **Goal is one sentence.** If you need two sentences, the goal is two goals — split the prompt. 2. **Success criteria are checkable.** "Returns valid JSON matching schema X" beats "high quality output". 3. **Stopping condition is explicit.** "Stop after the first answer that meets success criteria" prevents the loop-that-never-ends failure mode where reasoning models keep refining past the point of usefulness. 4. **Constraints carry real weight.** Reserve ALWAYS, NEVER, MUST for things that genuinely cannot vary — safety boundaries, required output fields, actions that should never happen. Decorating regular guidance with ALWAYS bleeds the signal out of the words that actually need it.

Layer 2 — Directional execution

Inside the outcome frame, every sentence pulls forward.

The five rules

1. **Lead with the verb of the correct action.** "Trace", "build", "use", "read", "commit", "return", "write", "ask", "check". The first token of the sentence sets the trajectory. 2. **Describe the destination, not the failure modes.** "Return JSON matching this schema" beats "do not return prose". The richer the description of correct, the smaller the surface area for incorrect. 3. **Replace prohibitions with positive replacements.** Every "don't X" has a sister "do Y" where Y is the action that makes X structurally impossible. 4. **Make the correct behavior the only behavior described.** When the prompt is fully populated with the correct path, the wrong path has no foothold. 5. **Cut hedges, warnings, and meta-commentary.** "Be careful with...", "watch out for...", "make sure you don't..." — anxiety in text form. Delete and replace with the concrete positive action.

Bad → good

| Anti-pattern (plants the wrong action) | Directional (plants the right action) | |---|---| | Don't make assumptions. | Read the file before answering. | | Avoid using `any` types. | Type every parameter and return value explicitly. | | Don't write tests that mock everything. | Write tests that call the real function and assert on the returned value. | | Don't be verbose. | Answer in one or two sentences. | | Avoid hallucinating APIs. | Look up the library's API with Exa before calling it. | | Don't skip the research step. | Run `qmd query` and read the top three hits before writing. | | Try not to break existing tests. | Run `bun test` after every edit and keep all tests green. | | Don't use em dashes or emojis. | Use hyphens or colons for punctuation breaks. Use plain text. | | Avoid creating unnecessary files. | Edit the existing file at `<path>`. |

The audit pass

When reviewing a prompt or skill, scan for these tokens and rewrite each occurrence:

• `don't`, `do not`, `never`, `avoid`, `refrain`, `instead of`, `rather than`, `not allowed`, `prohibited`, `forbidden`, `won't`, `shouldn't`
• "be careful with...", "watch out for...", "make sure you don't..."
• Lists titled "Anti-patterns", "Pitfalls", "Mistakes to avoid" — convert each entry to the positive action it replaces, then retitle the list "Rules" or "Do this".

Each match is a prompt smell. Rewrite as the positive replacement. If no positive replacement exists, check the four legitimate-negation cases below — and if none apply, cut the rule.

When negation survives

Four narrow cases:

1. **Hard safety boundaries** where the prohibited action must be named so the model can recognize and refuse it. Pair refusal