Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Understanding and Investigation

The skills in this chapter build understanding before anyone edits code. Editing code that no one has traced is a common way for subtle regressions to reach production, and the risk applies to the agent as much as to you. Each skill also forces the agent to explain itself in terms you can check, which is how you supervise an agent that may know the code better than you do.

The chapter covers 7 skills:

  • /how explains how the code works now;
  • /why recovers the reasons it was built that way;
  • /recall rebuilds your own recent working context;
  • /in-your-own-words plays your goal back to you before work starts;
  • /figure-it-out designs a custom playbook when none of the built-in ones fits;
  • /interrogate asks adversaries to break a change and keeps only proven findings;
  • /blast-radius looks for breakage outside the diff and proves the fact that makes a change safe.

/teach, which combines /how and /why into one explanation, belongs to Learning and Communication.

/why: answer from the record, not from the code

Source

  • What it does: it explains the rationale behind a piece of code by reading the commits and pull request discussions that introduced it, followed by each later change. When that trail is thin, it consults other sources.
  • When to use it: questions such as “why does X work this way” or “why did we pick Y”, design rationale, regressions, postmortems, and the origin of a data-backed threshold. For runtime behavior, the description points you to /how instead.
  • How it proceeds: it cites what the authors actually wrote, labels its own inferences as inferences, and states which parts of the question the record does not answer. The guide notes that a missing explanation is itself a finding.
  • Caveats: the skill is deliberately constrained to the historical record, so it should not reconstruct a motive from the shape of the code. It runs only when invoked.

A typical prompt from the guide is /why was the retry limit set to five? does the reason still hold?. When you suspect that history explains a confusing design, the guide suggests asking for /why first and /how second.

/how: a working mental model of a subsystem

Source

  • What it does: it answers “how does X work?” with an architectural explanation pitched at a senior engineer who is new to the area and needs enough of a model to start working there with confidence.
  • When to use it: code walkthroughs before a change, explanations of runtime flow, onboarding, and questions about placement, ownership, and layering (“where should this live”, “which package owns this”, “is this the right layer”).
  • How it proceeds: if the scope is ambiguous, the agent states how it interprets the question and starts exploring; you can redirect it. It then spawns one subagent (subagent_type: generalPurpose, readonly: true) that explores the codebase and writes the explanation in a single pass. The main agent presents that output with only light edits for clarity or conversational context.
  • Caveats: the skill tells the main agent not to rewrite the subagent’s explanation substantially. Motivation and history are outside its scope; that is the job of /why.

The guide recommends asking the question you actually have, for example /how do we dedupe notifications? is there an n+1 when we look up subscribers?.

/recall: rebuild your recent working context

