Debate Before You Write: Pre-Spec Discussion
Part of the AI Software House series.
In short: My PM and PM Reviewer often spent several calls discovering they had different assumptions.
discuss_spec_brieflets the PM, reviewer, and architect talk through the raw requirement before the first PRD is written.
The revision loop problem
The standard pipeline PMβPM Reviewer flow works like this:
- PM receives the raw requirement and writes a PRD
- PM Reviewer reads the PRD and either approves or requests changes
- If changes requested: PM revises, PM Reviewer re-reviews, repeat up to 3 times
The loop is useful, but I noticed that the same kind of gap kept causing it: loose scope, vague acceptance criteria, or an edge case the PM had not considered.
The PM revises from the comments, but it is still responding after a whole document has already been written. Sometimes that takes all three rounds.
Each retry is another full call, plus more time before the architect can start.
The alignment problem behind the revision loop
The PM and the PM Reviewer approach the same requirement differently.
The PM is optimistic and constructive. Given "add webhook support", it writes a PRD that describes the happy path: register an endpoint, fire events on status changes, retry on failure.
The PM Reviewer is critical and thorough. It reads the same PRD and asks: what happens when the subscriber is down for a week? what's the queue depth limit? is delivery guaranteed or best-effort? what's the authentication model?
Neither role is necessarily wrong. They are looking for different things, and the PM does not know the reviewer's concerns until the review arrives.
The revision loop is where those assumptions finally meet.
Front-loading alignment with discuss_spec_brief
I decided to move that conversation earlier.
discuss_spec_brief is a discussion preset that puts PM, PM Reviewer, and Architect in a debate about the raw requirement. No PRD exists yet. They're debating what a good PRD would contain.
The reviewer raises its concerns early, and the architect can point out technical constraints before they are buried in a draft. The PM then starts with a much better idea of what this particular PRD needs to cover.
# pipelines/ai-feature-careful.yaml
stages:
- discuss_spec_brief # β PM + PM Reviewer + Architect debate the requirement
- pm # β writes PRD informed by the debate synthesis
- pm_reviewer # β reviews an already-aligned PRD
- architect
- junior_engineer
- senior_engineer
- qa_planner
- qa_engineer
The synthesis from the discussion is automatically injected into PM.run(). No extra config required β if discussion_synthesis is populated, the PM uses it. If not, it behaves exactly as before.
What the debate looks like
Given the requirement "add webhook support to the notification service":
PM: The core requirement is straightforward β an endpoint to register webhook URLs,
event firing on job status changes, and retry logic on delivery failure. I'd
propose a simple REST endpoint and a retry queue.
PM_REVIEWER: Before we write that PRD, I want to flag three things the spec will
need to cover: (1) authentication β how does the subscriber prove the event is
genuine? (2) idempotency β can the same event fire twice? (3) subscriber
management β can subscribers update or delete their endpoint?
ARCHITECT: The existing notification service uses Redis. A webhook retry queue
would fit naturally there. But if we need at-least-once delivery guarantees, we
should say so in the spec β that has infrastructure implications the engineers
need to know about.
MODERATOR: CONSENSUS_REACHED. The PRD should explicitly cover: HMAC signature
verification, idempotency via event IDs, subscriber CRUD endpoints, delivery
semantics (at-least-once vs at-most-once), and queue depth limits.
The PM now writes the PRD. It already knows to cover HMAC verification. It already knows to address idempotency. It already knows the architect's constraint about Redis. The reviewer, when it reads the PRD, finds exactly what it was looking for.
No homework_llm needed
Unlike architecture brainstorms, spec discussions don't need to search the codebase. Participants are reasoning about a text requirement β what it means, what it implies, what a good spec would say. That's pure reasoning.
Setting homework_round: false (the default for this preset) keeps the discussion fast. Three participants, two rounds, no tool calls. Typically 2β3 minutes.
The tradeoff is one short discussion against one or more full rewrites. For obvious requirements I skip it. For an ambiguous one, it has usually earned back its time before the first review.
Option A still works
The discussion stage can also go after the PM, before the reviewer β debating the written PRD rather than the raw requirement:
stages:
- pm
- discuss_spec_review # debate the PRD quality
- pm_reviewer
Or both:
stages:
- discuss_spec_brief # align on requirements first
- pm # write informed by synthesis
- discuss_spec_review # debate the written spec
- pm_reviewer # final verdict
The second pattern is useful when requirements are genuinely complex and you want two alignment checkpoints. The first discussion front-loads requirement clarity. The second catches any gaps in the written spec before the reviewer sees it.
Where this has been useful
This gave me a practical rule for discussion stages: put them just before a misunderstanding becomes expensive.
- Before the PM writes: misalignment costs revision rounds
- Before engineers write code: misalignment costs rework and PR re-reviews
- Before a major architectural decision: misalignment costs a rebuild
It does not guarantee a perfect spec. It simply gives disagreements a chance to appear while they are still cheap to fix.
Related reading: The Two-Model Split: Fast Debate, Slow Research