# Routing Plans

> Rewrite an existing implementation plan into a cost-aware, model-routed plan backed by live LLM Stats benchmark data. Use when asked to route a plan, assign models to plan tasks, optimize a plan for model cost, or add per-task primary/fallback model recommendations. Advisory only - rewrites the plan file in place; never executes tasks, spawns workers, or edits project code.

- Skill: `lucadominguez/routing-plans` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add lucadominguez/routing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucadominguez/routing-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lucadominguez (https://skillmd.com/u/lucadominguez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucadominguez/routing-plans

---


# Routing Plans

Rewrite an existing implementation plan into a cost-aware, model-routed plan.
Inspect both the plan and the current codebase, improve the plan's task
boundaries and ordering where useful, assign every routed task a primary and
fallback model justified by current LLM Stats evidence, and overwrite the
original plan file in place.

**This skill is advisory only.** It must not invoke models, start agents or
workers, execute the plan, edit project source code, or manage terminals. Its
only write target is the plan file itself.

## Inputs and preconditions

Before starting, confirm you have:

1. The path of the plan file to rewrite. If the user did not name one and more
   than one plausible plan file exists, ask which one - do not guess.
2. Read access to the project or repository the plan targets.
3. Python 3.10+ available to run `scripts/llm_stats.py`.
4. An LLM Stats API key in the `LLM_STATS_API_KEY` environment variable.

**Credential rules (hard):** never embed the key in the plan, the command
line, cache files, logs, examples, or any output. Never ask the user to paste
the key into the plan or the conversation; if it is missing, stop before
rewriting and tell them to set `LLM_STATS_API_KEY` in their environment. If a
key was previously pasted into the conversation, do not copy it anywhere.

## Workflow

### 1. Establish scope

Resolve the exact plan path and the repository root. Read the complete plan,
plus repository instruction files (CLAUDE.md, AGENTS.md, CONTRIBUTING, etc.)
that constrain how work is done. Note the plan's file format (markdown,
checklist, YAML, tracker convention) - the rewrite must round-trip it.

### 2. Inspect the codebase (read-only)

Look at repository structure, manifests and lockfiles, languages and
frameworks, test layout, CI configuration, existing ownership boundaries, and
every file the plan names. Read enough implementation context to judge whether
the plan's tasks, dependencies, and file boundaries are realistic. Do not
modify anything in this phase.

### 3. Normalize the plan

First build an internal **requirement ledger**: every goal, constraint,
deliverable, and explicit non-goal stated in the plan. This ledger is the
contract for the rewrite - nothing in it may be dropped or silently weakened.

Then reshape tasks where it genuinely helps:

