[!TIP] Audience: people curious whether “human writes the spec, model executes” actually holds up, and anyone who writes technical specs. Core goal: use one real handoff, recorded end to end, to show what kinds of things a spec must pin down — and how to handle an executor correcting the spec with evidence. Problem-to-solution map:

  • One dataset crossing the network twice → recon showed the root cause was topology; one bind mount makes it local IO
  • Specs must not be ambiguous → measured facts separated from assumptions, security constraints fixed
  • Specs can be wrong → the executor found it, corrected it with evidence, and recorded it

Just what actually happened this time: no slogans, no grand “future of AI division of labor” conclusions. Judge from the record where this arrangement holds.

1. It Started With Something Mundane

My home download box writes files to an SSD; the archive target is a 14T mechanical disk on another machine. The old flow was pull from SMB to my Windows machine, then push back over SMB — one dataset crossing the physical network twice, slow and roundabout.

2. Recon First: The Root Cause Was Topology, Not the Tool

Before touching anything, I surveyed. The root cause wasn’t the tool at all:

  • The archive disk was already mounted on the host and bind-mounted into three containers, but the download box’s container was the one left out — so it could only go over the network.
  • The container serving SMB had a cgroup IO limit (80 MB/s hard cap), and every byte flowing through it to the archive disk hit that ceiling.
  • The two containers sat on bridges attached to two different physical NICs, with no interconnect between the bridges — container-to-container traffic had to leave the physical port, loop through the gateway, and come back.

Conclusion: add one bind mount, and the move turns from “two network trips” into pure local IO. Expected gain: moving 100 GB drops from roughly 25–30 minutes to about 7.

3. What the Spec Contained

Here’s what kinds of things must be pinned down in a spec, each with a real example from this job:

First, measured facts and unverified assumptions tagged separately — with an explicit instruction that measured items must not be re-derived, nor silently “corrected” just because they disagree with common sense or the docs. The measured numbers pinned this time include: archive disk sequential write 233 MB/s, sequential read 254 MB/s (dd O_DIRECT, 1GiB); filesystem is exfat with a 4 MiB cluster (read from the boot sector, not guessed); an unprivileged container can write exfat, no idmap needed, no hard links, same-disk rename is atomic; rsync --preallocate is unsupported on exfat and must be disabled (Operation not supported); exfat timestamp precision is 10 ms, so incremental detection is reliable and won’t re-transfer.

Second, hard design requirements derived from measured facts. The real waste from 4 MiB clusters: the photo directory shows 840G allocated for 600G real size, 77400 files, 240 GB wasted. So the spec directly required: a cluster-aligned space precheck (Σ ceil(size / 4MiB) * 4MiB), and the UI must show both “real size” and “allocated size” — otherwise “a thousand small files totaling 10MB” will bite you on a disk with only 1.8T left.

Third, security constraints fixed with no room for the executor to improvise: path whitelist (realpath first, then prefix check, against traversal and symlink escape), subprocess always gets an argument list, never shell=True, source deletion requires all four steps green plus an explicit user checkbox, and refusal to overwrite an existing destination.

Fourth, an explicit “not doing this” list with reasons: no changes to the downloader config, no hooks or scheduled scanning (I explicitly wanted everything manual), no third-party Python dependencies, no touching the 80 MB/s limit, no filesystem migration.

Fifth, the acceptance list written as directly executable commands and criteria, not “confirm it works”.

4. What Execution Produced

Deliverables: the download box got its mount point; a single-file mover service (pure standard library + system rsync) plus a systemd unit, SQLite queue, and embedded frontend. State machine PRECHECK → COPYING → VERIFYING → COMMITTING → [DELETING_SRC] → DONE, writing into a same-disk staging directory first, then an atomic rename into place once verified.

Acceptance all actually ran:

  • Copy rate 287–321 MB/s, above the 233 MB/s baseline.
  • Space precheck: a 2TB sparse file was rejected from the queue, reporting the cluster-aligned requirement.
  • Bloat display: a directory of 200 small files showed 57 KB real / 800 MiB allocated.
  • Interrupt recovery: restart the service 8 seconds into a copy → the task marked FAILED, staging preserved, source not deleted; resubmit resumed and finished in 46.8s (full run is 54.8s), byte-level verification confirming the resume.
  • Security: ../../etc, /etc, symlinks, and using staging as the destination were all rejected.

5. Three Measured Deviations

The executor didn’t copy the spec blindly; it found in the real environment that the spec was wrong, corrected it with evidence, and recorded it:

  1. The spec said --partial-dir=.rsync-partial. Measured on rsync 3.2.3: --append and --partial-dir are mutually exclusive, and --partial-dir only stores the partial — re-running does not resume (sent bytes = full transfer). Switching to --partial --append-verify, re-running a 2 GiB file after 1 GiB was transferred dropped sent to 1.07 GiB with speedup 2.0 — a real resume.
  2. The spec wanted “allocated size” shown in both the source and destination columns. Measured: recursively counting that 77k-file directory takes ~8s, stalling the whole destination listing 15s+. Changed to recursion only on the source side, a shallow list on the destination side, and the authoritative “real vs allocated” comparison lives in the pre-submit confirmation dialog.
  3. rsync trailing-slash semantics: passing staging/<base> directly produced the double nest staging/<base>/<base>.

There’s also one honestly-recorded isolated anomaly: a 20 GiB job’s progress bar once stopped at the 3rd progress line while the log had all 80 lines; re-running the same code and file was normal, not reproduced, no known root cause, logged and under observation. I insisted on including this — writing “I don’t know why” into a delivery report is more credible than an all-green one.

6. What Has to Be Mine

No “AI does everything” fantasies — a factual split:

  • Can be handed off: writing code within given constraints, deploying, accepting item by item against a checklist, measuring numbers in the real environment, and correcting the spec with evidence when reality disagrees. All of that held up this time.
  • Cannot be handed off: judging problem framing like “the root cause is topology, not the tool”; deciding what not to do (refusing automation, refusing to touch the limit, refusing to migrate the filesystem are all trade-offs with costs); pinning down security boundaries; and deciding what counts as “measured”.

Summary

One plain conclusion: the division of labor holds not because the model is powerful, but because the spec spelled out, item by item, which things are facts, which are assumptions, and which must not be changed.