codebase-design: design-it-twice sub-agents can build on conflicting facts, and the comparison doesn't check them #1338

What I ran: /improve-codebase-architecture, then design-it-twice on one candidate. Following DESIGN-IT-TWICE.md, I spawned three sub-agents, each with a different constraint: minimize the interface, design for concurrency first, and optimize for the most common caller. All three briefs pointed at the same file of facts gathered beforehand: the call sites, their guards and the library's behavior.

What happened: one design rested on a library fact that contradicted that file. It assumed the ORM's conditional UPDATE returns the rows it changed, and used that to report which writes applied. The facts file said the update returns a row count, and the installed library source confirms it: UpdateQuery._execute -> int. The comparison step contrasts depth, locality and seam placement, and has no step that checks the facts each design depends on. The false premise went through that comparison unchallenged. I caught it only by reading the library source myself.

What I expected: the comparison to separate design differences from fact differences. When the sub-agents disagree on design, that is the point of the fan-out. When a design states a fact that contradicts the brief or the source, that is an error, and the comparison should surface it before judging the designs. A shared facts file alone does not prevent this, because the sub-agent read the file and still asserted the opposite.

• Harness: Claude Code
• Model: Opus 5.5