- **Split** tasks that mix unrelated expertise (e.g. "build the API and style
  the settings page") or that cannot be reviewed independently.
- **Merge** tiny tasks whose separation adds routing overhead without
  improving reviewability.
- **Reorder** to respect dependencies and open up safe parallel groups.
- **Add** missing verification or integration tasks when the plan ships
  changes it never checks.
- **Retain** intentional human approval gates exactly where the plan put them.

### 4. Profile each task

Assign each task one primary capability profile (secondary profiles allowed):

| Profile | Typical work |
|---|---|
| `architecture` | repository exploration, cross-cutting design reasoning |
| `coding` | general implementation and refactoring |
| `algorithms` | complex algorithmic reasoning |
| `debugging` | root-cause analysis, regression hunting |
| `testing` | test design and verification |
| `frontend` | UI implementation and styling |
| `agentic` | tool use, multi-step autonomous execution |
| `math` | mathematics or formal reasoning |
| `long-context` | synthesis over large inputs |
| `mechanical` | documentation, renames, config churn, routine edits |

For each task also estimate: difficulty and risk; required context window;
input/output token shape; modality and tool-use needs; whether an open-weight
model is acceptable or required; latency sensitivity; and expected cost tier.
The full profile-to-benchmark-category mapping and the routing metadata format
live in `references/routing-contract.md` - read it before routing.

### 5. Fetch LLM Stats evidence

Run the helper to pull current, comparable evidence:

```bash
python scripts/llm_stats.py snapshot --categories coding,agentic,reasoning,math --out routing-evidence.json
```

(Write the output file somewhere temporary, not into the repository.)

The helper queries the documented LLM Stats API (`api.llm-stats.com`) and
emits deterministic JSON containing models with stable identifiers, provider
and organization, open-weight/license metadata, context and inference
metadata, provider pricing, benchmark definitions and categories, benchmark
scores, TrueSkill category rankings with conservative ratings, and the
timestamp of every piece of evidence. It handles pagination, bounded
timeouts, HTTP 429 `Retry-After`, and a credential-free local cache. Stale
cache data is used only when a live request fails and is labeled
`"stale": true` in the output - carry that label into the plan.

The script never chooses the task/model mapping and never edits the plan.
That judgment is yours, in the next step.

### 6. Build a quality/cost frontier per task

For each task profile:

1. Select the relevant benchmark categories (see the contract reference).
2. Exclude models that fail **hard constraints**: context window too small,
   missing modality, no tool support where the task needs tools, license
   incompatible with the project's requirements.
3. Rank surviving models by evidence-backed capability for the profile,
   weighting confidence and benchmark coverage.
4. Compute expected cost from provider pricing and the task's estimated token
   shape.
5. **Choose the least expensive model that clears the task's required quality
   and confidence threshold.** Do not pick the cheapest model when it is
   materially underqualified; do not pick the leaderboard leader when a
   substantially cheaper model is sufficiently capable.

Any model present in LLM Stats may be recommended, from any vendor, whether or
not it is configured in the user's environment. Never route from vendor
familiarity or memory - only from the fetched evidence plus repository
context. High-risk or hard-to-review tasks justify a stronger model; routine
mechanical tasks almost never do.

### 7. Rewrite the plan

The rewritten plan starts with a **routing summary**: data source, evidence
retrieval timestamp and freshness (live vs. stale cache), global assumptions,
any recommended models that would need configuration before execution, and a
**budget and ETA ledger** - projected total token spend (input/output tokens
and dollars, computed from the per-task estimates and LLM Stats pricing) plus
a running-totals table the executing agent must update as tasks complete.

Every executable task carries the routing metadata block defined in
`references/routing-contract.md`: goal and deliverable, dependencies,
file/ownership boundary when discoverable, acceptance checks, primary model
(LLM Stats identifier), fallback model, capability profile and cost tier, a
concise routing rationale, evidence summary with timestamp, parallel group or
sequential requirement, and the escalation condition for switching to the
fallback or a stronger model.

Each task also carries a **budget and ETA block**:

- estimated input and output tokens, and the resulting dollar estimate at the
  primary model's current per-million-token pricing (show the arithmetic
  inputs, not just the total);
- fields for actual tokens and dollars, left blank for the executing agent to
  fill in when the task finishes;
- an ETA estimate (wall-clock duration and projected completion order), with
  an explicit instruction that the executor must re-forecast the remaining
  tasks' ETAs and the plan-level totals after every task completes or its
  scope changes - ETAs are living values, not one-time guesses.

The skill itself only writes the initial estimates; keeping actuals and ETAs
current is an obligation the plan imposes on whoever executes it.

Preserve the plan's original format and any useful project-specific
conventions (tracker syntax, numbering, checklists).

### 8. Validate, then overwrite atomically

Before writing anything:

- Recheck the rewritten plan against the requirement ledger - every entry
  accounted for, none weakened.
- Verify every executable task has complete routing metadata.
- Check dependencies and parallel groups are internally consistent (no cycles,
  no parallel group containing a dependency edge).
- Confirm you performed no execution or worker-spawning action.
- Confirm every model recommendation cites evidence or is explicitly labeled
  uncertain.

Then write a temporary file **beside the original** and atomically replace the
original only after validation succeeds. Do not produce a second routed-plan
file. If validation or replacement fails, leave the original untouched and
report the problem.

## Failure behavior

| Condition | Behavior |
|---|---|
| Missing API key | Stop before rewriting; explain how to set `LLM_STATS_API_KEY`. Never ask for the key in the plan or chat. |
| Auth failure (401) | Leave plan untouched; report the error category without printing credentials. |
| Rate limit (429) | Honor `Retry-After`. If a usable cache exists, label it and continue; otherwise leave the plan untouched. |
| Network failure | Use a usable cache with an explicit stale-data warning, or leave the plan untouched. |
| Thin benchmark coverage | Recommend cautiously, label the evidence gap, choose a fallback with stronger coverage. |
| Unknown plan format | Preserve the format where feasible; ask before replacing structured formats that cannot be safely round-tripped. |

## Non-goals

This skill does not call provider APIs to execute tasks, spawn or delegate to
workers, configure providers or purchase access, guarantee a recommended model
is available in the user's agent, keep a hardcoded list of favored vendors or
models, manage terminals, or rewrite application source code.