---
name: using-cascade
description: Drive the CASCADE tool to get real work out of a small, local LLM on a complex, fuzzy task — primarily over its MCP server (the solve/resolve/inspect tools), where you act as CASCADE's external Resolver. Invoke when asked to "use cascade", "solve X with cascade", drive a CASCADE run over MCP, resolve a CASCADE elevation, or review/steer a CASCADE knowledge graph. This is about DRIVING cascade as an operator — not building the cascade codebase (that's /software-lead).
---

# Using CASCADE (operator's guide)

You are operating **CASCADE**: a methodology + engine for getting frontier-quality work out of a
**small, local LLM** (running on Ollama) on a task too big or too fuzzy for one-shot prompting.

**As an agent, you drive CASCADE over its MCP server, not the command line.** The pitch is
**token offload**: instead of burning your own expensive context doing a big decomposable job, you
hand the objective to CASCADE, which decomposes and executes it on a small, cheap, local model. You
spend a handful of tool calls; the small model spends the tokens. (Humans drive the same engine via
the CLI + an Obsidian vault — see the last section; both surfaces drive the *same* engine and the
*same* durable on-disk state.)

## The one thing to internalize
The model is **small**. It fails when the *decision entropy of a single step* exceeds its
working-memory headroom — not because the overall task is big. CASCADE shrinks the entropy: it grows
a rich knowledge graph so the model knows enough, then drives decomposition down until every task it
executes is **small enough to do reliably** — roughly "write one function with one test." A small
model also **cannot enumerate its own ignorance** and **lacks context and awareness** you take for
granted. So *you* supply the judgment, the unknown-unknowns, and detailed feedback when it elevates.
CASCADE is a collaboration, not an autopilot.

## How CASCADE works (two stages)
1. **Interrogate → knowledge graph.** The model asks a question → answers it → each answer raises
   sub-questions → recurses depth-first. Research questions are answered by *grounding* (fetching
   real docs/APIs); capability questions by a tool registry; design/decision questions it can't make
   are **elevated to you**. Output: a durable `knowledge.json`.
2. **Plan → execute.** The task DAG is *projected out of* the completed knowledge graph (not authored
   upfront), then leaves execute bottom-up — agentic: they write files, run commands. Each task's
   context is only its deepest linked knowledge node's **path-to-root** — the specific fact plus the
   chain that situates it, and nothing more.

Because context is scoped per-task, **a big knowledge graph is good, not wasteful.** A detailed,
multi-layer graph is what lets the model produce narrow, targeted tasks instead of one giant vague
one.

## You are the Resolver (the MCP role)
CASCADE's operating rule is **"elevate when stuck"**: when the small model can't make progress on a
node, it doesn't thrash — it routes the node to a more capable **Resolver**. Over MCP, **that
Resolver is you.** You play exactly the role a person plays at the vault: kick off a run, CASCADE
works on the small model and **elevates back when stuck**, you supply resolutions, CASCADE resumes,
you read the result.

> **You own the knowledge gate — it is NOT auto-approved.** In the CLI, after Stage 1 a person
> reviews the knowledge graph and decides *build it* or *keep asking*. Over MCP you get the **same
> gate**: when Stage 1 finishes cleanly, `solve` returns `status: "awaiting_knowledge_approval"`, and
> you answer it with the **`advance`** tool — `action: "approve"` (build it) or
> `action: "keep_generating"` (deepen the graph one more level and ask again). This is your highest
> -leverage moment: **don't reflexively approve a thin graph** — `inspect` it, and keep generating
> until it's rich enough to project small, specific tasks.

## The MCP server

Register CASCADE's stdio MCP server with your client (run `cascade init` once first so `config.json`
and the tool cache exist):

```json
{ "mcpServers": { "cascade": { "command": "cascade", "args": ["mcp"] } } }
```

It exposes **four tools**. State is durable on **disk, not memory** — every run owns a **workdir, and
that workdir path IS the `run_id`** the tools key on, so a run survives across calls and restarts.
Each `solve`/`resolve`/`advance` call **blocks** until the run reaches the next gate or terminal point:

- **`solve`** — start a run. Input: `objective` (required — the literal goal text, not a path),
  `constraints` (optional list — each HARD constraint as its own string; pass them here, don't
  concatenate into the objective), `acceptance` (optional list of acceptance criteria), `out`
  (optional workdir; empty → a `cascade/` dir in the cwd, returned as `run_id`), `project_root`
  (optional, read-only FS grounding), `web_search` (optional, needs an Ollama API key). Returns the
  run result.
