reliquary/docs/workpad/brainstorm/2026-10-16-22-grotto-plan-structure.md

# 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.)*

## Correction and additions (user, 2026-10-16, later)

- "How much Opus can throw out" meant **how much output it can generate**, not deleting code. Igor misread this above as "trust Opus to throw code away".
- On deleting code, the user's actual view:
  - Throwing code away is sometimes wise, **as long as you commit before throwing it out**. History is usually useful.
  - All code teaches something. This prototype holds a lot of wisdom and logic, and the user doesn't want to downplay it. **It was just too much.**
  - It would have helped to have a prototype first, and then use it to write the real code.
- The user wants the whole build bundled into a report that honestly calls it a failure. The approval waits cost time, but they are not the main issue.
- **Guidance hasn't found its sweet spot yet.** Open question: how big are the skills in text, how much of it is filler, and is each skill truly written for an agent, or does it regurgitate knowledge the model already has?

## Steering sentences cut both ways (user, 2026-10-16)

- "Keep it small", "happy path first" and "delete what isn't needed" are themselves dangerous: they can fire the other way, into cut corners, missing error handling and deleted tests or needed code.
- Igor's take on safer framing (options, not decisions):
  - Tie size to requirements, not adjectives. Each function or module traces to an acceptance box, and anything that doesn't gets a one-line reason in the hand-back.
  - A size *estimate* in the plan that the builder must explain deviations from. A budget to justify against, not a cap to obey.
  - "Happy path first" as **sequencing**: the happy path runs end to end before edge cases get built. It's not a value judgement against edge cases.
  - Reviews report "unrequested surface" as a finding category with the decision left to Igor and the user. Reviewers don't delete on their own.
  - Pair every push with its counterweight in the same sentence, e.g. "cover the failure paths the boxes name; add no others without a reason".

## 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).