For most of its life, the tool I maintain was good at one half of the job: keeping specifications structured, versioned, traceable, and honest about their status. The other half — actually getting the words onto the page — was still the user's to grind through. You stared at an empty requirement file and tried to remember every section that belonged there, every edge case you'd regret forgetting, every sibling spec you might be about to duplicate.
This week I shipped the half that helps with that. The interesting part isn't that there's now an AI in the loop. It's that I deliberately didn't ship the obvious version of it.
Full disclosure: I'm the creator of SPECLAN, a VS Code extension that manages product specifications as Markdown files with YAML frontmatter — Git-native, one file per requirement, organized in a hierarchical tree. The pattern works without the tool; SPECLAN is just where I observed and engineered around the design problem below.
The obvious version: one button
The obvious version of "AI helps you author specs" is a single button: Improve this spec. You write a rough draft, you click it, the model rewrites the whole thing better. Every AI authoring feature trends toward that shape because it demos well and it's one code path.
I built that. I didn't ship it. Two days into using it on my own specs, it was clear the single button was quietly doing two unrelated jobs badly, because they're not the same job.
Correctness and completeness are different problems
Watch what actually goes wrong with a first draft, and it fails in two distinct ways.
It's confidently wrong. The model fills every section with plausible-sounding text. The gaps don't announce themselves — they hide as assumptions nobody questioned until an implementer hit one three weeks later and built the wrong thing. "The system shall let users export their report" reads fine until someone asks: which formats? who's allowed? what about a report still generating? That's a correctness failure, and the fix is interrogation — someone has to ask the questions the draft glossed over and get answers.
It's narrow. You wrote the version of the feature that was in your head. The three adjacent things a good reviewer would have raised never made it onto the page, because review hasn't happened yet — including the ways the new spec quietly contradicts the specs already around it. That's a completeness failure, and the fix is the opposite motion: not asking the author what they meant, but proposing what they didn't think of.
Interrogation and proposal are different interaction models. One is a question form you answer. The other is an idea pool you accept or reject. Bolt both onto one "improve" button and you get a model that does each one vaguely. So I split it into two tools, each doing one thing legibly.
Clarify — make it correct
After the assistant drafts a spec from your one-line idea, Clarify reads it back the way a skeptical reviewer would: ambiguous wording, underspecified behavior, missing scope boundaries, decisions the draft assumed instead of stating. It hands you up to a few targeted questions — multiple-choice when several answers can apply, single-choice when it's one decision, free-text when it needs your judgment. You rate how much each question matters; you skip any you can't answer yet. Nothing blocks you.
On submit, it doesn't append a Q&A list to the bottom of the spec. It runs a refinement pass that works your answers back into the draft body and returns you to the draft, tighter. Before:
## Specification
When a user logs in, the system shall greet them with a
fortune cookie message.
The questions surface the holes — where is it shown, which sign-ins trigger it, what about service accounts. You answer two, skip one. After:
## Specification
On a successful interactive sign-in, the system shall display
a fortune cookie message in a non-blocking banner. It auto-dismisses
after 8 seconds. Shown at most once per user per calendar day;
service and automation accounts are excluded.
Same idea. A spec an implementer can build from without guessing.
Brainstorm — make it complete
Clarify makes a draft correct. Brainstorm makes it complete — and this is where I had to be most careful not to turn it into "add more stuff."
From your idea and the surrounding spec context, Brainstorm generates idea cards. What it raises is the thing I didn't expect to be the most valuable: not feature padding, but inconsistencies with the specs around the draft. A timing rule that contradicts an existing business rule. A dependency reference pointing at a bare ID instead of a real link. An out-of-scope exclusion that names a sibling spec ambiguously. You Accept what belongs, Reject what doesn't. Only accepted ideas are worked in.
The detail I'm proudest of is what happens to a rejected idea. If Brainstorm proposes "scheduled recurring export" and you reject it as scope creep, it doesn't just vanish — it can land as an explicit ## Out of Scope line. The thing you decided not to do is now written down on purpose. The difference between a spec that's complete and one that just looks finished is whether the deliberate exclusions are visible.
The user is the filter. Brainstorm widens the option space; it never widens scope without consent.
The posture, not just the features
The reason this is two narrow tools instead of one button isn't ergonomics — it's a stance about what an AI authoring flow is allowed to do. At no point does the tool finalize a spec for you. Clarify asks; you answer or skip. Brainstorm offers; you accept or reject. The draft lives in memory until you explicitly press Create, and it lands in draft status — the start of the review lifecycle, not the end of it. Owners and stakeholders review it exactly as they always have.
That constraint falls directly out of the product's premise. A spec's whole value is that it's a reviewed artifact with status discipline. An AI flow that auto-finalized specs would contradict the thing that makes specs worth keeping. So the flow is deliberately shaped so the AI accelerates the draft without bypassing the review the lifecycle exists to enforce. The single "improve" button quietly erodes that. Two suggest-then-decide tools preserve it.
The unglamorous win that shipped alongside
Not every improvement needs an AI. The same release ships a plain Search Bar in the editor — permanently visible, full-width, find-in-document with live highlighting, a match counter, next/previous with wraparound, and keyboard shortcuts to focus and clear. Case-insensitive, full-string matching, ignores the hidden YAML frontmatter. It's invisible until the first time a requirement grows past one screen and you need one acceptance criterion now. Secondary to the AI headline, but the quality-of-life touch long-time users had been asking for, and worth saying out loud that "ship the boring thing people actually asked for" still belongs in a release.
The generalizable lesson
If you're building AI authoring into any tool, the temptation is always the single universal "make it better" action — it's one code path and it demos beautifully. The lesson I keep relearning: before you build the button, name the failure modes it's supposed to fix. If there's more than one and they need opposite interaction models, one button will do all of them vaguely. Correctness wants interrogation; completeness wants proposal. They earned two tools because they were two problems.
The SPECLAN-specific tour — the full flow, screenshots, the Search Bar, and a step-by-step walkthrough — lives in the release notes and the help guide. The video at the top is the 3-minute version.
What's a feature you shipped as one action that, in hindsight, was secretly two? Curious whether the "name the failure modes first" lens lands the same way elsewhere.
Top comments (0)