How do you stop agents from making arbitrary architectural decisions before writing code?

[RolandoQuintana]

I love the workflow discipline of this repo, but I often run into an issue right before implementation. The flow jumps straight from the spec/tickets into generation, leading to design choices that can be arbitrary or counterintuitive (not always but sometimes)—leaving me to ask "why was it built this way instead of another, possibly more intuitive way?" only after the code is written.

How are you all handling this architectural gap? Are you using specific prompts to force a design/trade-off debate with the agent before it starts coding, or is there an existing pattern in the repo I should be leveraging?

I'm not sure a single SOP doc would help it either since it's just beyond code styling - it's a selection of the many ways to reach the agreed outcome.

[lab1207]

This gap is real and I've seen both sides of it in agent systems I contribute to. The pattern that works is making the design decision a gated artifact, not a prompt wish — two parts:

1. A decision record before generation. Between tickets and code, require the agent to write down: the options considered, the trade-off for each, and the choice + why. Not an SOP doc — a per-task record (one ADR-like note per ticket). The 'why was it built this way' question you ask after the fact becomes unaskable, because the answer is already written before code exists. In repos I work in, governed actions go through explicit approval gates; the same shape applies here: the ticket isn't 'ready for implementation' until its design note exists.

2. Enforce the gate in the skill instructions, not in a prompt you type each time. The reason the flow 'jumps straight to generation' is that nothing in the workflow blocks it. If your implement skill's instructions say 'do not write code until the design note for this ticket is recorded and approved', the agent treats it as procedure, not style advice. Prompts debate; gates decide.

What I'd check in this repo specifically: whether the spec→tickets handoff has a defined 'design complete' state or goes straight to implementable tickets. If tickets carry acceptance criteria but no design field, that's the structural hole — add 'design/options considered' to the ticket shape and make implement refuse tickets without it. The grilling flow already extracts decisions from you before spec; extending that same extraction one step further (per-ticket trade-offs) fits the existing machinery better than a new debate prompt.