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

Playbooks: Troubleshooting

This chapter covers the 5 playbooks that respond to “something is wrong”. They differ in how far they go: Bug fix and Perf issue end by opening a PR (Perf issue with the measurement cited in it), and Investigation, Runtime forensics, and Trace forensics stop at an explanation or a diagnosis and change no code.

A few terms recur across all 5:

  • Control skill: a skill that drives the real product the way a user would, such as control-ui or control-cli from the separate cursor-team-kit plugin. “The matching surface” means the place where the problem actually shows up (the running UI, the CLI, the IDE).
  • Configured model: the model a code-writing subagent runs on. /setup-pstack writes one line per role into ~/.cursor/rules/pstack-models.mdc, and each playbook reads its own line. Where no line exists, the default is claude-opus-5-5-xhigh-fast.
  • Throughput checkpoint: the 4-item plan for parallel work (blocking first steps, independent workstreams, shared mutable state, smallest safe decomposition) that the Feature playbook writes before delegating; see Planning and starting. The read-only playbooks in this chapter reduce it to a single line marked n/a.

Bug fix: every shipped line traces to evidence

Source: bug-fix.md

Bug fix is the playbook for repairing broken behavior. The agent in charge keeps planning, review, and verification for itself and hands both the investigation and the implementation to subagents. Its central rule is scientific: each line that ships must be justified by something observed at runtime, and a defensive extra change that “might help” counts as an untested hypothesis, so it stays out of the diff.

The steps:

  1. Reproduce the bug personally on the matching surface through the control skill. This applies even when some debugging protocol suggests asking the user to reproduce it. The agent may ask the user only after it has driven the control surface as far as it can, and only with a specific reason why that surface cannot reach the target. If the bug does not appear on demand, the agent synthesizes the trigger, tightens the conditions, or adds instrumentation until it does.
  2. Binary-search the cause. The agent lists candidate hypotheses and eliminates them until one survives. A trace of the affected subsystem and the why skill (for regression history) supply the first candidates. Each round picks the split that removes the largest share of the remaining problem space, gathers runtime evidence, and discards what the evidence rules out. Where program state is unclear, the agent adds logging and reads it while the code runs. A long hunt can be driven with Cursor’s /loop command. The surviving mechanism must be confirmed with runtime evidence before any design work starts.
  3. Plan the fix. A fix that crosses a function boundary goes through the architect skill first. Implementation goes to a subagent on the configured bug-fix model, with a precisely stated scope.
  4. Verify on the same surface. The original reproduction must now pass. A result that is “inconclusive”, or one taken on a different surface, does not count as a pass and must be reported as such. Unit tests demonstrate how individual branches behave; they cannot show that the bug is absent.
  5. Order the commits so that the failing reproduction appears in history before the fix. When the bug has a cheap local test, the tdd skill supplies the failing-test-first rhythm; when a test would be expensive or integration-heavy, the agent skips it. The playbook calls this the canonical case of the principle-sequence-verifiable-units skill.
  6. Run Opening a PR (see Shipping).

When evidence refutes a hypothesis, the agent reverts whatever that hypothesis motivated. Only the smallest change the evidence supports ships.

The final reply states what was broken, the root cause, the fix, and how it was verified. It includes the reproduction output twice, failing and then passing, pasted verbatim.

Investigation: answer the question, change nothing

Source: investigation.md

Investigation handles requests for understanding or for a decision, and it is strictly read-only. The deliverable is either an explanation with citations into the code or, when the user must choose between alternatives, a recommendation. The agent owns the answer itself.

The steps:

  1. Trace the code that the question concerns. Questions about motivation (“why is it built this way?”) also go through the why skill.
  2. Record the throughput checkpoint as one line: throughput checkpoint: n/a, read-only investigation.
  3. Write the output. An explanation uses 5 fixed sections: Overview, Key Concepts, How It Works, Where Things Live, and Gotchas. A decision request gets a recommendation backed by a trade-off table.
  4. Run the unslop skill over the reply before sending it.

This playbook opens no PR, starts no babysit, and does not call architect. If the investigation turns out to be the first stage of a code change, the agent stops, returns to the user, and re-routes the work to Bug fix or Feature.

When the user asks “are we sure?”, the reply must contain the agent’s actual judgment and its reasons. If the premise of the question is wrong, the agent says so, in line with the candor rule in the Autonomy section of poteto-mode.

Perf issue: tie every fix to a measurement

Source: perf-issue.md

Perf issue treats a one-off performance problem as a measurement story that the agent owns. Every proposed fix is linked to a number, and reading the source is never accepted as a substitute for running it.

