/meta-planning-ai-planning

name: meta-planning-ai-planning
description: Specification frameworks for features that call a model — approach tier, model pinning, output contracts, budgets, failure modes and eval design. Load when a spec touches model calls, prompts, retrieval, tool calling, agent loops or evals.

AI Planning Frameworks

> **Quick Guide:** Default to the lowest tier that meets the requirement — most features are one well-built call — and name the requirement behind every tier above it. Pin the model id, give every output a contract the code checks on receipt, state budgets in tokens and money, give each failure the feature can hit a row, and fix eval thresholds before the first run. Two provider facts shape the answers: a schema-constrained output mode guarantees shape only for a response that completed and was not refused, so the contract's remaining work is truncation, refusals and values; and reasoning tokens bill as output and count against the output ceiling, so a ceiling sized for the visible answer can run out before one appears.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — templates for the sections every model-calling feature needs, and a worked specification
• [examples/retrieval-and-agents.md](examples/retrieval-and-agents.md) — retrieval design, tool contracts and loop guards
• [reference.md](reference.md) — output-mode guarantees, budget line items, default failure behaviour, retrieval starting points, grading methods, eval set sizing

---

Which path applies

A section belongs in the spec only when the feature has its artifact; one filled in for completeness reads to the implementer as something to build.

• **The feature calls a model** — approach, model, prompt, output contract, budgets, failure modes and eval plan; follow [examples/core.md](examples/core.md).
• **It retrieves from a corpus** — add the retrieval section from [examples/retrieval-and-agents.md](examples/retrieval-and-agents.md#pattern-8-retrieval-design).
• **The model calls tools, or orders its own steps** — add tool contracts and loop guards from [examples/retrieval-and-agents.md](examples/retrieval-and-agents.md#pattern-9-tool-contracts-and-agentic-loops).

---

<critical_requirements>

Before specifying an AI feature

**Name the requirement that rules out the simpler tier before specifying a chain, retrieval or a loop.** Each tier up adds cost, latency and failure rows, and a known step sequence run as a loop buys non-determinism and no capability.

**Pin the model id in configuration, name its fallback, and list what forces a re-eval.** A floating alias changes quality with no deploy, and a fallback nobody named becomes an unhandled exception on the first 5xx.

**Give every model output a contract — mechanism, schema, the validation that runs on receipt, and a repair-or-reject rule.** Provider-side enforcement covers shape for a completed, unrefused response and nothing more, so truncation, refusals and wrong values reach the consumer unless the spec stops them.

**State budgets as numbers, counting reasoning tokens as output and cached input at its cached rate.** An adjective cannot be implemented or reviewed, and a cost line that leaves out either is wrong — low without the reasoning, high without the cache.

**Mark every untrusted input and bound what it can reach.** Delimiting lowers the odds that an injected instruction is followed without preventing it, so the prompt gets adversarial eval cases and its tools get only the access the task needs.

</critical_requirements>

---

**Auto-detection:** AI feature spec, LLM feature spec, model selection, pinned model id, model fallback, prompt version, system prompt, untrusted input, prompt injection, structured output contract, repair or reject, refusal handling, token budget, reasoning tokens, prompt caching, retrieval design, chunk size, re-ranking, tool contract, agent loop, step budget, eval plan, eval threshold, LLM-as-judge

**Applies to:**

• Choosing between a single call, a fixed chain, retrieval and an agentic loop, and recording why the simpler tier lost
• Model selection, prompt architecture and the output contract for each model call
• Token, cost and latency budgets, and the behaviour for each way a call fails
• Retrieval parameters, tool contracts and loop guards
• Eval sets, metrics and the thresholds that gate a merge

**Handled elsewhere:**

• The spec's general shape — research, goal, scope fence, success criteria — belongs to the planning process; this skill adds the sections a model call brings
• Provider SDK calls — parameter names, client setup, streaming plumbing — are the implementation's; the spec names the mechanism, not the call
• The interface that exposes the feature — request and response shapes, error statuses — is settled with that interface; the failure matrix here says what the feature does, not how the interface reports it

---

<philosophy>

Philosophy

**Non-determinism is the material; contracts are what make it buildable.** A model's output cannot be trusted by construction, so every boundary — schema, budget, failure behaviour, eval threshold — is decided in the spec, or production decides it implicitly.

• **Start from the existing call path.** Trace one model call end to end — client, prompt module, validation, consumer — and cite each as the pattern source with its file and lines; the new feature inherits its retries, timeout and logging, and a bare path leaves the implementer to guess which code was meant.
• **Record the baseline** — current cost, latency and quality, or an explicit "unmeasured" — so the change has something to beat.
• **Decide product questions in the spec**: whether the model may answer when retrieval finds nothing, whether its output acts or only advises.
• **Contracts, budgets and behaviours, not code.** Implementation code in a spec gets followed instead of the codebase's own patterns.

</philosophy>

---

<decision_framework>

Which tier

Two independent qu