Refine a spec
How to improve a focus area spec after initial extraction — tightening results, filling in boundaries, and handling late-breaking requirements.
A spec is never finished on the first pass. This guide covers how to improve focus areas after initial extraction — whether during the review phase or mid-build when reality diverges from the plan.
When to refine
During review (before plan generation). This is the cheapest time to refine. Changes here cost nothing — the plan hasn't been generated yet and the agent hasn't started work.
During the build (before agent picks up the focus area). Still cheap if the agent hasn't started on this focus area. Update the spec and the agent will pick up the changes on its next read.
During the build (after agent has started). More expensive. Raise a clarification explaining what's changed and why, then update the spec. The agent will see the clarification, pause if needed, and re-read the spec before continuing.
Tightening results
Results are the most commonly under-specified part of a focus area. Signs that results need tightening:
- They describe what will be built rather than what will be observable
- They contain words like "properly," "correctly," or "as expected" — these are undefined
- A developer could interpret them multiple ways and all interpretations would pass
To tighten a result, ask: how would a reviewer test this? Write the result in terms of what the reviewer would observe. If you can't describe the test, the result isn't specific enough.
Filling in boundaries
Good boundaries are concrete, not conceptual. "Mobile is out of scope" is a boundary. "We're not building a full CMS" is not — it's too abstract to be useful in a spec.
For each focus area, run through adjacent capabilities and ask whether they're in or out. If it's out, write it down. Edge cases you explicitly rule out in the boundary become clarifications you'll never need to answer.
Handling late-breaking requirements
Sometimes a new requirement arrives mid-build that belongs in an existing focus area. You have three options:
Update the existing focus area. Right when the requirement is genuinely part of the original scope but was missed. Raise a clarification to notify the agent.
Create a new focus area. Right when the requirement is new scope — genuinely separate work that wasn't in the original brief. Add it to the plan in the appropriate phase.
Defer to a new initiative. Right when the requirement is substantial enough to warrant its own brief, goals, and plan. Create a linked initiative.
Spec change history
Every edit to a focus area is versioned. You can view the full history of a spec from the focus area's History tab. This is useful for understanding why a decision was made, and for auditing what changed when a build diverges from expectations.