- **`advance`** — answer the knowledge gate. Input: `run_id` (required), `action` (required:
  `"approve"` to accept the graph and build it, or `"keep_generating"` to deepen the knowledge
  frontier one breadth-first level and re-ask the gate). This is the agent's y/n at the CLI gate.
- **`resolve`** — advance an `elevated` run (something got *stuck*, distinct from the gate). Input:
  `run_id` (required), `question_answers` (map of Stage-1 question id → answer text),
  `task_resolutions` (map of Stage-2 task id → optional guidance; empty = pure unblock, non-empty
  flows up into the knowledge graph as context). Re-runs and returns the next result.
- **`inspect`** — read a run's state read-only, without advancing it. Input: `run_id`. Same result
  shape; use it to read the knowledge graph / artifacts and re-check status.

**Run result shape:** `run_id` (always); `status` = `"awaiting_knowledge_approval"` (Stage 1 finished
cleanly — call `advance`), `"elevated"` (stuck — call `resolve`), or `"done"`. When `elevated`: `kind`
(`"stage1_questions"` | `"stage2_tasks"`) and `elevations` — a list of `{ id, prompt, reason }` items
you address (`id` is the key you supply back in `resolve`). When `done`: `summary` and `artifacts`
(durable files under `run_id`: `tree.json`, `knowledge.json`, `links.json`, `metrics.json`, `nodes/`).
Read artifacts directly off disk.

**The loop:** `solve` → (`awaiting_knowledge_approval` → `advance keep_generating`)\* →
`advance approve` → (`elevated` → `resolve`)\* → `done`, with `inspect` as a read-only probe any time.
Note the two distinct pauses: the **gate** (Stage 1 finished, you decide build-vs-deepen → `advance`)
and an **elevation** (a specific node got stuck → `resolve`).

## Operating it well over MCP
This is where the operator wisdom maps onto your tool calls:

1. **Write a rich, specific `objective`.** It's the seed the whole interrogation grows from. State
   the goal, hard constraints, and how you'll know it's done. Vague seed → vague graph → oversized
   tasks.
2. **Ground it when you can.** Pass `project_root` when the task is about existing files (read-only,
   confined to that subtree). Pass `web_search` for research-heavy tasks. **With grounding off the
   small model is far likelier to hallucinate** — weight your accuracy checks accordingly.
3. **Resolve elevations with detailed, explicit answers.** When `status` is `elevated`, each item is a
   call the small model couldn't make. **Be detailed and explicit** — it lacks the context and
   awareness you have; don't assume it infers anything. Spell out the answer, the why, and concrete
   specifics (formats, names, shapes). Terse resolutions waste a whole re-run. For `stage2_tasks`,
   non-empty guidance flows up as context the executing leaf will see.
4. **`inspect` the knowledge graph and check it for accuracy.** Read `knowledge.json` under `run_id`.
   These are **small local models — treat facts as potentially hallucinated until checked**, especially
   with `web_search` off: verify API shapes, URLs, agency/field names — the specifics tasks get built
   on. A wrong assumption caught here never becomes wrong code.
5. **At the gate, deepen before you approve.** When `solve` returns `awaiting_knowledge_approval`,
   `inspect` the graph first. If it's shallow — facts too coarse, tasks it would project still too big
   or vague — call `advance keep_generating` to grow it another level, and repeat. Only `advance
   approve` once the graph is rich and accurate enough to project small, specific tasks. Approving a
   thin graph is the main way an MCP run goes wrong. **Score the graph against the rubric below to
   make this call.**

## The gate rubric: the high-schooler test
Every time `solve` returns `awaiting_knowledge_approval` you face one decision: **`advance approve`**
(project tasks and build) or **`advance keep_generating`** (grow the graph one more level). This is
the test for that decision — the single question to keep asking until the answer is yes.

**The bar.** The executor is a small model — treat it as a **diligent high-schooler**: it follows
instructions exactly and works hard, but it has **no domain context, no judgment, and no way to tell
a real fact from a plausible-sounding one.** So `inspect` the knowledge graph and ask:

> *Could a high-schooler, handed only the knowledge in this tree and nothing else, build the thing —
> without making a single judgment call of their own?*

If yes, approve. If they'd have to guess, infer the intent, go look something up, or choose between
options, the graph isn't done — `keep_generating`. That degree of hand-holding **is** the bar; the
knowledge has to do the thinking so the model only has to do the typing.

Score the graph on these six. **All must pass to approve**; any fail means it's not good enough yet:

