35 lines
3.7 KiB
Markdown
35 lines
3.7 KiB
Markdown
# 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).
|