{"slug": "the-most-valuable-spec-kit-command-is-the-optional-one", "title": "The most valuable spec-kit command is the optional one", "summary": "GitHub's spec-kit toolkit for spec-driven development with AI coding agents has a critical optional command, /speckit.clarify, that interrogates specifications for ambiguity before planning begins, according to a developer's analysis. The clarifying step is essential because AI agents, unlike human engineers, resolve ambiguous requirements by guessing rather than asking questions, leading to hidden schema errors that surface weeks later as costly rework. The analysis also notes that spec-kit's planning documents double as a durable decision record, while verification tasks are often skipped once functionality appears complete, a structural failure mode in checklist-driven workflows.", "body_md": "# The most valuable spec-kit command is the optional one\n\n[spec-kit](https://github.com/github/spec-kit) is GitHub’s toolkit for spec-driven development: you define what to build before building it, and any of 30-odd AI coding agents does the implementing. The core loop is `constitution → specify → plan → tasks → implement`\n\n, and there’s a handful of extras listed as optional — `clarify`\n\n, `analyze`\n\n, `checklist`\n\n.\n\nI’ve been running it across several projects now. My single strongest finding is that **the optional step is the one that pays for everything else.**\n\nIf you keep one command out of the whole toolkit, keep `/speckit.clarify`\n\n— the pass that interrogates your spec for ambiguity *before* planning starts.\n\n## Why clarify matters more when an agent writes the code\n\nHere’s the pattern that repeats. A feature request sounds complete. You read it, it makes sense, nothing’s obviously missing. Then the clarifying pass asks two or three questions and every one of them changes the data model:\n\n- Is this number\n*captured*or*derived*? - Is this total the sum of its parts, or an independently reported figure that happens to land close to the sum?\n- Is visibility all-or-nothing per role, or per row?\n\nThose aren’t edge cases. Each one silently determines a schema. Get one wrong and the rework reaches all the way back to your migrations.\n\nNone of that is new. Ambiguous requirements have always been expensive, and teams have been interrogating specs for ambiguity since long before any of this was automated. What changed is what happens to an ambiguity that slips through.\n\nA human engineer, hitting a genuinely ambiguous requirement, stalls. They wander over to your desk, or drop a message in the channel, and ask. The ambiguity surfaces itself because a person got stuck on it.\n\n**An agent doesn’t get stuck.** It resolves ambiguity by picking something plausible and moving on — quickly, confidently, and the result looks finished. You get a complete-looking implementation built on a guess nobody reviewed. The ambiguity never surfaces as a question; it surfaces three weeks later as a schema you have to unwind.\n\nThat’s the whole argument for `clarify`\n\n. The step exists to force the questions into the open *before* there’s code, because the mechanism that used to surface them for free — a confused human — isn’t in the loop anymore.\n\n## The second payoff nobody mentions: specs are a decision record\n\nAn underrated side effect showed up when a governance question came up late on one project: does this architectural decision need to be formally recorded?\n\nThe answer was defensible, and it was defensible *because* the design decisions were already written down — at the time they were made, with their reasoning attached.\n\nThat’s the thing teams almost never have and always want six months later. And with spec-kit it’s essentially free: `spec.md`\n\nand `plan.md`\n\nalready exist, written to direct the work. They just need to live somewhere durable. Planning documents you wrote to steer an agent turn out to double as the record of *why the system is the way it is*.\n\nWorth optimizing for deliberately. If your specs are getting deleted with the branch, you’re throwing away the most valuable artifact of the process.\n\n## The failure mode: verification tasks are the ones that get skipped\n\nNow the part that bit me hardest, because it’s structural rather than occasional.\n\nThe most reliable failure in any checklist-driven workflow: **the feature works, so the tail of the list quietly stops getting done.**\n\nA concrete case. One slice was considered complete for weeks — functionality working, everyone moved on. An audit later found its final tasks had never been run. Among them was a design-consistency check, which then turned up **three shipped screens with no approved design at all.**\n\nNobody lied. Nothing was hidden. The work simply *felt* finished once the functionality worked, and everything remaining in the list was verification.\n\nThat’s the trap: a checked-off task list creates false confidence precisely where verification lives. The last phase is the one that proves the rest — and it’s also the one most likely to be abandoned, because by the time you reach it the interesting part is already done.\n\nTwo mitigations that actually work:\n\n**Run** Cross-artifact consistency analysis is another of those “optional” commands, and it’s how you catch the gap between what the spec said and what got built.`/speckit.analyze`\n\nbefore declaring anything done.**Treat an unchecked box in the final phase as blocking, not cosmetic.** If the phase that proves the work is optional, you don’t have verification — you have a nice list.\n\n## Structural things worth designing around\n\nA few sharper edges I hit, all of which generalize past spec-kit to any spec-driven setup:\n\n**Don’t bind artifacts to branch names.** Any convention that resolves “the spec for the current work” from the branch name breaks the moment a branch gets renamed, or an umbrella/integration branch exists. The failure mode is the bad part: a gate that can’t find its config tends to *silently pass* rather than loudly fail. Resolve from an explicit marker in the repo, and make “no spec found” an error rather than a default-allow.\n\n**Approval gates should check specificity, not existence.** A gate that greps for “is anything approved?” green-lights *everything* the moment one thing is approved. Approvals need to bind to the specific artifact and version they approved, or they decay into ceremony that costs time and buys nothing.\n\n**Shared, auto-generated files are merge magnets.** If a workflow appends to one shared file on every planning run, that file conflicts on every merge between parallel workstreams — always additively, always tediously. The structural fix is one file per feature, aggregated on read, rather than every branch rewriting a common file. (I tried solving it with a union merge driver first. That just produces duplicated headers — treating the symptom.)\n\n**Namespace your task IDs.** If every feature’s tasks start at `T001`\n\n, then “T013” is ambiguous the second you have two features in flight.\n\n## When it’s worth it, and when it isn’t\n\nBe honest about the overhead: this loop is worth it when the work is genuinely uncertain — new domain, real design decisions to make, several slices to coordinate. For well-understood work, it’s ceremony. Adding `constitution → specify → clarify → plan → tasks`\n\nto a task you could describe in one sentence is how spec-driven development gets a bad reputation.\n\nAnd the valuable output isn’t the plan. Plans go stale, usually fast. The value is:\n\n- The ambiguities forced into the open\n**before** any code got written. - The written record of\n**why** each decision went the way it did.\n\nBoth of those got *more* valuable with agents in the loop, not less — because the implementation step got dramatically cheaper, and deciding what to build didn’t get any cheaper at all. When writing the code is the expensive part, spending a day on specs feels like overhead. When an agent writes the code in twenty minutes, the spec *is* the work.\n\nWhich is the real reason to run the optional step. `clarify`\n\nis where you do the only part of the job that hasn’t been automated yet.", "url": "https://wpnews.pro/news/the-most-valuable-spec-kit-command-is-the-optional-one", "canonical_source": "https://victorvelazquez.dev/blog/the-most-valuable-spec-kit-command-is-the-optional-one/", "published_at": "2026-07-24 00:00:00+00:00", "updated_at": "2026-07-24 19:58:33.692771+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "ai-agents"], "entities": ["GitHub", "spec-kit"], "alternates": {"html": "https://wpnews.pro/news/the-most-valuable-spec-kit-command-is-the-optional-one", "markdown": "https://wpnews.pro/news/the-most-valuable-spec-kit-command-is-the-optional-one.md", "text": "https://wpnews.pro/news/the-most-valuable-spec-kit-command-is-the-optional-one.txt", "jsonld": "https://wpnews.pro/news/the-most-valuable-spec-kit-command-is-the-optional-one.jsonld"}}