Source

  • What it does: before you start or resume work, it reconstructs your recent context on a topic and returns a compact brief on where things stand and what to do next. It draws on 2 records: your own chat history (what you did and decided) and the shared record, meaning source control, the issue tracker, chat and issue channels, long-form documents, and error tracking.

  • When to use it: prompts such as “recall my work on X”, “catch me up”, “what have I been working on”, or “where did I leave off”. It is most valuable for a feature with a long tail of bugs, because most of that story lives outside your own chats.

  • How it proceeds:

    1. Classify the request. Resuming one specific earlier chat is the job of the session-pickup playbook, and turning habits into a lasting skill is /automate-me. If you have already supplied a full state capsule (paths, branch, the change), the skill uses it and skips the mining.
    2. Lock the scope. It fixes the time window (“recent” defaults to the last 7 days), the topic, and the workspace, then states the scope back to you. It never narrows “all” to “recent” without saying so, and it does not read another project’s transcripts unless asked.
    3. Mine the chat history in parallel. Subagents on a fast, inexpensive model each take a slice of the transcripts, which Cursor stores under ~/.cursor/projects/<slug>/agent-transcripts/. Each one orders candidates by modification time, searches for the topic before reading, and reads only the relevant regions. All of them return the same fields per chat: topic, goal, decisions, open threads, struggles and corrections, and artifacts, each citing the chat UUID. The raw transcripts stay inside the subagents.
    4. Sweep the shared record. Whenever the topic names a feature, file, subsystem, area, or bug, one investigator subagent per source asks what the current state is, what has been tried and failed to hold, and what users are still reporting. This step is the default, and an empty result counts as a finding. Only pure activity recall (“what did I do this week”) skips it.
    5. Check live state. It verifies the pull requests, branches, and tickets that surfaced against reality with git and gh.
    6. Write the brief.
  • Output: the brief follows a fixed contract:

    PartContent
    CapsuleAt most 5 bullets on what the work is and where it stands
    ThreadsOne line each, with exactly one status tag such as [merged #N], [open PR #N], [in flight <branch>], [verified, uncommitted], [reverted #N], or [planned, not started]
    ProblemsAt most 5 recurring problems, including symptoms users keep reporting and fixes that shipped and were reverted
    Next moveThe single most useful next action, stated concretely
  • Caveats: adjacent features stay out of the brief unless they block this one. The brief is written through /unslop, cites chat findings by UUID and shared-record findings by their source, and has private context removed before any public output.

The guide suggests loading context before handing over new input, for example /recall my work on the virtualized list from yesterday, then read this bug report.

/figure-it-out: design a playbook when none fits

Source

  • What it does: for a task that matches no built-in playbook, such as a large migration or an ambitious multi-part change, it designs one. The first deliverable is the workflow itself: a sequence of phases whose rigor matches the task, run as a hypothesis loop, with a decision trail that a human can audit after stepping away.

  • When to use it: work for which no narrower playbook exists, especially when you want to leave the agent working and later confirm that it did the job correctly.

  • How it proceeds: it opens a todo list whose first item is to read the Principles section of /poteto-mode, then works through 5 phases.

    PhaseWhat happens
    A. FrameDefine “done” as a falsifiable predicate, quantify the scope, and choose a rigor level, biased towards high. One-way decisions and wide blast radius earn more rigor; reversible, low-stakes steps earn less. A multi-hour run gets one checkpoint where the framing and trade-offs are shown before work starts.
    B. Design the workflowSplit the work into atomic units that can land independently, riskiest unknown first. Build the verification setup and capture a baseline before any change, so results read as old value against new value. Use /architect (which runs /arena) only for one-way design decisions. Parallelize only across real seams, with a separate worktree or branch per worker. The written phase list is what the human reviews.
    C. Run the loopTreat each unit as an experiment: state a hypothesis, make the smallest change, measure it on the real artifact, keep it if it helped, and revert it if it did not. Verify each unit before starting the next. Every verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE, and INCONCLUSIVE is not a pass.
    D. Keep the audit trailLog decisions with /show-me-your-work, adding a row as each step lands. For ambitious work, commit the trail so the reviewer can read it in the pull request.
    E. Verify and hand backCheck the whole result against the Phase A predicate on the real product, not only the verification setup. Encode any recurring correction as a gate, lint rule, check, or script.
  • Caveats: when something passes too easily, the skill suspects the observation method before the system. Delegated work is paired with a judge; if a worker games a gate, the contract is reset and tightened, and if the gate itself is wrong, it is fixed in a separate change. The reply names the designed playbook, the rigor level and the reason for it, the path to the decision trail, what is verified, and what remains open.

/interrogate: adversarial review that keeps only proven findings

Source

  • What it does: it sends adversaries, each running on a configured model, to break a change or a design. A finding survives only when a run proves it. The skill reports findings and applies no fixes.
  • When to use it: requests such as “interrogate”, “adversarial review”, “multi-model review”, “challenge this”, “stress test this code”, “find blind spots”, or “tear this apart”.
  • How it proceeds:
    1. Frame. If you name a scope, that is the scope; if not, it covers the branch diff, running from the merge base with the base branch up to the working tree. Using /in-your-own-words, the agent restates the intent from your message, the commits, and the pull request description, and it asks you when the intent remains unclear.
    2. Fan out. It reuses the runner selection, the per-candidate worktrees, and the parallel launch from /arena, but reads the interrogate reviewers line of the model configuration instead of arena runners. Uncommitted changes are copied into each worktree. Each adversary is told to prove every finding with a run against the real code (a failing test, a repro script, or command output showing wrong behavior), to probe a prototype or the current tree when the target is a design, and to omit anything it did not run.
    3. Verify. The agent reruns each finding’s command. It keeps a finding when the output shows the failure and that failure breaks the intent, drops the rest, and merges findings that share a root cause.
  • Output: the restated intent; every verified finding with its command, its output, how it breaks the intent, and which adversaries found it; and, per adversary, the number of dropped findings and why. “No verified findings” is a valid result.
  • Caveats: style, naming, structure, and risks that would matter only after some future change are excluded from the start, because no run can prove them. The skill skips the cross-judge, base selection, and grafting phases of /arena: adversaries find different failures, so the verdict keeps every verified finding instead of choosing one adversary’s list. The guide advises reading the Dropped list as well, since you can override the verdict, and warns that an abstract plan with no code behind it gives the adversaries little to break.

/in-your-own-words: restate the goal before starting

Source

  • What it does: the agent restates, in its own words, what it believes your goals are and which problem you are trying to solve. The entire body of the skill is that one instruction.
  • When to use it: at the start of a large or ambiguous request, so that a misunderstanding surfaces before any code is written. /interrogate uses it to state the intent of a change.
  • How it proceeds: the agent reads your request and plays back the goal and the problem. If the restatement is wrong, you have found the misunderstanding cheaply.
  • Caveats: the output is the restatement and nothing more. The skill runs only when you type /in-your-own-words.

/blast-radius: find what breaks elsewhere, and prove the safety fact

Source

  • What it does: before a change ships, it looks for what the change could break outside the diff. The skill calls itself a companion to /how (what the code does) and /why (why it has that shape); blast radius answers what it breaks somewhere else. Listing callers is explicitly not the job, since grep finds them in seconds. The job is the breakage grep cannot show.

  • When to use it: “Blast radius of X”, “what could this break”, or a small diff that you do not yet trust.

  • How it proceeds:

    1. Read the change: the diff, the symbols it adds, changes, and deletes, and the behavior that differs even where the diff does not spell it out. Pull the pull request and its commits.
    2. Find the one fact the change is safe because of, for example that a call only drops cache entries that are already dead. If that fact holds, most risky cases are cleared at once, so this step deserves most of the time.
    3. Look where grep stops: the source of the libraries being called, including their pinned versions and local patches; timing such as microtasks, unmount and teardown, or Solid compared with React; and data paths a symbol search misses, such as API responses, database columns, wire formats, another language reading the same bytes, feature flags, or code 3 hops downstream.
    4. Be honest about each risk: give it a realistic probability and cost, cite a real file:line, keep confirmed risks separate from checked and cleared ones, and never invent a caller or an API. A search that finds nothing is still an answer.
    5. Prove the one fact with a script or test that runs the real code, and paste the result.
    6. For a large or wide change, run it as an arena, because different models catch different real bugs.
  • How sure the agent is: the skill grades each fact on a 5-step scale and asks the agent to say where it stopped:

    StepEvidence
    1The agent said so (worthless on its own)
    2It pointed at the line, either a real file:line or the library’s source
    3It walked the failure step by step and showed it cannot happen
    4It ran a script or test against the real code that fails loudly if the claim is wrong
    5It reproduced the behavior in the running app
  • Output: what the change does, including the non-obvious part; the safety fact, the step it reached, and its proof, or the word “unproven”; the risks with file:line, likelihood, severity, and how to check; what was cleared and why; and the cheapest test or repro to run before merging.

  • Caveats: the skill’s central warning is that a convincing writeup is worthless as evidence, because it reads the same whether or not it is true. The result is written through /unslop, and private details are removed before anything goes public.

Two /poteto-mode playbooks complement these skills. The Investigation playbook handles a read-only question; a prompt that ends with “don’t change any code yet” routes there, and it returns a cited explanation or, for a choice between options, a recommendation with a trade-offs table. The Session pickup playbook takes over a branch that another agent left mid-flight, treats the prior trail as authoritative, and verifies inherited claims against the original goal. Both are covered in the playbook chapters.