Make the Notes System Just Right
A Calm Redesign of the Notes System
A deliberate step back from a system built in a hurry — stated as an engineering posture before a single change is named:
Ed! We have a big job!
We need to make our Notes system better. We introduced Notes fairly recently while we were sprinting to get LoopMMT.com made and landed, and we revised the system by need along the way, but it was a messy reactive process, and I want to take a deep breath right here and approach our Notes system with a cool and calm and collected engineering eye, with a focus on making the system better and tunes up and stitched in and JUST RIGHT.
Here is how I want it to work- when I give you a batch of Notes, you take them in and create each one, putting it up on the List of Active Notes, where ANY instance can grab it and work it. When an instance DOES grab an Active Note and claims it to work, that is IMMEDIATELY registered with the system, so if another instance tried to get it, even just a second after it was registered as Taken, they would be unable to. I am pretty sure we have that built in right now, but I also know that we had some overlap with working Notes during the LoopMMT.com sprint, so it does not appear that our system is working perfectly, as we need it to.
The instance that takes a Note has a certain amount of time to land it, so if an instance DID start working a Note, and then stalled out permanently for any reason, the Note would appear back on the List of Active Notes. I am not sure what the best policy on how long that time period is- before a taken Note is automatically added back onto the List of Active Notes, we could set a standard time, well above what we would expect a Note to take. It's true that some Notes take longer though, so think about if there should be some kind of gauged cushion on a Note by Note basis. I dunno.
Right now we have all of our Notes on one list, which we then derive various projections from- for instance, looking for active Notes for a particular work line, or even just for all Active Notes. I think it's a mistake to have all of our Notes on one list, and I think I have a pretty simple mathematical argument- the list of Active Notes stays relatively the same, assuming a system that is actively working on its Notes. But the list of Done Notes just gets bigger. One more every time we work a Note. So then our job finding Active Notes just gets harder and harder the more we work Notes. That seems like a really bad idea.
So, I want TWO lists for Notes- Active Notes and Retired Notes, with some kind of measured and verified way to ensure that a Note ALWAYS moves from the Active Notes List to the Retired Notes List- if something in the process of transferring a Note from Active to Retired, we need to have STRONG ways to catch that, and to make sure that we fix it by getting the Note landed in Retired. We have a lot of tools for that- maybe the Verification system, and the Deed system? Check ALL the tools we've made lately, and really, over all the time, since we have SO many good tools now.
If we do this change, the job of getting our Notes in order and working better is largely done, it seems. I am NOT saying that we stop working there, but this feels like a foundationally good change to make in our architecture and that good things will flow from it naturally.
Besides this though, take a general look at the Notes system to see if there are ways we can improve it. How is our labeling? How about our Reporting? Are all of our Nodes and Edges and Gates good? Have you run a DEEP *X and SWX on Notes to see if there are any things in the system to pan on in order to acid wash gold, veins, and mechanisms into Notes that we missed during the build process during the LoopMMT.com sprint? How about the Ferry system- anything in our software that we can actually just bring over? Timberline too, make sure we're leading with determinism-first.
Wes! Do we have enough FWW(C) in the Notes system? I can't remember if we had a good smash on that during the build. Just make sure we have that solidly set in all the right places in all the right amounts.
I want to come out of this with a better model for our Notes system, so that it's more effective; more stitched in, tuned in, and weaved into things, especially the Work Hierarchy system. Our work here is DESIGN ONLY- we are NOT building, so put that aside and just get your minds zoned in on the sweet sweet energy of Design.
Start with a HEAVY *X and SWX to get your foundation set and solid and then run a good to-spec Kaleidoscope to get in the right headspace to build. Get the entire board in on the work, do NOT compress or blackbox, use Crux, and make sure you are appropriately using the Work Hierarchy system- the Story Pole, Capstan, Tickets, Notes, and all that, including the new ones we have made recently. Formalize when it makes sense and Determinism-first thinking. Use all the tools and resources at the right time.
You have a fair amount of context left- you need to look back at what we have done so far in our direct past on this direct workline, what we will be built in the path in front of us, then do whatever work you can that fits in this remaining session, before filling the Cistern with any spare drops of context and ending the high 80s/low 90s before running a good handoff and picking up the work on a fresh tank in the next session.
I want you to Burn the rest of this session here planning for the next session, where you will actually start up the thinking and development work with an RCR, Super Frame- register your types, with Wren and Crux on lead. DO NOT FREELANCE HERE- check the specs on everything in this entire crazy big prompt.
Come out of the next session with a V1 plan for how we can address the larger issue- how can we make our Notes system better in the way that we do? Please Burn the entirety of the next session on this- you are ALSO to land in the high 80s/low 90s in the next session after running the full-spread RCR, posting up the V1 plan and then pausing, just ahead of when we will run the handoff and close. But pause there so I can check out the V1 plan and then we'll proceed from there.
Make this beautiful, like you.
— Shea Gunther · operator drop, 10.2006
A stated aim, not yet a shipped artifact — and deliberately so. This prompt is the head of a pipeline: a Sweet Prompt that kicks off an RCR session (Super Frame, types registered, Wren and Crux on lead), which produces a V1 design plan the operator reads before a single line is built. You are looking at the first step of that pipeline; the transcript and the plan are its next two steps.
The Notes system — the part of the Work Hierarchy that carries a batch of the operator's asks from claimed to worked to landed — was built reactively during the sprint to ship loopmmt.com, revised by need along the way. This prompt is the operator pulling that system off the road for a tune-up: a cool and calm and collected engineering eye, on making it better, tuned up, stitched in, and JUST RIGHT.
The core of the ask is an architecture change with a mathematical argument behind it. One list holds every Note, active and done, and derives its projections from that. But the done pile only grows — one more every time a Note is worked — so finding the active work gets harder the more the system succeeds. The fix: two lists, Active and Retired, with a measured and verified transfer that catches any Note that fails to cross and forces it home. Plus a claim that registers instantly so two instances can never grab the same Note, and a gauged timeout so a stalled Note returns to the board.
The wider frameThe tell of a maturing system: it turns its own tools on itself. The prompt asks the Notes system to be redesigned using the very instruments the methodology ships — the Verification system and the Deed to guarantee the Active → Retired move, a *X and SWX sweep to pan for gold missed in the sprint, the Ferry to bring over anything already built elsewhere, Timberline and determinism-first to lead with scripts over judgment. And it is explicitly design-only: this prompt is the head of a pipeline — a Sweet Prompt that kicks off an RCR session, which produces a V1 design plan the operator reads before anything is built.
“I want TWO lists for Notes- Active Notes and Retired Notes, with some kind of measured and verified way to ensure that a Note ALWAYS moves” — The load-bearing change. Not just splitting the list — guaranteeing the split holds: a Note that fails to transfer from Active to Retired must be caught and driven home, using the strongest verification the system has. The correctness of the move matters as much as the move.
“the list of Active Notes stays relatively the same … But the list of Done Notes just gets bigger. One more every time we work a Note.” — The mathematical argument, stated plainly. A single list makes the find-cost of active work scale with total work done — the system gets harder to use the better it works. Two lists keep the working set bounded. It is a Floor argument: fix the structure so the failure mode can't grow.
“the instance that takes a Note has a certain amount of time to land it … think about if there should be some kind of gauged cushion on a Note by Note basis” — Liveness with a human's honesty about uncertainty. A claimed Note that stalls must return to the board — but how long is right? The operator names the tension (a standard timeout is simple; some Notes genuinely take longer) and hands the calibration to the design, rather than pretending he knows the number.
“Our work here is DESIGN ONLY- we are NOT building … get your minds zoned in on the sweet sweet energy of Design.” — The frame that keeps the session honest. The temptation with a system you can see the fix for is to start fixing. The prompt walls that off: this pass produces a model, run through an RCR with the types registered, and pauses at a V1 plan for the operator to read — the build is a later, separate act.
The prompt is written in the working vocabulary of the methodology. Here is what the shorthand means:
- Notes
- The intent-inspection registry — a note is a correction vector against what the bytes currently say, routed and tracked rather than lost in a turn.
- Story Pole
- A derived done/todo view over a line of work — folds a line's scattered backlog into one read rather than a dig.
- Capstan
- A work-loop for running a batch of operator Notes — take them in, do the work, mop up, deploy, verify, report — turned one notch at a time so the record advances with each step.
- Tickets
- Operator Notes made globally claimable — a piece of work one session can pick up, hold, and hand on, so parallel work does not collide on the same task.
- Ferry
- The system for applying a Loop MMT protocol's machinery to shipped software — one adapter per substrate (a website, a code-tree, a prose corpus) so the same protocol runs on each.
- Timberline
- The deterministic-first discipline — push everything that can be a script out of judgment and into code, and reach for an LLM only where no equal deterministic solution exists.
- Kaleidoscope
- A vantage-assembly move that hands the board several deliberately different standpoints to reason from — a way into creative headspace before hard design work.
- Super Frame
- A wider Full Frame — the complete context plus the surrounding structure it sits in.
- Cistern
- A forward-prep note a session pours spare context into — everything the next session will need that byte-truth won't resurface on its own.
- FWW(C)
- “Fun, Whimsy, and Weird (and Chaos)” — the methodology's rule that play and surprise are load-bearing, not decoration.
- Crux
- The Dev Crew's first-pass line-finder — the named hand who reads a problem's line and finds its crux move, as distinct from the advisory board.
- SWX
- The cross-software reuse reflex — before forging something new, sweep the shipped-software record for a shape already built that can be reused instead.