Timestamp (Europe/London): 2026-01-14 19:47
Clear, Repeatable, and Built for a Non-Dev Brain
With the v0.1 Paper Rules locked, the risk shifts. It’s no longer “do we know what the game is?” It’s “can we implement it without ambiguity, accidental scope creep, or mysterious non-repeatable behaviour?”
So we’ve agreed an approach that prioritises clarity over speed, repeatability over cleverness, and determinism over vibes. The goal is simple: every change should be understandable, verifiable, and easy to undo if it goes sideways.
The Golden Rule: No Implied Steps
Because I’m learning-by-building (and because future-me will forget details), we’re running with a strict “no implied steps” rule.
That means: if a task requires clicking, typing, creating, renaming, or selecting something in a UI (Visual Studio, GitHub, Windows), the instructions must explicitly say what to click and what you should see afterwards. We’re optimising for someone who doesn’t already know.
Our “Output Contract” (what every implementation answer must include)
- Goal (one sentence: what are we trying to achieve?)
- Where we’re changing things (exact file names and folders)
- Exact steps (click-by-click where relevant; one action per step)
- Verification (what should now work, what log line should exist, what test should pass)
- Rollback (how to undo safely: revert commit, delete file, undo setting)
When code is involved, we also add one extra rule: instructions must say exactly “Create file X” or “Replace contents of file Y”, and the full code must be provided in one go. No “and then you know the rest…” hand-waving.
The Implementation Loop: Spec → Build → Prove → Record → Repeat
This is the core cycle we’ll run for every slice of work. It keeps the project moving forward without turning into spaghetti (technical or organisational).
1) Discuss (micro-spec in plain English)
Before writing any code, we write a short “micro-spec” for the slice. This lives in the kanban card / issue and describes:
- What should happen (plain English)
- What inputs cause it (player actions / seed / orders)
- What outputs prove it happened (especially what must appear in TurnTrace)
- One or two concrete test scenarios (seed + steps + expected outcome)
This step is basically “measure twice, cut once” — it prevents us building the wrong thing efficiently.
2) Implement (small slice, no bonus features)
We implement only what the micro-spec says. If we discover a gap, we log it as a new card rather than quietly expanding scope.
3) Test (prove it works, then prove it repeats)
Every slice has verification. In v0.1 that includes a special requirement: determinism.
- Run the defined scenario and confirm the expected outcome.
- Run it again with the same seed/orders and confirm the outcome (and trace) is identical.
If it can’t be reproduced, it doesn’t really “work” yet — it’s just being polite in one specific run.
4) GitHub update (make it reviewable)
Each slice becomes a small branch and a Pull Request. The PR description includes the same verification and rollback steps, so future-me can understand what changed and why.
5) Kanban update (keep the board honest)
Cards move across the board based on evidence, not optimism. “Verify” means it has been tested and is repeatable. “Done” means merged, traceable, and not a mystery.
Then we loop back to a new micro-spec for the next slice. Rinse, repeat, and slowly accumulate a working strategy game instead of a pile of good intentions.
Where the Clarity Lives (So It Doesn’t Vanish)
We’re also anchoring the process in a few simple places so instructions never float around as tribal knowledge:
- GitHub Project board: the work queue and statuses
- Issues / draft issues: micro-specs and acceptance checks
- Pull Requests: what changed + how to verify + how to rollback
- Repo docs: short, practical pages like “how TurnTrace works” and “golden seeds for testing”
This keeps the project friendly to future-me, and also makes it easier for anyone following the devlog to understand what’s happening without being inside my head.
One Small UX Decision (And Why It Matters)
v0.1 won’t focus on a fancy main menu. That’s not the point of this milestone.
Instead, we’re building a debug-friendly “main game window” with a simple New Game flow (seed + galaxy size) and the essential controls to run turns and inspect the TurnTrace. The goal is usability and repeatability, not gloss.
The Point of All This
This approach is how we stop v0.1 becoming a swamp of half-working systems. It’s also how we keep the “experiment” honest: every claim (“it works”) has proof (“here’s the seed, here’s the trace, here’s how you reproduce it”).
Next up: we start with the spine — turn flow + TurnTrace — and then we build outward slice-by-slice until the rules become a machine.