Adam Lewis

Most of the review arguments I've sat through were two people discovering they'd assumed different requirements, so settling that in the spec first has cut most of them off. I've written up how I approach it here: https://prickles.org/tenet/spec-first-execution/P2

The clarification step is the one I see skipped most often, so it is good to see it named as work rather than overhead. I keep the questions and their answers in the spec itself, and the agent checks back against them as it builds. A surprising amount of review argument disappears when the ambiguity was settled in writing first.

That makes sense, an observed cap is more defensible than one picked up front because it comes from what the skills actually needed. And the number matters less than the fact that hitting it makes you stop and check whether the skill has quietly taken on a second job. Cheers for the detail.

Nice. The thing I'd point to in what you did is that the consensus ends up written in a doc the agents re-read, rather than only living in the session that produced it. That's the same reason the per-decision markdown files have stuck for me - the agreement survives the context window, so the next run picks it up instead of going over it again. I'll read through the synthesis proposal. Multi-agent coordination is one I haven't spent much time on yet.

Makes sense. I've found the same thing - getting the agent to say the invariants back before it writes anything surfaces a misread while it's still cheap to deal with. The one place I'd be careful is that it tells you it understood, not that the code does the right thing. I've had it restate a rule perfectly and then break it two functions later. So I treat the explain-back as the check on whether it read the brief, and keep a runnable test for whether the code actually holds to the rule once it exists.

Right, and the bit that's easy to miss is the check actually has to be able to fail. I've had specs where the "check" was something like compiles-and-returns-200, which the agent passes whether the behaviour underneath is right or wrong, so it tells you nothing. The ones that pull their weight are the ones that would go red if the thing they describe stopped working. Otherwise you've just written more prose for the agent to interpret, which is the problem you were trying to get away from.

We've seen the same pattern on smaller solo projects too. Authoring skill N+3 three weeks after skill N-1 with no PR review is exactly the failure mode. We'd copy the 110-line cap straight across. A number the agent can't talk past does more enforcement work than a written rule. Out of interest - how did you settle on 110 specifically?

The skills/ directory pattern is the same in our setup. We've got one markdown file per architectural decision the agent kept getting wrong, and they all get re-read at the start of every session. After a few sessions there's not much left to re-explain. Scalability is harder to catch with a hook alone. We've started writing the quantified threshold into the spec ('handles 30k rows in under 2 seconds'), so the agent flags it itself before I'd otherwise need to interrupt.

We've kept the runnable check as the load-bearing part of our specs too. Without it the agent grades itself generously on what "done" means. Have you found agents actually read the [A] layer first when prompted, or does it need a hook to enforce the order?