Indeed Adam. The two documents problem is real if the spec becomes a permanent, competing source of truth. However, the counter-argument is that SDD + Atomic PRs fundamentally changes the spec’s lifecycle. As noted, if we cap PRs to one concern, the spec is an ephemeral contract, not a permanent architectural document. The question then pops up is Who retires it? In a mature workflow, the retirement is automated. Tools like Spec Kit’s converge command can be configured to archive or delete the spec files once the PR is merged and verified. The spec exists solely to align the agent during development. Once merged, the code and its tests become the single source of truth. If we treat the spec as a living doc that must stay in sync with production, it fails. But if we treat it as a temporary, auto-deleted verification layer for atomic changes, the drift problem disappears entirely.
@socialthinker
Abhishek Banerjee
@socialthinkerDelhi, IndiaJoined September 2026
Working Guy. Late-night code reviews, AI workflows & clear engineering docs. I write stories for growing tech brands.
About
Working Guy. Late-night code reviews, AI workflows & clear engineering docs. I write stories for growing tech brands. Reach out: abhishekninja2018@gmail.com
Available for
Need High-Impact Technical Content for Your Team? I partner with developer-tooling startups, SaaS platforms, and engineering teams to translate complex infrastructure, agentic systems, and backend architecture into publication-grade technical writing. Whether you need deep-dive architecture essays, hands-on developer tutorials, or technical counter-narratives: 📩 Email: abhishekninja2018@gmail.com 💼 LinkedIn: linkedin.com/in/abhishekninja 🐦 X (Twitter): x.com/AvishekBanzzov 🛠️ Capabilities: Long-form Technical Essays | Hands-On Tutorials | Developer Tooling Deep-Dives | Technical Counter-Narratives
Abhishek Banerjee's blogs
Comments
AB
AB
That is the ultimate spec-driven lesson one can get. It’s wild how often the bugs that survive aren’t logic errors, but missing sentences. I actually ran into a similar issue with auth scopes the agent built the perfect middleware, for one of my client when i went into detailed review of their code end; but the spec didn’t account for read-only service accounts. It’s a reminder that the Spec isn’t a set it and forget it document; it’s a living contract that needs to be stress-tested against real-world traffic patterns, not just happy paths.
AB
That’s the missing link for SDD. Tools like GitHub Spec Kit get the agent to break things down into atomic tasks, but human review is where the one concern rule is actually enforced. If we let the agent bundle modules, the spec becomes too high-level to catch edge cases. Capping the PR scope keeps the verification tight.
AB
This is the unsaid part of agent setup people do not talk about. We pair OpenSpec's delta specs with a simple counter in our CI pipeline if /opsx:verify fails more than twice on the same requirement, it auto-flags the PR for human review instead of letting the agent burn tokens on a third attempt. Stops the stall dead in its tracks.