Memory
# AI Coding Debugging Playbook Working draft — practical reference for AI coding-agent debugging (opencode, Claude Code, Cursor, Aider). ## Core loop Observe → Hypothesize → Test → Verify. Ask: which stage is the agent skipping? ## Spin cycle detection A spin is likely when the agent repeatedly edits the same files without changing the error, alternates hypotheses without new observations, re-reads files without a stated question, or broadens scope to adjacent code. Key tell: the error stays the same while the agent’s explanation changes. ## Intervention ladder 1. Force observation: "Stop editing. Add logging at [point] that shows [value], run it, and paste the raw output. No code changes until we see the data." 2. Narrow scope: "Current goal: make [function] return [value] for [input]. Nothing else." 3. Name the failure mode: "You are hypothesis cycling: [evidence]. List observed facts vs guesses, then pick one observable to check." 4. Reset the session when interventions fail or context is polluted. ## Restart handover template Goal: [one sentence] Confirmed facts (observed, not speculated): - [fact] Dead ends (do not retry): - [failed hypothesis and why] Current state: [changes vs committed] Next step: [exactly one] Persist if real runtime evidence was gathered, the spin is young, and the problem is isolated. Start fresh after 3 failed hypotheses without new observation, when the agent defends prior changes, contradicts earlier findings, or reforms the spin after two interventions. ## Prompt patterns - Show me the data: before changing anything, log [value] at [location], run [command], paste raw output. - Task scope: Current step: [action]. Done means: [observable criterion]. Do not touch: [scope]. - Meta-commentary: You are [failure mode]. Specifically: [evidence]. Reset to observation: [what to inspect]. - Constraint: Hard rule: no edits until runtime output demonstrates the failure; label hypotheses as hypotheses. Put durable versions in AGENTS.md. ## Task structuring Give each agent chunk one responsibility and one observable done-state. Include relevant paths/contracts and explicit non-goals. If the done condition cannot fit in one sentence, split the chunk. Sequence chunks so each is verified before the next begins. ## Memory rules Codebase memory (AGENTS.md/docs/README) holds architecture invariants, contracts, repeated corrections, hard-won dead ends, and setup gotchas. Session memory holds current task state and in-flight hypotheses. If the agent needed the same correction twice, promote it to codebase memory. ## Failure modes - Hypothesis cycling: theories/edits without new data. Force runtime observation. - Type-driven debugging: types and schemas are trusted over wire/runtime values. Print data at the boundary. - Context pollution: stale theories and long history overpower the current goal. Start a fresh session with handover; do not argue about history. - Sunk-cost reasoning: patch-on-patch or defence of an earlier approach. Prompt: "Evaluate reverting [change] and trying [alternative] as equally valid options; work done is not a factor." ## Quick reference Same error after 3+ edits → stop editing; log a specific value; run and paste output. Rotating explanations → list observed facts vs guesses. Types look correct but behavior fails → print actual boundary values. Contradicts earlier correct findings → fresh session plus handover. Patch-on-patch/defending approach → evaluate revert as an equal option. Multi-step thrash → one step, binary done-state, explicit non-goals. Status: draft. Expand practical examples with real coding-session transcripts over time.
[Update Sep 2, 2026]: ---
## Addition: Artifact–Mechanism Conflation
### Failure mode
- **Looks like:** treating a tool error or one endpoint response as proof of the underlying platform mechanism. Example: "the CLI says `worker_loaders` is an unexpected field, therefore the dispatch namespace rejects it"; or "unknown path returns Sphere not found, therefore routing is not slug/path based."
- **Why agents do it:** tools produce crisp, authoritative-looking text, while the mechanism producing that text is hidden. The agent completes the causal chain from a partial observation because a confident explanation is easier than designing a discriminating test.
- **Loop stage broken:** Hypothesize and Verify. The agent turns an artifact into a mechanism claim without a control, source inspection, or direct platform observation.
- **Intervention:** require an evidence label and a discriminating control.
```
Separate this into: (1) raw artifact, (2) supported conclusion, and
(3) unverified mechanism theory. Do not promote (3) to a finding.
Give me the cheapest control or source inspection that would distinguish
the competing explanations, then run only that.
```
### Control-first rule
Before diagnosing routing, bindings, deployment behavior, or another hidden mechanism, run a known-good control. A successful control makes the failure population meaningful; without it, an error from an unprovisioned or invalid target may only prove that validation occurred.
Prompt:
```
Run one positive control and one failing case. State what each result
would prove and what it would not prove. Do not infer the mechanism
until the control result is available.
```
### Real example: Wrangler field error vs platform rejection
**Situation:** A deployment reports `worker_loaders` as an unexpected field. An agent concludes that the dispatch namespace rejected the loader binding and, after several unknown-slug requests return `{"ok":false,"error":"Sphere not found"}`, further concludes dispatch is not path/slug based.
**Bad assessment:**
```
worker_loaders was rejected at upload. Dispatch is not slug-based.
No runtime test is possible.
```
**Regrade:**
- The deploy log itself identifies Wrangler `3.74.0`, while v4 is available. The older CLI predates the field, reports "Unexpected fields", and may strip the binding before upload. This is a local CLI artifact; it does not establish a platform rejection.
- Identical `Sphere not found` responses for several unprovisioned slugs establish that unknown slugs are gated before customer code. They do not establish a routing mechanism.
- The missing five-minute checks were: curl a known provisioned slug as a positive control, then inspect the dispatch source for the `Sphere not found` branch and slug-to-script mapping.
**Better debugging sequence:**
1. `curl -i https://sphere.docuclear.ai/test-alpha/` for a provisioned customer. Confirm it returns a Sphere response rather than `Sphere not found`.
2. Inspect `dispatch/` to identify the exact `Sphere not found` branch and mapping behavior.
3. Upgrade to `wrangler@4`, or use the platform API deployment path with loader-binding metadata.
4. After a successful deployment, GET the Worker via the Cloudflare API and retain the materialized `worker_loader` metadata as the contract for future fleet deployments.
**Lesson:** raw artifacts can be excellent while the conclusion drawn from them is wrong. Always label facts separately from mechanism theories, and prefer a cheap discriminating control over a sophisticated inference.
Tags: playbook, ai-coding, debugging, agents, draft, project:ai coding debugging playbook, kind:semantic, volatility:state — Source: perplexity — 2026-09-02 13:15:43 UTC