/meta-planning-ai-planning

name: meta-planning-ai-planning
description: AI specification planning frameworks. Use when a spec touches model calls, prompts, retrieval, tool calling, agentic loops, or evals. Covers approach selection, model and provider choice, structured output contracts, loop guards, budgets, failure modes, and eval design.

AI Planning Frameworks

> **Quick Guide:** Default to the simplest tier that satisfies the requirement — most features are one well-built model call. Pin the model id, define the output contract with a repair-vs-reject policy, budget in tokens and money rather than adjectives, enumerate the failure modes, and make quality measurable with an eval plan before implementation starts. Apply a framework only when the spec touches its artifact class — a feature with no retrieval needs no retrieval section.

---

<critical_requirements>

CRITICAL: Before Specifying AI Features

> **All specifications must be grounded in the codebase's real model clients, prompt modules, schemas, and eval fixtures** — reference specific files with line numbers

**(You MUST justify the approach against the simpler tier — a fixed code-orchestrated chain beats an agentic loop whenever the step sequence is known)**

**(You MUST pin an explicit model id in configuration with a named fallback — never a floating alias, never inline in code)**

**(You MUST define the output contract completely: mechanism, schema, validation boundary, and a repair-vs-reject policy)**

**(You MUST state budgets as numbers — tokens per call, calls per request, cost per request, p95 latency — never as adjectives)**

**(You MUST identify where untrusted input enters every prompt, and require adversarial eval cases wherever it does)**

**(You MUST apply each framework only when the spec touches its artifact class — an unused section is omitted, never filled)**

</critical_requirements>

---

**Auto-detection:** AI spec, LLM feature spec, prompt design spec, model selection, RAG spec, retrieval design, tool calling spec, agent loop spec, eval plan, token budget, structured output

**When to use:**

• Specifying a feature that calls a model (classification, extraction, generation, summarization)
• Choosing between a single call, a fixed chain, retrieval, and an agentic loop
• Specifying prompt architecture, versioning, and untrusted-input boundaries
• Specifying structured output contracts and validation policy
• Specifying retrieval parameters, tool contracts, or loop guards
• Specifying eval datasets, metrics, thresholds, and budgets

**When NOT to use:**

• When implementing AI code (use the relevant AI implementation skill)
• For the API surface that exposes the capability (use the api planning skill)
• For the planning PROCESS itself — research, scope fencing, success criteria — which the PM agent carries

**Key patterns covered:**

• Approach selection (single call → chain → retrieval → agentic loop)
• Model and provider selection with pinned ids and fallback chains
• Prompt architecture: role split, versioning, untrusted-input boundaries
• Structured output strategy and repair-vs-reject policy
• Retrieval design parameters
• Agentic loop guards and tool side-effect classification
• Eval design and adversarial cases
• Failure-mode matrix
• Token, cost, and latency budgets

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Per-artifact spec section templates and a worked example specification

---

<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 behavior, eval threshold — must be decided in the spec, or it gets decided implicitly in production.

**When specifying AI work:**

• Trace one existing model call end to end before specifying a new one — client, prompt module, validation, consumer
• Name the requirement that forces each tier of complexity; if nothing does, use the simpler tier
• Establish the baseline before proposing a change: current cost, latency, and quality numbers, or an explicit "unmeasured"
• Decide product questions in the spec — may the model answer from parametric knowledge when retrieval is empty? — rather than leaving them to the implementer

**When NOT to specify:**

• Don't specify an agentic loop for a step sequence known in advance
• Don't add retrieval infrastructure when the knowledge fits in the context window
• Don't fill a tool-contract or retrieval section for a feature that has neither
• Don't include implementation code — contracts, budgets, and behaviors only

**Core principles:**

• **Simplest sufficient tier**: most features are a single well-constructed call
• **Validate on receipt, every branch**: provider-side enforcement reduces violations; it does not eliminate them
• **Budgets are numbers**: "fast and cheap" is not implementable or reviewable
• **Refusals are surfaced, never retried**: retrying with softened wording is a bypass attempt
• **Eval thresholds gate the merge**: thresholds set after seeing results ratify instead of gating

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Choosing the Approach

Does the task need knowledge that is not in the model and not in the request?
├─ NO  → Single model call with a well-built prompt. Stop here. Most features end here.
└─ YES → Where does that knowledge live?
    ├─ A bounded set that fits the context window (< ~30% of it) → Pass it directly. No retrieval infrastructure.
    ├─ A large or growing corpus → Retrieval (RAG)
    └─ A live system of record (database, third-party API) → Tool calling, not retrieval

Does the task need multiple dependent actions the model must sequence itself?
├─ NO  → Single call, or a fixed chain of calls you orchestrate in code
│         (a fixed chain is cheaper, more debuggable, and easier to eval than a loop)
└─ YES → Agentic loop with an explicit step budget and termination conditions

**Default to the sim