Before an Agent Clones Your Template Repo, Hand It a Trap Index: One Line per Fix, the Reasons Kept in One Place
When you copy a running site to start the next one, an agent carries the fixes over but leaves the reasons behind. A symptom-first trap index, a one-page porting plan written before the copy, and three small scripts that catch drift between the index, the source docs and their mirrors.
One evening early in the autumn I was getting ready to start a new artist's site by copying one I already run. The chapter layout, the gallery that scrolls sideways, the language routing: nearly all of it carried over. If I asked the agent to "build it the same way as the last one," I expected it to get most of the way overnight.
I stopped when I opened the implementation notes of the site I was copying. Dated additions had started to pile up outside their sections, and the same caution appeared in another document in slightly different words. I wrote all of it, and I still couldn't say at once which version was current. Hand that over as it is, and the agent will pick one of them and fix things in a way that disagrees with the others.
Since then, as an indie developer copying my own work, I give the agent a one-page trap index before any step-by-step guide. What follows is the shape of one row in that index, the porting plan I write before the copy, and three small scripts that keep the index and the source documents from drifting apart, exactly as I run them.
The index holds one line of fix, and nothing more
The index exists to be looked up by symptom. Each row has four columns (symptom, cause, fix, source), and the fix stops at one line. Why that fix works, and how I found it, lives in a section of the source document; the index only points there.
It took me a while to settle on this. At first I kept adding the reasons to the index too. When a bad night is still fresh, you want to write all of it down. It didn't go well. The longer the rows grew, the more the same explanation sat in both the index and the source, and sooner or later only one of them got corrected.
I think a short index suits the agent as well. It narrows things down by symptom, opens the source section to read the reason, and only then makes a change. When the reading order is that clear, there is less room for it to invent a plausible alternative of its own.
What a row looks like, and rows I actually keep
Here are rows from my own index with the specific names removed. Each one is something I hit on a site built from the same template.
| Symptom | Cause | Fix | Source || --- | --- | --- | --- || Commit "succeeds" but push says everything is up to date | A stale .git/index.lock on the synced folder made the commit fail silently | Check HEAD with git log --oneline -1 | rules.md §3 || Deploy fails quietly and the old version stays live | A downloadable PDF exceeded the host's 25 MiB per-file limit | Check sizes with ls -l after generating | ops_guide.md §6 || Background flickers at chapter boundaries, worst on iOS | Current chapter picked by an IntersectionObserver center band | Treat the chapter containing the viewport's center point as current | knowhow.md §2 || On dark chapters in light theme, the toggle label disappears | One of the inverted tokens leaked | Invert all six tokens as one set on dark chapters | knowhow.md §2.1 || Build stalls for 10+ minutes on the synced folder | Writes to the synced folder are slow | Copy to a local disk, build there, bring back only the output | rules.md §3 |
The fourth row carries something I only noticed after building the index. I used to fix vanishing text in the zoom overlay with a local workaround: always give the overlay a dark background. Lined up in the index, that turned out to be just one symptom of a single leaked token, and the same root was making text disappear elsewhere too. Workarounds stay out of the index; the root goes in, in one line. Once I held to that, similar symptoms started showing up together when I looked them up.
Three rules for writing a row:
The symptom in the words of what you saw on screen ("the toggle label disappears," not "layout breaks")
The cause in one sentence, in terms of the mechanism
The source down to the file and section number
✦
Thank you for reading this far.
Continue Reading
What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.
WHAT YOU'LL LEARN
✦Before starting a new project from an existing repository, you will be able to turn the traps you have already hit into a symptom-first index, so an agent stops before carrying the same breakage across
✦You can catch, with a script and before release, the moment your index starts growing reasons of its own and becomes a second source of truth that disagrees with the first
✦Right after copying a template, you'll be able to count exactly where its specific values still live, separating deliberate traces in comments from real leftovers, and run that loop on your own repo
Secure payment via Stripe · Cancel anytime
✦
Unlock This Article
Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.
A lint that stops the index from putting on weight
Left alone, an index slowly takes on reasons. So I wrote a check that flags rows whose fix is too long, rows with no source, rows whose source file no longer exists, and symptoms listed twice. Whenever the agent updates the index, this runs afterwards.
#!/usr/bin/env python3"""Lint a trap index (a Markdown table).One row = Symptom | Cause | Fix | Source. A long Fix means the reasoning crept into the index;an empty or missing Source means the index outlived the document that justified it.Usage: python3 trap_index_lint.py docs/trap_index.md --root . [--max-fix 90]"""import argparseimport reimport sysfrom pathlib import PathHEADER = ["Symptom", "Cause", "Fix", "Source"]def rows(text): """Yield (line number, cells) for table rows, skipping the header and divider.""" for no, line in enumerate(text.splitlines(), 1): s = line.strip() if not (s.startswith("|") and s.endswith("|")): continue cells = [c.strip() for c in s.strip("|").split("|")] if cells == HEADER or all(re.fullmatch(r":?-{3,}:?", c) for c in cells): continue yield no, cellsdef main(): ap = argparse.ArgumentParser() ap.add_argument("index") ap.add_argument("--root", default=".", help="where Source paths are resolved from") ap.add_argument("--max-fix", type=int, default=90, help="max length of the Fix cell") a = ap.parse_args() root = Path(a.root) problems, seen = [], {} for no, cells in rows(Path(a.index).read_text(encoding="utf-8")): if len(cells) != 4: problems.append(f"L{no}: {len(cells)} columns (expected 4)") continue symptom, _cause, fix, source = cells if len(fix) > a.max_fix: problems.append(f"L{no}: Fix is {len(fix)} chars; move the why to the source, keep one line here") if not source or source in {"—", "-"}: problems.append(f"L{no}: no Source ('{symptom[:24]}')") else: # allow "path §3-2"; only the path part has to exist path = source.strip("`").split(" ")[0].split("§")[0].strip("` ") if path and not (root / path).exists(): problems.append(f"L{no}: Source {path} not found") if symptom in seen: problems.append(f"L{no}: same symptom as L{seen[symptom]}") seen.setdefault(symptom, no) for p in problems: print(p) print(f"checked {len(seen)} rows, {len(problems)} problem(s)") sys.exit(1 if problems else 0)if __name__ == "__main__": main()
Run it on a deliberately broken index (a missing source file, a fix that tells the whole story, and a duplicated symptom) and it stops like this:
L4: Source docs/rules.md not foundL5: Fix is 143 chars; move the why to the source, keep one line hereL6: no Source ('Background flickers at c')L6: same symptom as L3checked 3 rows, 4 problem(s)
I picked the limit after lining up the fixes in my own index, which is written in Japanese and uses a 60-character limit there. Of a little over seventy rows, the median fix was about 30 characters and only seven went over 60. Two of those seven had absorbed dates and commit hashes, the history that belongs in the source. The other five were simply long because they listed commands or variable names, and they were fine. So I treat the limit less as a wall and more as a cue to reread that row. English runs longer per idea, hence 90 here; please measure your own rows before choosing. A pipe inside a cell adds a column, so fixes that need a shell pipe go to the source document instead.
Before copying, write the porting plan on one page
If the index records what you stepped on, the plan records what you bring and what you leave. Before the copy starts, I write five things per component on a single page:
The component and where it lives in the template
Take it, take only the mechanism, or leave it
How it changes in the new site
Traps that tend to come with it (as index row numbers)
A list of what does not come along (designs and features unique to the template)
The one rule that mattered was never moving on with the "how it changes" column blank. Reuse the structure untouched and you get the same template in a different color. So the plan draws the line early: mechanisms come from the template, while the visual and motion vocabulary is rebuilt for the new site. When I hand a component marked "take" to the agent, its "how it changes" note goes with it; otherwise the template's motion simply walks across.
I also freeze the plan once the production setup exists. The top line says it is no longer updated and points to the document that tracks the current state. A plan that keeps getting edited ends up sitting next to the status document, and the double bookkeeping starts again.
Right after the copy, count what the template left behind
A freshly copied repository is full of the template's specific values: the domain, the contact form endpoint, the analytics ID, the artist's name. I keep a list of those values in the template and run a small script against the new repo. Traces I left on purpose in comments are counted separately and don't fail the run.
#!/usr/bin/env python3"""Count template-specific values still left in a freshly copied repository.Keep the list of values (one per line, lines starting with # ignored) in the template,and run it against the new repo. Hits on comment lines are counted separately asdeliberate traces and do not fail the run.Usage: python3 leftover_values.py template_values.txt app components lib public"""import reimport sysfrom pathlib import PathTEXT_EXT = {".ts", ".tsx", ".js", ".mjs", ".css", ".json", ".md", ".html", ".py", ".txt", ".toml"}COMMENT = re.compile(r"^\s*(//|#|/\*|\*|<!--)")def load_values(path): vals = [] for line in Path(path).read_text(encoding="utf-8").splitlines(): line = line.strip() if line and not line.startswith("#"): vals.append(line) return valsdef main(): if len(sys.argv) < 3: sys.exit(__doc__) values = load_values(sys.argv[1]) pat = re.compile("|".join(re.escape(v) for v in values), re.IGNORECASE) live, in_comment = [], 0 for top in sys.argv[2:]: for f in sorted(Path(top).rglob("*")): if not f.is_file() or f.suffix not in TEXT_EXT: continue try: lines = f.read_text(encoding="utf-8").splitlines() except UnicodeDecodeError: continue # skip binaries that slipped through for no, line in enumerate(lines, 1): m = pat.search(line) if not m: continue if COMMENT.match(line): in_comment += 1 else: live.append(f"{f}:{no}: {m.group(0)} <- {line.strip()[:70]}") for x in live: print(x) print(f"{len(live)} left ({in_comment} in comments, ignored)") sys.exit(1 if live else 0)if __name__ == "__main__": main()
With the analytics ID and form endpoint still in place, it reports this. Fix both and run it again, and it drops to zero with only the comment left.
What this script really gives me is a single definition of "done." Ask an agent to swap the values, and it may fix what it notices and report that it's finished. On my side, done means this prints zero, and I don't move on until it does. An analytics ID that ships unchanged would quietly mix the new site's visits into the old site's numbers, and you can't see that by looking at the page; counting is the safer judge.
Bringing improvements back, and the drift of copies
Building something new from a template produces good parts on the new side: a cursor design, a hover where the background fills from the point you entered, a thin line that shows how far you've scrolled. I've carried parts like these back into a site already in service, with the same rule as the plan: the mechanism from the new side, the visual vocabulary of the site receiving it.
The trouble starts when the recipe for a part needs to be read from more than one place. I keep the source of truth in one location, put mirrors elsewhere, and start each mirror with a note naming its source. Then a check confirms nobody edited a mirror directly.
#!/usr/bin/env python3"""Check that mirrors still match their source of truth (catches edits made to a copy).mirrors.txt holds "source<TAB>mirror" per line. Every mirror starts with a"> Mirror. Source of truth: ..." note, so that line is ignored when comparing. python3 mirror_check.py mirrors.txt # report drift (exit 1 if any) python3 mirror_check.py mirrors.txt --write # rebuild mirrors from the source"""import difflibimport sysfrom pathlib import PathNOTE_PREFIX = "> Mirror. Source of truth: "def body(text): return [l for l in text.splitlines() if not l.startswith(NOTE_PREFIX)]def main(): if len(sys.argv) < 2: sys.exit(__doc__) write = "--write" in sys.argv base = Path(sys.argv[1]).resolve().parent drift = 0 for raw in Path(sys.argv[1]).read_text(encoding="utf-8").splitlines(): if not raw.strip() or raw.startswith("#"): continue src_rel, dst_rel = raw.split("\t") src, dst = base / src_rel, base / dst_rel want = src.read_text(encoding="utf-8") if write: dst.parent.mkdir(parents=True, exist_ok=True) dst.write_text(f"{NOTE_PREFIX}`{src_rel}` (do not edit here)\n{want}", encoding="utf-8") print(f"wrote: {dst_rel}") continue if not dst.exists(): print(f"missing mirror: {dst_rel}") drift += 1 continue a, b = body(want), body(dst.read_text(encoding="utf-8")) if a != b: drift += 1 print(f"drift: {dst_rel}") for d in list(difflib.unified_diff(a, b, src_rel, dst_rel, lineterm="", n=0))[2:8]: print(" ", d) if not write: print("in sync" if drift == 0 else f"{drift} drifted") sys.exit(1 if drift else 0)if __name__ == "__main__": main()
Change a number only in the mirror and it stops, showing the differing line:
drift: shared/20_recipe.md @@ -2 +2 @@ -Stagger delays in 120ms steps +Stagger delays in 150ms steps1 drifted
I don't reach for --write straight away here, because sometimes the change in the mirror is a real improvement. I read the diff, and if it's right, I move it into the source first and then regenerate the mirror. Improvements always travel through the source, in the same direction as bringing parts back.
The order I follow on copy day
On the day I actually copy a repository, the tools above run in this order:
Run trap_index_lint.py on the template side, so the index and its sources agree before anything moves
Write the one-page porting plan and confirm every "how it changes" cell is filled
Copy the repository and replace values until leftover_values.py prints 0
Rework components one at a time; when stuck, look up the index by symptom. A new trap goes to its source first, then one line in the index
Before release, run mirror_check.py for drifted copies, then freeze the plan
Some days I'm tempted to skip the first step, and I'd recommend not doing so. If the template's documents disagree with each other when you copy, the disagreement moves into the new repository along with everything else.
The one page the agent reads first
Once the index, the plan and the checks exist, I link each of them from whatever instruction file your agent reads at the start of a session (workspace rules, AGENTS.md, or whatever your setup loads automatically). I don't copy their contents in; a copy there would become a third source of truth. Roughly, it's these few lines:
## This repository started as a copy of another site- Stuck? Before fixing, look up docs/trap_index.md by symptom; read the section in the Source column for the why- What to bring and how it changes: docs/port_plan.md (frozen; current state in docs/status.md)- A new trap goes into its source section in 1-3 lines, and into the index as exactly one line- Before a change that alters an assumption (URLs, cookies, how classes are applied), grep every place that reads it- Value replacement is done when leftover_values.py prints 0; also run trap_index_lint.py and mirror_check.py
The fourth line came from a bad day: a fix I had made the previous day had broken detection somewhere else. It's hard to see when you made the change yourself, but I now think a change to an assumption isn't finished until you've counted everything that reads that assumption. Since then I run the same checks before and after a fix and compare whether the differences appear only where I meant to change something.
Traps I fell into myself
Four places where I tripped while running this:
The index becomes a second source: the urge to add a reason is the signal to add it to the source section instead. The lint's limit is there to turn that signal into something a machine notices
A workaround hides the root: before listing a local patch (pinning one screen's colors, lengthening one delay), I look once for anything else the same root might be breaking
Keeping the plan alive: the plan records decisions made before the copy. When current state starts creeping in, freeze it and point elsewhere
Editing a mirror: whatever you wanted to change in a mirror, move it to the source and regenerate. An improvement that lives only in a mirror will vanish on the next copy
I've also settled on one way back when the documents get messy. Once dated additions start scattering outside their sections, I move the full document into an archive folder and fold the live version back into its sections. Having the full text set aside makes cutting much less nerve-racking.
Where I draw the line now
Starting the next site from a template turned out to be less about copying code and more about handing over what I'd stepped on; I realised that somewhere along a line of sites built from the same lineage. The fix, one line in the index; the reason, once in the source. However fast the agent writes, mixing those two jobs means I end up deciding, every single time, which of two documents to believe.
The next time you copy an existing repository, I'd suggest starting by writing down just five places you got stuck before, in those four columns. Five rows are enough to get a feel for looking things up by symptom, and enough for the lint to be worth running. From there, one more row each time you get stuck is plenty.
Share
Thank You for Reading
Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.