Agent | kaguc — Writing to understand systems.

27 days of AI-assisted development: a retrospective in numbers

Wed, 29 Jul 2026 00:00:00 +0000

Also in 中文. Part 14 of the Engineering LLM Applications series — the closing installment. The previous thirteen articles discussed mechanisms; this one returns to the 27 days that produced them.

Scope and accounting rules

From 2026-06-10 to 07-06, one person plus a coding agent (Claude Code) built, from scratch, the AI writing agent this series has been citing throughout. Because the project enforced a paper-trail rule from day one — every development conversation produces a devlog entry — this retrospective does not rely on memory. The data comes from 94 devlogs, git history, a count of the test directory, and a line-by-line sum of the research experiment’s usage.jsonl. The article is organized as four ledgers: output, discipline, debt, and conclusions. Approximate figures state their accounting basis; anything the logs marked as “suspected cause” stays hedged here.

The output ledger

Dimension	Number	Basis
Time span	27 days	2026-06-10 → 2026-07-06
Devlogs	94 entries	docs/devlog/, one per conversation; single-day peak of 27 (06-15)
Backend	28 modules / 8,352 lines	line count over backend/app/*.py
Clients	Web frontend + Tauri desktop build	PyInstaller-frozen backend + Tauri shell + bundled TinyTeX
Tests	351	count of def test in backend/tests
Research experiment	4 days / 20 commits	writing-judgment-distill, 06-18 → 06-21
Experiment LLM usage	3,511 calls / ~7.94M tokens	summed from results/usage.jsonl: ~5.22M input + ~2.72M output
Product pivots	3	manual workflow → local web app (06-10) → SaaS (06-12) → standalone desktop (06-22)

Two notes. First, output came in bursts: of the 94 devlogs, 27 landed on 06-15 alone and 14 on 06-11 — at the granularity of “one conversation advances one feature”, parallel sprints became the norm. Second, the third pivot (SaaS → standalone) is worth recording as method: every change was flag-gated and off by default; on landing day, all 47 backend tests passed in the default configuration — zero regression in SaaS behavior. The test baseline then grew to 344 passed (devlog figures), with the repository ultimately counting 351 test functions.

The discipline ledger: which conventions paid for themselves

Of the working conventions written into CLAUDE.md on day one, four were repeatedly proven worth their cost by day 27.

A devlog for every conversation. Fixed format: goal / what was done / key decisions / files changed / leftovers. The direct payoff is this article — a retrospective that needs no recollection. The larger payoff is attribution: the venv-pollution debt described below can be reconstructed as a complete causal chain from two log entries one hour apart. The research experiment ran the same regime — journal entries are append-only and machine-readable results go into runs.tsv — which is what allowed the summary document to state that “all numbers come from recorded experiments.”

Git as the safety net: commit every state that runs. The very first conversation ended with git init and a commit (f705076, 115 files). None of the three pivots ever lost work: the standalone pivot branched from the current HEAD with zero disturbance to the working tree, preserving the experiment branch’s 20 commits intact. “If the AI breaks it, roll back” went from slogan to daily practice over the 27 days.

base_docs is read-only. Domain material, few-shot samples, and test data live in a read-only zone; generated artifacts go into separate directories. Through three pivots and dozens of generation rounds, the evidence base was never contaminated.

One feature per change. Twenty-seven devlogs in one day is not 27× productivity; it is 27 scope-narrowed conversations, paired with “one commit plus tests per feature.” This is the deterministic boundary applied isomorphically to the development process itself: narrow the scope of every change, and defend existing assets with deterministic gates — tests and git.

The debt ledger: verification debt and environment debt

Verification debt, case one: a batch verification that failed wholesale. On 07-05, to benchmark the agent pipeline against the state of the art, a 105-agent web-research workflow was run. Its adversarial verification stage failed as a whole batch when the subscription’s session quota was exhausted: all 25 claims came back unverified. The only remedy was manual: pick the 3 papers carrying the most weight — and most likely to have been fabricated by a retrieval agent — and check them line by line against the arXiv originals. One had its core numbers confirmed (revisions regress 16–27% of already-covered content); one was genuine but required two corrections to how it had been cited; one was architecturally real, with its specific numbers absent from the abstract and therefore left marked unverified. The machine produced 25 conclusions in one evening; human verification covered 3. That gap is the shape of verification debt.

Verification debt, case two: a conclusion frozen for want of a human anchor. The 4-day controlled experiment obtained highly direction-consistent results under LLM-judge scoring (see part 12); the 30-pair anonymized blind-evaluation sheet was exported, and the machine’s verdict on the same items was B=20 / A=3 / tie=7. But human scores were never collected. The summary document therefore had to settle for: H1 is “a strong candidate with method-level evidentiary support — not established.” The one step that 3,511 calls and ~7.94M tokens could not buy was precisely the only step independent of the machine.

Environment debt: one experiment’s contamination, detonating an hour later. On 06-23, minted code highlighting was trialed for the standalone build; the conclusion was that it is unworkable under frozen distribution, so the build reverted to the safe default. But the experiment’s pip installs had touched the shared venv. One hour later (by log timestamps), the packaged desktop app failed to start; one layer of the four-layer root-cause analysis was a missing pydantic_core — the log annotates it as “suspected cause: the minted detour’s pip installs overrode the pydantic version.” The recorded lesson, verbatim: clean up the venv after temporary experiments.

The methodological conclusion: the bottleneck moved to verification and judgment

The output ledger shows AI assistance expanding the engineering scale one person can drive by an order of magnitude — a full-stack application, desktop distribution, 351 tests, and a controlled experiment advancing simultaneously within 27 days. That is a case judgment against the author’s own manual pace, not a controlled measurement. But the three debts point to a single conclusion: once scale expands, the bottleneck moves from production to verification and judgment. Twenty-five claims needed a human reading the originals; H1 needed 30 human blind evaluations; the venv contamination needed a human-driven layer-by-layer diagnosis. Every conclusion the machine produces needs an anchor independent of the machine — deterministic tests, git history, arXiv originals, human scores. The mechanisms discussed across the first thirteen articles of this series are, in the end, ways of manufacturing such anchors at scale.

Where this retrospective does not apply

N=1. One developer, a greenfield project, no collaboration friction, no legacy code. These numbers are a record, not a statistic; extrapolating to teams or brownfield systems has no basis here.
Output metrics are not outcome metrics. Lines, tests, and devlogs measure production volume; the 27 days include no user data, so product value went unmeasured.
Devlog count is not workload. Devlogs count conversations; a 27-entry day reflects short, scope-narrowed sessions, not 27× throughput.
The token figures cover only the experiment’s metering. usage.jsonl records the research experiment’s API calls only; the coding agent’s own usage during main-app development is not metered there, so total cost cannot be extrapolated from these numbers.
“Zero regression” was purchased in advance. Three pivots without incident rested on flag-gating plus a test baseline; without that baseline, the same speed produces silent breakage.

References

The three papers manually re-verified after the 105-agent workflow: Beyond Single-shot Writing: Deep Research Agents are Unreliable at Multi-turn Report Revision (arXiv:2601.13217; core numbers checked against the original); PaperOrchestra: A Multi-Agent Framework for Automated AI Research Paper Writing (arXiv:2604.05018; genuine, with two citation corrections); RP-ReAct (arXiv:2512.03560; architecture genuine, specific numbers not independently verified).
Experiment data and statistical basis: the writing-judgment-distill SUBMISSION_SUMMARY and results/usage.jsonl.

Controlled revision in reflection loops

Wed, 29 Jul 2026 00:00:00 +0000

Also in 中文. Part 10 of the Engineering LLM Applications series.

The problem: why “draft → self-revise × N” often makes things worse

The standard closing act of an autonomous generation pipeline is a reflection loop: once the first draft exists, let the model critique and revise it for a few rounds. Intuition says more rounds can’t hurt. Our first implementation was a direct transcription of that intuition — critique produced a prose commentary, revise rewrote the whole document accordingly, and the new draft replaced the previous one unconditionally:

msgs.append({"role": "assistant", "content": draft})
yield {"type": "draft", "text": draft} # keep this version unconditionally

Empirical measurement says the intuition is wrong. arXiv:2601.13217 (Beyond Single-shot Writing: Deep Research Agents are Unreliable at Multi-turn Report Revision — we read the arXiv original to verify it) measured multi-turn revision in deep research agents: when handling feedback, full-rewrite revision regresses 16–27% of already-covered content on average, with citation quality degrading alongside. More alarming: unguided “please reflect and revise yourself” is ineffective for almost every agent tested — only 1 of 5 improved (+3.6%) — and it causes more collateral damage than targeted feedback. On the mechanism side, Self-Refine (arXiv:2303.17651, retrieval excerpt, not adversarially verified) is consistent: feedback must be specific and actionable, generic feedback measurably hurts, gains concentrate in the first 1–2 rounds, and tasks where errors are hard to self-detect see almost no benefit. The positive contrast is PaperOrchestra (arXiv:2604.05018): its refinement loop carries an explicit “accept only if better, revert and stop if worse” gate and reports a 79–81% win rate with 0% degradation (a body-text detail, not independently verified).

Held against that evidence, our first implementation stepped on all three mines:

Failure mode	Evidence	Corresponding rework
Full-document rewrite	Regresses 16–27% of covered content, citation degradation (2601.13217, manually verified)	Rework 1 + Rework 2
Open-ended prose feedback	Generic feedback measurably hurts; unguided self-reflection nearly useless with more collateral damage	Rework 1: locate to section + actionable step
No accept/revert gate	Only gated refinement achieves 79–81% / 0% degradation (PaperOrchestra, not independently verified)	Rework 3: zero-token regression gate

The three sections below walk through the rework in order of increasing invasiveness. The context is a LaTeX report-generation agent (scan → explore → figures → write → reflect × N → bib → compile self-repair), but the mechanisms are format-agnostic.

Rework 1: reflection outputs a structured edit plan

The first cut lands on the shape of the feedback. The critique is no longer prose; it is forced into a JSON edit plan (prompt translated here — the production prompt is Chinese):

_REFLECT_SYS = (
 "You are a reviewer of lab reports / course notes. Check the current draft "
 "against the source material and identify only problems that genuinely need "
 "fixing, locating each one to a specific section (give its anchor, e.g. n2); "
 "use \"whole\" for cross-section / overall-structure / abstract-and-keywords "
 "issues. Each item carries an issue and an actionable action. Do not mention "
 "what is already fine; no generic polishing. Output strictly JSON: "
 "{\"changes\":[{\"section\":\"n2 or whole\",\"issue\":\"\",\"action\":\"\"}]}; "
 "if the draft is acceptable overall, output {\"changes\":[]} and nothing else."
)

Four design points:

Every issue must be located to a specific section (the anchor assigned by the sectionizer, e.g. n2); cross-section, overall-structure, and abstract/keywords issues are explicitly marked "whole". Location is not decoration — it decides which application path the item takes next.
Issue and action come as a pair. “The error analysis is shallow” alone is not enough; an executable action is required — the direct application of Self-Refine’s “feedback must be specific and actionable”.
The empty array is allowed. {"changes":[]} means “acceptable overall” and terminates the reflection loop early. Revision flips from “change by default” to “no change by default, change only with cause”.
Parse failure never breaks the flow. _parse_reflect_plan returns an empty list for non-JSON or missing changes, which the caller treats as “no changes needed”; plans are capped at 8 items; the title fallback when an anchor misses is “exact match first, then the longest contained title” — so “Results” cannot steal a match meant for “Results and Discussion”.

A companion change: reflection now runs on a fresh minimal context (system + source material + current draft) instead of dragging along the full exploration transcript; the material sits as a stable prefix and hits the cache across rounds.

Rework 2: pure section-level issues go through scoped per-section splicing

Each plan item is routed by its location. Pure section-level issues no longer trigger a full rewrite; they reuse the mature machinery of the interactive editing side (sectionizer, scoped prompts, fragment health check, deterministic splice — the toolkit of Part 07), applied section by section. For each item, _scoped_reflect_apply re-parses and re-resolves the target on the current working text (offsets have moved after the previous splice), sends the model only the target section plus that item’s issue/action plus relevant material, and health-checks the returned fragment (non-empty, balanced braces, balanced environments, no \documentclass). A fragment that fails the check causes that section to be skipped — a bad fragment is never spliced back. A fragment that passes is spliced in, with every other section byte-identical. Only cross-section issues, abstract/keywords issues, or drafts that cannot be sectionized fall back to a whole-document minimal rewrite.

This step has one implementation pitfall, found by an internal adversarial audit (rated [medium]):

# The fragment must preserve the count of top-level \section commands within the
# replaced span (usually =1; =0 for a subsection) — otherwise the splice changes
# the document's section count, the positional anchors of subsequent scoped items
# in the same round drift and edit the wrong section, and the "added sections"
# direction is not caught by regression_check (it only reports decreases).
# Count mismatch → skip this section; never splice a fragment that would shift things.
if len(re.findall(r"\\section\{", new_text)) != len(re.findall(r"\\section\{", section_src)):
 continue

The model occasionally gets “helpful” and splits one section into two: the fragment itself is healthy and passes every check, but after splicing, the document’s section count goes up by one, the positional anchors of all subsequent plan items in the same round drift, and the wrong sections get edited — while the regression gate only reports section decreases, leaving this path with no backstop. The conservation check closes it off before the splice.

Rework 3: the zero-token regression gate

Whether a round went through scoped splicing or the whole-document fallback, its output passes regression_check before landing — six criteria, all deterministic, zero API calls:

loss of the compilable skeleton (\documentclass / \end{document});
length collapse below 60% of the previous version (truncation, or “rest unchanged”-style elision);
structural score decrease;
shrinkage of the \cite key set (with the lost keys reported);
fewer sections;
fewer figures or data tables.

Any trigger means regressed: revert to the previous version and stop reflecting. If the two versions are character-identical after whitespace stripping, the result is converged — also an early stop, so convergence wastes no rounds.

Why not use an LLM judge as the gate? The reason is written in the module’s own comments: this particular failure mode — losing content — is deterministically detectable, whereas the pairwise judge’s reliability in the Chinese domain is unverified (the judge module’s own caveat) and would cost one extra real call per round. More correct, and cheaper. The judge’s proper place is offline evaluation, not an online gate; the validity question is the subject of Part 09.

The gate has its own edge case: in the pipeline, bibliography generation runs after reflection, so during reflection the bib is always empty — which makes the “citations closed” check false for any draft containing \cite, and a newly added citation would be misread as a structural-score drop, wrongly reverting a good edit. The fix: while the bib is empty, that check is excluded from the gate score, and citation loss is judged separately by “the key set must not shrink” — pinned by a dedicated regression test (empty bib produces no false positive).

Gate decisions are surfaced as persisted step events (visible in the log page and across reconnects), with a structured reflect_gate field attached to the trace so the experiment bench can observe whether reflection is actually improving quality and which round reverted.

The reworked loop, end to end

flowchart TD
 A[Current draft vN] --> B[Reviewer on fresh minimal context: JSON edit plan]
 B -->|changes empty| S[Judged acceptable, early stop]
 B -->|pure section-level| C[Scoped per-section edit + splice, other sections byte-identical]
 B -->|contains whole items| D[Whole-document minimal rewrite]
 C --> G{Zero-token regression_check}
 D --> G
 G -->|degraded| X[Revert to vN, stop reflecting]
 G -->|converged| S
 G -->|pass| V[Commit as vN+1, next round]

Tests arrived in batches with the rework: when the gate landed, test_eval_report +7 (accept / revert / converge / lost section / lost citation / length collapse / empty-bib no false positive) and test_run_agent_mock +1 (degraded revision → revert to previous version and stop), with 303 backend tests green; 306 after scoped reflection landed; 322 by the end of this round of work (plus 19 on the experiment bench). Generation quality itself cannot be tested offline — but every deterministic component of the loop can: plan parsing, routing, splicing, the gate.

Lessons from the research process itself

The evidence chain behind this rework deserves its own post-mortem. To benchmark against the state of the art, we ran a 105-agent networked research workflow; the adversarial-verification stage failed wholesale when the subscription session quota was exhausted, leaving all 25 claims stuck at unverified. So we manually re-verified the 3 most load-bearing papers — the ones a retrieval agent would most plausibly fabricate — by reading the arXiv originals. 2601.13217: real, core numbers confirmed. PaperOrchestra: real, but with two corrections — it is not a Google paper, and its abstract describes itself as flexible rather than rigidly fixed, so it can only support “structured multi-agent division of labor beats autonomous loops” (win rate +50–68% / overall quality +14–38%), not “the more rigid the better”. RP-ReAct (arXiv:2512.03560): the architecture is real, but the specific scores in the retrieval claim about “being beaten by vanilla ReAct on simple tasks” do not appear in the abstract — plausibly extracted or confabulated from the body text by the retrieval agent, so they are marked unverified. One more calibration correction: the retrieval claim said “break rate 21–31%”, which is the body-text framing; the abstract says 16–27%, and this article uses the abstract’s figure.

The lesson is isomorphic to the article’s thesis: a retrieval agent’s output needs an accept/revert gate of its own — manual verification is the regression_check of the research workflow.

When not to do this

The gate’s criteria are proxies: they prevent getting worse, they do not certify getting better. Section counts, citation sets, and length all measure structural preservation; content that is wrong but structurally intact passes the gate. Preference-level quality still requires offline evaluation and judges — this gate does not replace them.
Scoped reflection presupposes sectionizable structure. A draft that cannot be parsed goes straight down the whole-document fallback — that fallback is not a defect, it is an acknowledgment of the boundary.
When the structure itself is wrong, scoped editing is powerless. Problems requiring global reorganization (moving sections, merging sections, changing the narrative line) must be marked whole and take the full rewrite; forcing them through per-section edits produces drafts that are locally fluent and globally incoherent.
Do not bolt this gate onto loops that already have an external signal. The compile self-repair loop has the compiler as its referee and stops on no-progress error fingerprints — a different kind of closed loop, and already the right design; adding a structural gate to it is redundant construction.
Keep N small. Self-Refine reports gains concentrated in the first 1–2 rounds (not adversarially verified), and 2601.13217 shows the break rate is the bottleneck of multi-turn revision — budget spent on a fifth reflection round is most likely paying for a revert.

This article pairs with Part 11, “The deterministic boundary”: that article promotes the gate and the scoped machinery into a unified architectural principle; this one is the complete rework record of that principle applied to a single closed loop — the reflection loop.

References

Beyond Single-shot Writing: Deep Research Agents are Unreliable at Multi-turn Report Revision (arXiv:2601.13217) — full-rewrite revision regresses 16–27% of covered content on average with citation degradation; unguided self-reflection is nearly useless and causes more collateral damage; its named remedies: structured edit plans and a dedicated Reviser. Verified against the original.
PaperOrchestra: A Multi-Agent Framework for Automated AI Research Paper Writing (arXiv:2604.05018) — structured multi-agent pipelines beat autonomous baselines by +50–68% / +14–38% (verified); its accept-or-revert refinement gate reports a 79–81% win rate with 0% degradation (body-text detail, not independently verified).
Self-Refine: Iterative Refinement with Self-Feedback (arXiv:2303.17651) — feedback must be specific and actionable, generic feedback measurably hurts; gains concentrate in the first 1–2 rounds; tasks where errors are hard to self-detect need external signals. Retrieval excerpt, not adversarially verified.
Reason-Plan-ReAct (arXiv:2512.03560) — plan/execute decoupled architecture (verified); the specific scores for “beaten by vanilla ReAct on simple tasks” are absent from the abstract and unverified.

From chat to agent: tool loops and collapse breakers

Wed, 29 Jul 2026 00:00:00 +0000

Also in 中文. Part 4 of the Engineering LLM Applications series. The series is grounded in the implementation and measurements of a production-grade AI writing agent (FastAPI + React + Tauri, 351 test cases).

The problem: handing the loop to the model

The first three articles of this series were about single-call engineering: controlling input, assembling prompts, sanitizing output. The watershed of an agent is that what to do next is also handed to the model: give it a tool set, execute its calls, feed the results back into the message list, and call again — until the task is done.

The concrete scenario for this article: give the agent a data folder whose file names and contents are unknown in advance, and have it read files on its own, figure out what experiment this is, and write the report. The naive implementation is a while True tool loop, and in production it fails in three ways:

Untrusted paths. The model decides which file to read; a single ../ in an argument reads outside the data directory.
No natural endpoint. “How much exploration is enough” is the model’s judgment call; there is no upper bound on iterations, and therefore none on cost.
Loop collapse. The most insidious class: in long contexts, the model degenerates into calling the same tool with identical arguments. A public case, qwen-code issue #4695, records 43 consecutive git status calls consuming 8.9M tokens in one session; the deepseek-v4-pro tier we use is also prone to collapsing into this pattern in long contexts. SDK retries cannot help — retries only cover network errors and rate limits, while each of these calls “succeeds” at the API layer. The breaker has to live on the client side.

The rest of this article walks through five mechanisms in build order. The implementation uses standard OpenAI-compatible tool calling (DeepSeek by default; any compatible endpoint can be swapped in); the entry point run_agent is a generator that yields events one by one for SSE streaming.

Mechanism 1: a minimal tool set with a path guard

The exploration phase has five tools: list_dir, read_file, read_image (a local vision model extracts readings from screenshots and figures), make_figure (executes model-written matplotlib code to produce plots), and finish_exploration. Three design points:

Segmented continuation instead of stuffing everything in at once. read_file clips text at READ_CHARS = 7000 characters and, when it clips, appends one line: “truncated — use offset/limit to continue reading by lines”. Truncation is not an error; it is a decision point for the model: there is more, and whether it is worth reading further is the model’s trade-off to make. It also imposes a constraint on the loop-breaker fingerprint later — continuation reads with different offsets are legitimate behavior and must not be flagged.

Explicit phase transition. finish_exploration turns “exploration is done” from an implicit signal (the model simply stops calling tools) into an explicit call: the schema requires experiment / goal / key_findings, with three optional slots for assignment requirements, methodology notes, and a reference report. The phase transition leaves a structured record — and gives the breaker a well-defined exit to steer toward.

Every path entry goes through _safe.

def _safe(rel, root=None):
 root = root or base_docs_root()
 if not root:
 return None, None
 t = os.path.normpath(os.path.join(root, rel or ""))
 if not (t == root or t.startswith(root + os.sep)):
 return None, None
 return root, t

After normpath joining, the resolved path must still be inside the root; an escape returns (None, None), and the tool layer turns that into a “path does not exist or is out of bounds” string returned as the tool result — the model sees it and can correct itself, and the main flow never raises. The make_figure tool description also spells out hard sandbox rules (no importing os/sys/subprocess and the like, no open()/eval/exec, no double-underscore attributes); its two-layer sandbox implementation is the subject of the next article.

Mechanism 2: a zero-LLM scan before exploration starts

Before the model begins exploring, scan_folder performs a deterministic recursive scan: files are coarsely bucketed by extension into documents / images / data / other, returning the bucketed listing and counts — zero LLM calls, zero tokens. It serves two purposes: an instant whole-folder snapshot for the user (the detail of the first step event), and deterministic input for the later material-gap check. The principle is the same as in Part 11: “what is in the folder” is a question code can answer, and the model’s exploration budget should be spent on “which files to read and what to make of them”. One cost note in passing: the exploration tool loop runs on the cheap model tier (reading files and deciding what to read is simple work); drafting and reflection use the main model.

Mechanism 3: two lines of defense — a budget cap and a collapse breaker

MAX_TOOL_ITERS = 20 is a budget cap, not a defense: a collapsed agent will burn all 20 iterations on repeated calls and produce nothing. The real defense is _LoopBreaker, built around a call fingerprint:

def _tool_fingerprint(name, args):
 """Tool-call fingerprint = name + full arguments (sorted JSON)."""
 try:
 return name + "|" + json.dumps(args, ensure_ascii=False, sort_keys=True)
 except Exception:
 return name + "|" + str(args)

Three design constraints: full arguments — offset=0 and offset=100 are two different fingerprints, so legitimate segmented reads are never flagged (a unit test pins this property); sorted serialization — argument key order does not affect the verdict; never raises — serialization failure falls back to str(). Wrap-up tools like finish_exploration are excluded from counting.

The thresholds come in two tiers. Third occurrence of the same fingerprint (_LOOP_WARN): inject one wrap-up prompt — “You are repeatedly calling the same tool with the same arguments. What you have read is sufficient; call finish_exploration immediately and state your conclusions” — with nudge_once guaranteeing a single injection per run, because the injection itself occupies context and repeated injections would accelerate the collapse. Fifth occurrence (_LOOP_STOP): hard-break out of the exploration loop. The break is not a crash: the agent yields a “repeated identical tool call detected — exploration cut off, writing from what has been read” event and proceeds to the drafting phase with the material accumulated so far. A degraded deliverable plus a human reviewer beats zero output after the budget is exhausted.

flowchart TD
 A[Call model with TOOLS] --> B{tool_calls returned?}
 B -->|none| N[Inject: keep exploring or call finish_exploration] --> A
 B -->|finish_exploration| W[Record understanding, enter drafting]
 B -->|other tools| F{LoopBreaker fingerprint count}
 F -->|ok| E[Execute tool, feed result back] --> A
 F -->|3rd time, once only| G[Execute tool, inject wrap-up prompt] --> A
 F -->|5th time| X[Hard break after this round] --> W

The whole loop still sits inside for _ in range(MAX_TOOL_ITERS) — the two defenses hold independently. The breaker has an end-to-end test: a mock client that, whenever tools are passed, always returns the same read_file(a.txt) call (simulating total collapse); the test asserts that the break event must appear and that the number of create calls is ≤ 6 — far below the cap of 20. The threshold sequence (first two ok, third nudge, fifth stop) and the fingerprint properties are pinned by separate unit tests.

Mechanism 4: the inverse failure in drafting — tool markup without tools

After exploration, drafting begins, and this phase passes no tools. But the model may still emit its internal tool-call markup (DeepSeek’s DSML) as body text — the generation “succeeds” on the surface, and the resulting report is garbage. _complete_report validates output with three deterministic criteria: contains \documentclass, contains no DSML, contains no tool_calls. On failure it injects a reinforcement instruction (“You have no tools available right now… output the complete LaTeX source directly”) and retries, up to 3 times. This is the output-sanitizing approach of Part 3 extended into the agent context: a structurally invalid output is not patched textually — the constraints are tightened and the call is retried.

Mechanism 5: deterministic progress — pre-enumerated milestones and explicit stages

A streaming agent’s progress bar cannot run on guesswork. This pipeline is “process as configuration”: scan → explore → [figures] → [gap] → draft → reflect×N → bib → [compile], with the optional steps switched by the template. So _plan_pipeline enumerates the milestone sequence before the run starts, from configuration alone; M = len(plan), every milestone event carries index/total, and the progress bar has a fixed denominator from the first second. Two consistency details:

The gates for optional steps must match the runtime decisions verbatim: has_xelatex is probed exactly once, and the plan and the runtime compile gate reuse the same result, so the two can never diverge;
the stage name is passed explicitly rather than looked up from _plan[_pi-1]: the reflection loop may break early on convergence, and a skipped milestone would make the positional lookup mislabel the subsequent bib / compile milestones as reflect.

One known small deviation is documented honestly in the code comments: the gap step also depends at runtime on whether material exists and may actually be skipped — the plan counts it anyway, and the completion event backfills to 100%.

Measurements

Real-run validation (devlog record, DeepSeek v4-pro, an electromagnetics field-scan dataset): the agent ran list_dir automatically and made multiple rounds of read_file (a PDF, band.csv, scan parameter files, and more), and its autonomous identification of the experiment was correct; the draft was 16,773 characters, and after one reflection-revision round the final report was 20,742 characters across 9 sections, with the full run taking 745 seconds. That validation ran on the initial version whose tool set was only list_dir / read_file / finish_exploration; read_image and make_figure were added later.

Mechanism	Alternative	Effect
`_safe` path guard	Trust model-supplied paths	Escapes become tool-level errors the model can self-correct; nothing raises
`scan_folder` pre-scan	Let the model map the folder itself	Zero-token bucketed snapshot of every file
`MAX_TOOL_ITERS = 20`	Unbounded loop	Hard cost ceiling
`_LoopBreaker`	Iteration cap / SDK retries alone	≤ 6 create calls in the collapse scenario (end-to-end assertion), saving 14+ wasted rounds
DSML detection and retry	Accept the “successful” output	Valid LaTeX within at most 3 retries
`_plan_pipeline` + explicit stage	Guess progress from event counts	Denominator known before the run; early convergence never mislabels stages

Where not to do this

An exact fingerprint catches total collapse, not wandering. Low-value calls to the same tool with varying arguments (reading irrelevant files one after another) never trip the breaker; that class is bounded by the budget cap and prompt quality. Fuzzing the fingerprint (ignoring some arguments) would widen coverage but misfire on legitimate continuation reads — we chose narrow and precise.
The nudge works only while the model still follows instructions. The wrap-up prompt helps with mild circling; once the context has collapsed severely, the model no longer responds to injections and only the hard break matters — which is exactly the rationale for the two-tier thresholds.
A degraded deliverable requires a human in the loop. A report written from partial material is only worth something if someone reviews it downstream. If the agent’s output is executed automatically and partial information can cause harm, the breaker policy should be fail-the-whole-run rather than degrade.
Pre-enumerated progress requires a fixed pipeline. _plan_pipeline works because the pipeline structure is settled before the run starts; an open-ended agent whose plan is generated dynamically by the model has no a-priori milestone sequence, and progress degrades to event counting.
The thresholds are not universal constants. 20 / 3 / 5 were tuned to the scale of “read a folder, write a report” and have not been validated on other task shapes.

References

qwen-code issue #4695 — a public case of tool-loop collapse (43 repeated git status calls / 8.9M tokens in one session).

Multi-agent adversarial review as an engineering practice

Wed, 29 Jul 2026 00:00:00 +0000

Also in 中文. Part 13 of the Engineering LLM Applications series.

The problem: the typical failure of an LLM finding is that it looks real

When you use an LLM to review code, volume is never the bottleneck — it will happily list fifty “potential issues” against any codebase. The bottleneck is at the other end: the typical failure mode of an LLM finding is plausible-but-wrong. The line number is specific, the failure narrative is complete, the suggested fix is fully formed — and then it falls apart the moment you confront it with the code: the guard already exists, the alleged race path is unreachable, the “leaked” resource is reclaimed somewhere else.

A review pipeline without a verification stage drowns in fake findings, and fake findings cost you both ways: either you falsify each one by hand, paying back every hour the review saved, or you start ignoring the report wholesale — and the real problems die with the fake ones. The second outcome is the more common and the more fatal: a report that mixes true and false findings carries close to zero engineering information.

A separate, independent problem is breadth: a single-perspective review — whether a human or a single agent — cannot stay simultaneously alert across security, concurrency, billing, and cross-platform consistency.

Both problems point at the same structural remedy: split “find problems” and “verify problems” into two stages with opposite objectives — the finding side optimizes for coverage, the verifying side optimizes for truth. This article walks through the structure, grounded in two production runs (one full-project audit, one session-level review) plus one set of overturn data.

The structure: parallel discovery by dimension, adversarial verification per finding

Stage one: N auditors in parallel, each guarding exactly one dimension. The full-project audit used 6 (backend core, API-DB-security, LaTeX-verify-distill, frontend, test blind spots, documentation drift); the session-level review used 4 (concurrency/runs, security, frontend regression, data integrity). The point of slicing by dimension is not parallel speed-up but forced perspective: an auditor that only looks at concurrency does not have its attention taxed by functional correctness.

Findings obey a format discipline: every one must land as file:line + a concrete failure scenario + a proposed fix. This is the precondition for everything downstream — it turns a finding from “something feels off” into a falsifiable claim.

Stage two: each finding goes to an independent verifier. The verifier is not the agent that produced the finding and does not enter with that agent’s reasoning in context; its instructions are default skepticism, specialize in falsification — go into the code and look for evidence that the finding does not hold. The verdict is three-valued: CONFIRMED / uncertain / dismissed, and only CONFIRMED enters the repair queue.

Independence is a requirement, not an option. When one agent checks its own work, its finding is sunk cost sitting in its context, and it will defend it; only when “successfully overturning the finding” is the verifier’s success criterion do the incentives align. This is the same issue as judge validity from part 9 of this series, seen from the other side: the verifier is itself a judge, and its validity has to be demonstrated by the fact that it actually overturns things — data below.

flowchart TD
 A[Codebase / change set] --> B1[Auditor: security]
 A --> B2[Auditor: concurrency]
 A --> B3[Auditor: ... N dimensions total]
 B1 --> F[Finding: file:line + failure scenario + fix]
 B2 --> F
 B3 --> F
 F --> V{Independent verifier: default skepticism, falsify}
 V -->|CONFIRMED| T[Triage by severity]
 V -->|dismissed| X[Discard]
 V -->|uncertain| U[File as open question]
 T --> R[Fix, or defer explicitly with a recorded reason]
 R --> P[Regression tests confirm no breakage]

Two measured runs

	Full-project audit	Session-level review
Scope	Entire codebase (backend + frontend + docs + tests), focused on the broader/older parts	One session’s changes: 44 files / 1,467 lines, including a core-path refactor
Auditors	6, by subsystem/dimension	4, by risk dimension
CONFIRMED	27 (5 high / 14 medium / 8 low)	7
uncertain / dismissed	0 / 2	all others falsified
Disposition	24 fixed, 3 explicitly deferred	7 fixed
Post-fix verification	pytest 243 passed (+6 new tests), vite build clean	pytest 18 passed + targeted live tests

Beyond the counts, what deserves attention is the type of problem on the confirmed list — a substantial share is the kind a single person reading the diff end-to-end would very likely miss:

TOCTOU race in the 409 concurrency guard (session-level): “check whether a run is already running” and “create the run” were not atomic, so concurrent requests could double-start. The fix moved the check, the creation, and the handle registration together inside runs._LOCK; the repair was closed out empirically — two concurrent requests return [200, 409].
Chat billing used the unresolved provider (session-level): with DEFAULT_PROVIDER=anthropic and the request omitting the provider field, cost was computed at deepseek’s unit prices — roughly a 60× underestimate. Provider resolution lives in one place, pricing in another; reviewed module by module, both sides “look correct”.
Anthropic streaming max_tokens=32000 while DeepSeek’s was 64000 (full audit, medium): long reports silently truncated on one provider; only a cross-provider consistency comparison exposes it. Fixed by unifying on _STREAM_MAX_TOKENS=64000.
Figure sandbox environment hardcoded POSIX (full audit, high): on the Windows distribution (the primary platform), the CPython subprocess cannot start for lack of SystemRoot/TEMP, so make_figure crashes unconditionally.
EXPOSE_RESET_TOKEN defaulting to true (full audit, high): any anonymous caller could obtain a reset token and change a password — account takeover; changed to a secure default of false.

These respectively require concurrency-interleaving reasoning, cross-module dataflow tracing, cross-provider comparison, and cross-platform runtime knowledge — exactly the categories that one dedicated perspective per dimension covers and one sequential read-through misses.

One disposition detail worth copying: the 3 deferrals are not silent omissions but explicit decisions with recorded reasons — all are SaaS-only issues neutralized in the shipped STANDALONE configuration by _no_cloud/forced-local, and fixing them outright would have meant disturbing a set of non-STANDALONE test semantics; they are filed for whenever SaaS is revived. The output of a review is not just fixes; it is also this traceable record of why not.

Verification is not a rubber stamp: overturn data

Whether the adversarial verification stage actually works needs evidence of its own. The same find-then-adversarially-recheck structure was applied to a different kind of object: auditing whether the writing rules produced by the distillation experiment (part 12 of this series) genuinely learned “judgment” rather than reskinning structural templates. Eleven agents in total: for each rule pair, an item-by-item initial classification, followed by an adversarial re-review whose instructions were, again, default skepticism — specializing in items whose “because” is a tautology or whose structural action carries only a thin veneer of justification.

Pair	Initial judgment share	After adversarial re-review	Pair verdict
1	87%	80%	holds
2	82%	73%	holds
3	73%	67%	holds
4	82%	64%	holds
5	100%	90%	holds

The initial numbers of all five pairs were revised downward; the post-adversarial mean is 0.746, and the overturned items follow one highly consistent pattern — the action overlaps a structural template and the stated reason is close to a tautology. The pair-level verdicts held 5/5, but no pair emerged untouched. The original report also flags, unprompted, that pair 5’s 0.9 is optimistic (the initial 1.0 was itself suspicious).

This data establishes two things. First, the verifier really does overturn items case by case — it is not process decoration. Second, the value of the adversarial stance runs in both directions: in code review it kills false positives (2 dismissed; “all others falsified” at the session level), and in evaluation tasks it deflates optimistic self-assessment (100% → 90%).

Cost and applicability

The cost structure is straightforward: every finding pays for one additional dedicated verification pass, plus orchestration overhead. When it is worth it:

Large change surfaces. The session-level run covered 44 files / 1,467 lines including a core-path refactor (“merging chat into run”) — a surface beyond what one person can hold in a single pass.
Pre-release / security surfaces. Problems like EXPOSE_RESET_TOKEN or the Stripe webhook skipping validation when no secret is configured (fixed to fail closed: 503 without a secret) have a miss cost wildly out of proportion to the verification cost.
Legacy code never systematically audited. The full-project audit’s stated goal was precisely “not just the new code — focus on the broader/older parts”, code outside the field of view of any recent review.

When it is not worth it, the source record already contains the judgment: single-feature implementation is “sequential and interleaved, with no fan-out” — solo work suffices; review and audit (breadth plus independent verification) are what the multi-agent workflow is actually good at. Extrapolating to small changes: on a few dozen lines of diff, falsifying three findings by hand is far faster than orchestrating a six-auditor pipeline, and the verification overhead simply exceeds the benefit.

Limits

The shared-origin blind spot. The verifier and the author of the code under audit are the same (or a sibling) LLM. The adversarial structure removes positional bias — no one defends their own output anymore — but it does not extend the capability boundary: a category of problem invisible to both sides stays invisible to the verification stage too. It is no substitute for signals of a different origin — actually running the code, live concurrency tests, human domain knowledge.
“0 uncertain” does not mean “0 escaped”. 27 CONFIRMED with 0 uncertain measures the precision side: nearly everything raised was real. It says nothing about the recall side — the problems no auditor raised at all. This very audit confirmed three test blind spots: an audit can find the holes in the tests, but there is no instrument measuring the holes in the audit.
Verification depth is itself sampled. The overturn experiment’s report states honestly that only pair 4’s source file was empirically spot-checked; the rest relies on sub-agent labeling. Verification can be shallow, and a CONFIRMED stamped by shallow verification deserves a discount — mistaking “verification happened” for “verification was thorough” is this pipeline’s most seductive self-deception.
The structure depends on finding discipline. file:line + failure scenario + fix is what makes a finding a falsifiable claim; relax it to “module X may have issues” and the verifier has nothing to confront — the whole pipeline degenerates into two rounds of opinion exchange.

Wiring external signals into the loop: compile-and-repair

Wed, 29 Jul 2026 00:00:00 +0000

Also in 中文. Part 6 of the Engineering LLM Applications series.

The problem: models cannot fix errors they cannot see

Scenario: an autonomous agent generates a LaTeX lab report, and xelatex fails. Who fixes it?

The reflex is to ask the model to “check it again.” The evidence against that path is specific. One of Self-Refine’s conclusions (arXiv:2303.17651) is that on tasks where errors are hard to self-detect, pure self-reflection is nearly useless, and gains only return once an external verification signal is wired in. The systematic review in When Can LLMs Actually Correct Their Own Mistakes (TACL 2024) is blunter: prompting-only self-critique does not improve — and can degrade — arithmetic and code tasks, and the flattering self-correction numbers in the literature mostly leaned on an oracle (stopping only when the known-correct answer appears). Compile errors are the canonical hard-to-self-detect case: the model rereads the \def line it just wrote and cannot see that a % inside the braces comments out the closing brace — but xelatex sees it, and its error report cannot be faked.

So the right question is not “how do we make the model self-check” but “how do we wire an objective external verifier into the generation loop.” This article dissects the compile-and-repair loop we shipped in an AI writing agent — really compile after generation; on failure, extract the errors and feed them back for a repair round — and the engineering constraints that keep this deceptively simple loop under control in production.

From patching to really compiling

Before the compiler was wired in, the system already had a deterministic sanitizer layer (part 3 of this series): \mathbf→\symbf, % comments inside \def lines, backfilling template variables the model forgot to set — the known pitfalls that rules can encode. But patches cannot enumerate the long tail. The devlog states the goal of this step plainly: “not patching with the sanitizer, but having the agent really compile after generating the report, feed the xelatex errors back for a round of its own fixes on failure, and push the first-pass success rate to the max.”

That fixed the division of labor: rules handle the known pitfalls (zero tokens); the compiler backstops the long tail (one LLM call per round). In practice the sanitizer has already cured the common traps, so the first compile check usually passes outright; the repair branch only catches what remains. The loop itself is three steps:

compile_tex — assemble a complete working directory (article.tex + cls + bib + figures), run xelatex → bibtex → xelatex ×2, return {ok, pdf_path, log};
extract_errors — pull from the log the lines starting with !, the l. line-number lines, and Runaway / Emergency stop lines, capped at 1800 characters — never feed back the whole log;
on failure, feed the error excerpt back to the model, demand the full revised source, at most 2 rounds.

The cap of 2 is not arbitrary: a survey finding (How Many Tries, arXiv:2604.10508) across 7 models is that the first two rounds capture 76–95% of the achievable gain, with near-zero return from round three on; Self-Refine likewise plateaus by round 3. Extra rounds only multiply wall-clock and token spend. One further detail: the second round’s repair output is not re-verified inside the loop — the repaired draft is kept, and final verification is left to the user-side manual compile/export path.

A counter-intuitive design point: the repair is a full-document rewrite, not a scoped patch of the kind used in part 7. The reason is a property of LaTeX errors — they are often decoupled from the root cause, and line numbers are unreliable (LaTeX Compilation Challenges, arXiv:2603.02873), so pinpoint fixes at the reported line easily patch the wrong place. Scoped editing presupposes deterministic targeting, and compile errors are precisely where that presupposition fails.

Termination: fingerprint, round cap, wall clock

The biggest production risk of a self-repair loop is not failing to fix — it is failing to stop. The consensus on loop governance is that “when to stop” must not be left to the model’s discretion; an outer controller enforces it with deterministic criteria. There are three gates:

The no-progress gate. After each failed round, fingerprint the errors — the first 120 characters of the first ! error line (LaTeX’s anchor line); if it equals the previous round’s fingerprint, declare no progress, stop immediately, keep the current draft:

def _error_fingerprint(errs: str) -> str:
 """Compile-error fingerprint: first '! …' error line (LaTeX's anchor),
 else the first 120 chars. Used for no-progress detection."""
 for line in (errs or "").splitlines():
 s = line.strip()
 if s.startswith("!"):
 return s[:120]
 return (errs or "").strip()[:120]

If the same error survived a repair round, this model has no answer for this error; feeding it the same report again will most likely produce the same failure, and burning more tokens has no expected return.

The round cap. for attempt in range(2) — a hard limit.

The wall-clock gate. A single compile runs up to 4 subprocess passes at 180 seconds each — a token budget cannot contain CPU time. COMPILE_WALL_BUDGET (default 600 seconds) is checked before each round; on expiry, stop and keep the current draft. The config comment states the motive: prevent multi-round self-repair from hogging the customer machine’s CPU.

All three gates are deterministic criteria executed on the Python side; the model has no say in whether the loop stops — the same stance as the tool-loop circuit breaker in part 4.

Minimal repair context: ~8k tokens, not 40–60k

How the repair call’s context is constructed is the single most money-saving decision in this loop. The intuitive approach is to reuse the agent’s full exploration history — surely the model “fixes better knowing more”? The opposite holds. The judgment recorded in the code comment: 95% of compile errors are template-level syntax problems (balancing, command misuse, template variables), and fixing them requires exactly three things:

the full current draft;
the error excerpt (≤1800 characters);
the formatting hard rules (no % comments inside \def braces; bold vectors with \symbf; no bold inside accents; balance braces/environments/$; end with a top-level \end{document}).

About 8k tokens in total. Reusing the full exploration messages would carry 40–60k tokens of dead weight — source material, tool-call records, multiple draft versions — none of it contributing to fixing one brace; switching to a fresh minimal context saves 30–50k tokens per repair round. The system prompt narrows the mandate to a single sentence:

You are a LaTeX compile-repair assistant: fix compile errors only — do not rewrite content, do not add or remove sections, do not touch data.

This is not only about cost: the measurements in Revisit Self-Debugging (arXiv:2501.12793) show label-only feedback beating verbose detailed feedback — inaccurate long context introduces ambiguity and lowers scores. Commercial products are isomorphic: Overleaf’s commercial Error Assist also deliberately minimizes the repair context, sending only the full error, the relevant code lines, and a file-name list (product-page information, not independently verified).

Concurrency isolation: a compile directory per session

A plain constraint you only learn by tripping on it: the compile working directory must be isolated per session. compile_tex writes article.tex into the directory, copies the cls and figures, and rmtree-rebuilds the figure subdirectory during assembly — two concurrent generation runs sharing one directory will overwrite each other’s source, delete each other’s figures, and pollute each other’s logs. After partitioning the repair directory as _repair/<session_id>, each run writes its own. The lesson generalizes: a verifier is a side-effecting process, not a pure function — when wiring an external verifier into a loop, isolation is a default, not an optimization.

The whole picture, quantified

flowchart TD
 A[Final draft] --> W{Wall-clock budget exceeded?}
 W -->|yes| S[Stop, keep current draft]
 W -->|no| C[compile_tex: real compile]
 C -->|ok| P[PDF produced]
 C -->|fail| E[extract_errors: pull ! error lines]
 E --> F{Fingerprint same as last round?}
 F -->|same = no progress| S
 F -->|different| R[Minimal-context repair call ≈8k tokens]
 R --> N[2 rounds used?]
 N -->|yes| S
 N -->|no| W

Constraint	Failure mode without it	Implementation and numbers
Round cap	Grinding on for rounds with near-zero return from round 3	K=2; first two rounds capture 76–95% of achievable gain (survey figure)
No-progress gate	The same error fed back again and again, spinning in place	Fingerprint = first 120 chars of the first `!` line; stop on consecutive match
Wall-clock gate	4 passes × 180s per compile; a token cap cannot contain CPU	`COMPILE_WALL_BUDGET`, default 600s; on expiry keep the current draft
Minimal context	40–60k tokens of exploration-history dead weight per call	Current draft + error excerpt + hard rules ≈8k; saves 30–50k tokens per round
Session isolation	Concurrent runs clobber each other’s source/figures/logs	Dedicated `_repair/<session_id>` working directory

Where not to build this loop

It presupposes a cheap, objective, unfakeable verifier. Compilers, type checkers, and unit tests qualify; “is the writing good” does not. The stop condition must anchor on an objective signal like “compilation succeeded” — never on the model’s self-assessment. Quality dimensions without a verifier belong to evaluation and judges (parts 8 and 9), not to this loop.
Deterministic repair comes first. Pitfalls that can be written as rules (known syntax traps, missing-figure placeholders, variable backfill) should be cured by the zero-token sanitizer before any LLM repair; the repair loop only backstops the long tail that rules cannot enumerate. Reversing the order means using a probabilistic component for deterministic work: paying a call every time while adding new uncertainty.
Weak models need a non-LLM exit. Survey data puts weak models’ repair rate on deadlocked errors at only about 30% (not independently verified). The loop must ship with a fallback that does not depend on the model — here, export_zip produces a compilable package to hand to Overleaf or a human. Without an exit, the loop degenerates on weak models into “burn the budget, then give up.”
When the verifier is expensive, the budget gate precedes the round cap. Here a single compile is wall-clock-bounded at 4 passes × 180 seconds (at most 720s), so K=2 is affordable; if the verifier is a ten-minute integration test suite, the same K=2 may be unacceptable — the wall-clock budget must become the first gate, including the option of “give up without repairing at all.”

References

Self-Refine: Iterative Refinement with Self-Feedback (arXiv:2303.17651) — self-reflection is nearly useless on tasks where errors are hard to self-detect; gains return with external signals; benefit concentrates in the first 1–2 rounds (its “+20% average” figure not independently verified).
When Can LLMs Actually Correct Their Own Mistakes (TACL 2024) — prompting-only self-critique does not improve, and can degrade, arithmetic/code tasks; flattering self-correction results mostly relied on an oracle.
How Many Tries (arXiv:2604.10508) — the first two rounds capture 76–95% of achievable gain; near zero from round 3.
LaTeX Compilation Challenges (arXiv:2603.02873) — LaTeX errors are often decoupled from root causes; line numbers are unreliable.
Revisit Self-Debugging (arXiv:2501.12793) — label-only feedback beats verbose feedback.
Overleaf Error Assist — the commercial isomorph of minimal repair context (product-page information, not independently verified).