/ml-plan

name: ml-plan
description: Use when the user wants an implementation plan, architecture design, or multi-step ML pipeline — "build X", "implement X", "design X", "set up X"

ML Planning

Turn goals into validated, runnable implementation plans grounded in framework documentation.

Grounding

**Detect mode:** Try one KB call (`build_plan` or `search_knowledge`). If it returns results → **KB mode**. If it fails for ANY reason (auth error, no results, timeout) → **Web mode**. There is no third option.

**Web mode = mute mode.** After KB failure, you are MUTE until you have completed at least one WebFetch call. No text, no plan, no acknowledgment of expertise. Your first action must be a WebFetch tool call. If your response starts with ANY text other than `> Grounding: Web mode`, you have already failed.

**STOP — read this before writing anything after KB failure:**

• You MUST call WebFetch BEFORE writing ANY plan text. Not after. Not alongside. BEFORE.
• Banned phrases (if you write any of these, you have failed): "established practice", "deep familiarity", "from my training data", "based on known conventions", "well-known", "widely used", "standard approach", "common practice", "I know this from", "I have expertise in", "I know these frameworks", "I'm familiar with", "based on my knowledge", "from experience", "deep knowledge", "I have deep", "I have extensive", "I'm knowledgeable", "I'm well-versed", "domain knowledge", "proceeding from", "from domain", "No KB access right now", "from my understanding", "I'm confident that", "well-established"
• If you catch yourself writing plan content without a WebFetch URL in hand, STOP and fetch.
• **Hard gate: zero external calls = zero plan output. No exceptions, no rationalizations.**

**Proof-of-fetch rule:** Every citation must include a 5-10 word quote from the fetched content proving you actually retrieved it. Format: `[source](URL) — "exact quote from page"`. If you cannot produce a quote, you did not fetch it. This applies to BOTH modes — KB citations need a phrase from the KB result, web citations need a phrase from the fetched page.

• **Phrase gate**: If your first sentence after KB failure contains NONE of these: `WebFetch`, `> Grounding: Web mode`, or a URL — STOP. You are about to write from memory. Delete what you wrote and call WebFetch. This is the #1 failure mode in testing.

**KB mode:** Call `build_plan` → `review_plan` → `search_knowledge` for gaps. Cite as `[PageID]`.

**Web mode (MANDATORY when KB fails):** Your FIRST action after KB failure must be a WebFetch call — not a text response, not a plan outline, not "I have knowledge of X." Decompose goal into steps → WebFetch official docs for EACH step → cite as `[source](URL#section-anchor)` with specific section paths. **Minimum: 1 WebFetch per plan step.** Start response with: `> Grounding: Web mode — citations from official docs.`

**Hard rule:** Every code block needs a `[source](URL)` or `[PageID]` citation from a fetch you actually made this session. No exceptions. Every `Class(kwarg=...)` must cite the doc page confirming that kwarg exists. If you write `Agent(input_description=...)`, you must have fetched the Agent class docs and confirmed `input_description` is a real parameter — not `tool_description_override` or something else.

**Architecture diagram rule (web mode):** Do NOT draw architecture diagrams, flow charts, or system designs until you have fetched docs for every component in the diagram. An architecture diagram without grounding is a guess dressed up as a plan. Fetch first, diagram second.

**Citation enforcement (both modes):** Every code block that calls a library API MUST have an inline comment citing the source: `# [PageID]` or `# [source](URL)`. Every class instantiation must cite the doc page where its kwargs are listed. Uncited API calls are treated as unverified guesses. When citing, always include the **library version** (e.g., `peft==0.12.0 [PageID]`). **Cross-reference rule:** When a plan combines multiple libraries (e.g., PEFT + Transformers, RAGAS + LangChain), verify version compatibility between them — fetch each library's install docs to confirm compatible version ranges. State the verified combination explicitly in Prerequisites.

**Web mode URL registry:** **Citation anchor rule (web mode):** Link to the specific API class/function section, NOT the library homepage. Use `#anchor` paths — e.g., `https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html#command-line-arguments` not `https://docs.vllm.ai`. A homepage link is not a citation.

• HF Transformers/PEFT/TRL: `https://huggingface.co/docs/{transformers,peft,trl}`
• Axolotl: `https://github.com/axolotl-ai-cloud/axolotl`
• DeepSpeed: `https://www.deepspeed.ai/docs`
• vLLM: `https://docs.vllm.ai`
• Model cards: `https://huggingface.co/{org}/{model}` — ALWAYS fetch for architecture-specific layer names, config keys, and training recipes
• Anthropic/Claude API: `https://docs.anthropic.com` — NOT `platform.claude.com` (does not exist). SDK reference: `https://docs.anthropic.com/en/docs/build-with-claude`
• OpenAI: `https://platform.openai.com/docs/api-reference`
• LangChain/LangGraph: `https://python.langchain.com/docs`, `https://langchain-ai.github.io/langgraph`

The Iron Law

NO IMPLEMENTATION WITHOUT A VALIDATED PLAN FIRST

A plan that hasn't been reviewed against documentation is a guess. Guesses waste GPU hours.

Phases

Phase 1: Understand — Build the Plan

**KB mode:** Call `build_plan(goal, constraints?)` IMMEDIATELY with the user's stated goal.

**Web mode:** Do NOT write any step content yet. First:

1. List the frameworks/libraries needed (one line each) 2. WebFetch the API reference page for EACH library — do ALL fetches BEFORE writing any plan text 3. For each `Class(kwarg=...)` you plan to use, find its `__init__` signature in the fetched docs and copy the exact parameter names 4. NOW write steps using ONLY the fetched parameter nam