The steps:

  1. Capture a baseline trace through the matching control skill. The baseline, and every later number, is vetted with the benchmark-checklist skill, which asks what limits the number and whether the work really ran inside the timed region.

  2. Trace the code to ground hypotheses. The agent may not claim a performance ceiling before it has run the code. Candidate fixes follow the 7 performance mantras, quoted here from the playbook, cheapest first. The search stops as soon as an earlier mantra reaches the target:

    OrderMantra
    1“Don’t do it.” (Stop work whose result nothing uses, instead of making it cheaper.)
    2“Do it, but don’t do it again.”
    3“Do it less.”
    4“Do it later.”
    5“Do it when they’re not looking.”
    6“Do it concurrently.”
    7“Do it cheaper.”
  3. Plan the fix from the trace. A boundary-crossing fix goes through architect first. A subagent on the configured perf-issue model implements it, the agent reviews the diff, and then captures a post-fix trace. Following principle-sequence-verifiable-units, each attempt is verified before the next one begins.

  4. Parse and compare the artifacts, for example by loading JSON traces into sqlite and diffing them. An inconclusive result or a measurement on the wrong surface is flagged and never counted as a pass.

  5. Cite the measurement in the PR.

  6. Run Opening a PR.

For sustained improvement against a metric, as opposed to a single fix, the playbook points to Hillclimb (covered in Shipping).

The reply gives the baseline number, the post-fix number, the delta, and the path to the artifacts.

Runtime forensics: instrument the live process

Source: runtime-forensics.md

Runtime forensics applies when the symptom is happening now, in a process that is still running. The agent owns a diagnosis, and it is expected to gather live signals from that process instead of building a theory from the source. The deliverable is a cited diagnosis; a fix is out of scope unless the user asks for one.

The steps:

  1. Capture the live signal on the matching surface through the control skill. The kind of capture depends on the symptom: a CPU profile for a process that spins, a heap snapshot for a leak, a CDP (Chrome DevTools Protocol) trace for a visual glitch. The point is a real artifact on disk.
  2. Reduce the artifact to the decisive evidence: the function on the hot path, the retainer chain that keeps a leaked object reachable from a GC root, or a loop that fires without any input. Large artifacts are parsed in a subagent, per principle-guard-the-context-window, so that only the reduced finding enters the main thread.
  3. Prove the mechanism before trusting it. Cheap confirmation methods include injecting instrumentation into the running process through CDP eval, or hot-patching the live code without a reload.
  4. Map the finding to source: the file, the symbol, and the line that allocates memory or schedules the work.
  5. Record the throughput checkpoint as one line: throughput checkpoint: n/a, read-only forensics.

The reply lists the captured signal, the reduced finding, how the mechanism was proved, the source location, and the artifact paths. Once the cause is known, the work is handed to Bug fix or Perf issue.

Trace forensics: diagnose from an existing capture

Source: trace-forensics.md

Trace forensics is the counterpart of Runtime forensics for the case where the capture already exists: a cpuprofile, a .json.gz trace, a spindump, or a heap snapshot. The playbook treats the artifact as a fixed dataset to be read, so nothing is re-run. Tooling stays generic (a DevTools or trace parser, a text editor for a spindump, ordinary heap tooling) instead of being built anew for each format.

The steps:

  1. Identify the format and open it with a suitable tool. Large artifacts are parsed in a subagent, again per principle-guard-the-context-window.
  2. Make the artifact queryable before reading it. The usual move is to dump it into sqlite with one row per sample, frame, or node.
  3. Narrow to the cause. With CPU time, query the frames holding the largest share of time and descend the call tree along the hot path. With a leak, trace the retainer chain from the leaked object up to a GC root. With a spindump, locate the thread that is either stuck on the CPU or blocked, along with the reason it is waiting.
  4. Attribute to source using the symbols in the artifact itself. A hot frame without a file, symbol, and line is not yet a diagnosis; the agent either resolves the symbols or states plainly that the artifact lacks them.
  5. Confirm with a paired capture if one exists, by diffing the before and after artifacts. Without a pair, the result is presented as the strongest hypothesis the artifact supports, and it is never called a confirmed cause.
  6. Hand back a cited diagnosis without a fix, unless one was requested, and route to Bug fix or Perf issue once the cause is known. The throughput checkpoint is the same one-line n/a as in Runtime forensics.

The reply names the artifact and its format, the reduced finding, the source location, the artifact paths, and whether a paired capture confirmed the result.