1. **No decisions left.** Every design/intent choice is already made *in the graph*. The executor
   never has to decide *what* to build or *which* of several ways to build it — only *do* the stated
   thing. (This is the entropy bar: ~zero open decisions per step.)
2. **Concrete, not gestural.** Facts are exact specifics — endpoints, field names, types, formats,
   signatures, file paths — not "use an appropriate X" or "handle errors". A high-schooler can't
   supply the missing specific; it has to be on the page.
3. **Grounded, not guessed.** Every world-fact a task will be built on (API shapes, URLs, names) is
   grounded or you've verified it via `inspect`. With `web_search` off especially, an unverified fact
   is probably hallucinated — and a high-schooler can't catch it.
4. **Complete coverage.** Every clause of the `objective`, every `constraint`, and every `acceptance`
   criterion traces to a knowledge node. No corner of the ask is silent.
5. **Projects small.** The graph is granular enough that the tasks it would project are "one function,
   one test"-sized. If you can already see a leaf that's a big vague leap, the graph is too shallow
   there.
6. **Self-contained.** Nothing load-bearing rests on "obvious" background the high-schooler lacks —
   domain conventions, the real intent behind the ask, tribal knowledge. If it matters, it's in the
   tree.

**The decision:**
- **All six pass → `advance approve`.**
- **A gap, vagueness, or missing branch (fails 1, 2, 4, 5, or 6) → `advance keep_generating`,** then
  re-run the test. Deepening is the fix for *thin*.
- **A *wrong* fact (fails 3) is a hard block on approval, and deepening won't fix it** — generating on
  top of a hallucination just grows more of it. Don't approve: re-ground the run (turn on
  `web_search` / `project_root`), and steer the bad assumption out via `resolve` guidance as tasks
  elevate, rather than building on it.

**Don't over-ask, either.** The bar is *enough* hand-holding, not infinite depth — once the six pass,
more `keep_generating` just burns the small model's tokens. In practice the dominant failure is
**approving too thin**, so lean toward one more level when unsure; but a graph that already projects
small, grounded, decision-free tasks is *done* — approve it and build.

## Driving it as a person (CLI + Obsidian)
When a *person* is in the loop instead of (or alongside) an agent, the same engine is driven from the
command line, and the knowledge graph is steered through an **Obsidian vault** — a richer, free-form
version of the same gate, where you don't just deepen but also edit facts, relink, and retag.

```sh
cascade init                                            # detect Ollama, create cache + config.json
cascade init task <name> --out t.md                     # scaffold a fillable seed-task template
cascade solve --root t.md --out runs/x                   # interrogate → human review gate → plan → execute
cascade vault render --base runs/x --vault ~/Obsidian/x          # graph → Obsidian markdown
cascade vault ingest --watch --base runs/x --vault ~/Obsidian/x  # live one-way: markdown edits → graph
```

In the vault you never edit JSON: answer a blocked question under its `## Answer` heading, correct an
assumption, add a fact the model missed, reshape the graph via `[[links]]` (hard edges: `Parent::`,
`Raises::`, `Depends::`; `#tags` are soft labels), and — the two calls that are explicitly the
person's — *is this atomic enough to execute?* and *keep decomposing or start building?* This is the
human path; **don't run an attended human-in-the-loop run with `--yes` or headless** — that strips out
the person the system exists to include. (`--yes` auto-approves both gates; demos/CI only.) Key `solve`
flags: `--max-questions <n>` (Stage-1 budget, default 64), `--review-depth <n>`, `--project-root`,
`--web-search`, `--eager`, `--verbose`/`--quiet`. Full
[command reference](https://github.com/robinonsay/cascade/blob/main/docs/guide/03-commands.md).

## Don'ts
- Don't hand CASCADE a vague one-line `objective` and expect a good result — the seed sets the ceiling.
- Don't trust an unverified fact from a small local model, especially with `web_search` off; `inspect`
  and check before you build on it.
- Don't give terse resolutions and expect the model to fill the gaps. Be explicit.
- Don't forget to read `run_id` back from a fresh `solve` — you need it for every `resolve`/`inspect`.

## Learn more
The [CASCADE README](https://github.com/robinonsay/cascade), the
[MCP server reference](https://github.com/robinonsay/cascade/blob/main/docs/mcp-server.md), and the
full [User Guide](https://github.com/robinonsay/cascade/tree/main/docs/guide) — install → first run →
steering in Obsidian → reading the result, with a complete weather-app tutorial.