📝 Gremlins code verdict, grotto plan-structure brainstorm, journal

2026-10-16 22:47:59 +02:00
parent bef84b3391
commit dff19572ab
3 changed files with 199 additions and 0 deletions
@@ -0,0 +1,34 @@
+# Grotto: plans need code structure — user's thoughts after the headless-forks build
+
+**Date**: 2026-10-16 22:41
+**Source**: the user, written out after reading the `headless-forks` prototype (4,155 lines in one file). Recorded by Igor, session [2026-10-15-21-grotto-work](../journals/2026-10-15-21-grotto-work.md). These are the user's thoughts, kept close to their words; they are not yet decisions.
+
+## The thoughts
+
+- **The gremlin would have helped here.** A trained implementer that knows the code, forked per block, is exactly what this build lacked: every block was a cold-start agent re-reading 5–6k lines of plans, digests, run log and code.
+- **Grotto should go back to putting some code in the plan.** Not super sophisticated, but at least the **structure of the code**: modules, the data model, the main interfaces. Plans without code (Spire 0.2.x) left the architecture to whoever built each block, and per-phase contract digests then invented it piecemeal.
+- **How to approach a problem:**
+  1. Make the **happy path** work first.
+  2. Then build **proper abstractions** around the problem.
+  3. **Iterate** over it.
+  4. Trust that an Opus agent can **easily throw out lots of code**. Deleting is cheap; don't protect what was written.
+- **Open question: how much code can an Opus agent write in one go?** (The user wants to know. Worth measuring, e.g. by having one agent write the minimal gremlins version from a structure-fixing spec.)
+- **Abstraction is also about sidestepping.** More side effects and special cases need space to grow into, and a good abstraction gives them that space instead of letting them spread through if-chains.
+- **"Could all this not be expressed simpler?"** For example, resolve complex ifs into a simple, elegant `match`, or move a class up a layer because that decouples the whole structure. Simplification is design work, and no stage of the current cycle does it: reviews hunt bugs, fixes add, nothing removes.
+- The user wonders whether this is partly their own fault, for being chaotic and having too many thoughts at once. *(Igor's note: the build's failure modes — no structure in the plan, cold starts, review loops that only add — are process failures, not the user's.)*
+
+## Answer: how much code can Opus 5.5 produce in one go?
+
+*(Igor, 2026-10-16, from the claude-api skill's model table)*
+- One response can hold up to **128K output tokens** (Opus 5.5's cap; values that large need streaming). Thinking tokens count against the same cap.
+- At a rough 10 tokens per line of Python, that is a ceiling of about **10–12k lines in one response**. In practice it's less: the thinking share, Claude Code's own output limit (configurable, possibly lower than the API cap; not checked here), and quality, which drops over very long single outputs.
+- All of gremlins.py (4,155 lines, ~45–50k tokens) would fit into a **single response, or two**.
+- Across a session, "one go" is effectively unbounded: an agent writes file after file over many turns within its 1M context.
+- So output volume was never the bottleneck. The day went to orientation, coordination and verification, not to typing.
+
+## Related
+
+- Journal open threads: "Process lessons to accrete" (budgets, a design/size criterion in reviews, cutting unrequested additions, a plan that fixes structure, re-planning when a premise falls).
+- [goals/drop-superpowers-0.2.2.md](../goals/drop-superpowers-0.2.2.md): grotto carries the design → plan → handoff procedure.
+- [reports/2026-10-15-22-spire-vs-superpowers-plan-and-build-experiment.md](../reports/2026-10-15-22-spire-vs-superpowers-plan-and-build-experiment.md): "code in the plan adds nothing" was measured on correctness and merge choice, not on design quality.
+- Code verdict on the prototype: reports/2026-10-16-22-gremlins-code-verdict.md (pending).