Over the years I've read / written hundreds of feature specifications. Some were brilliant; most were bloody awful. The difference between a good spec and a bad one isn't about length or formality; it's about whether it actually helps developers build the right thing without driving them mad in the process.
Here's something I learned at Microsoft that changed how I think about specs: A spec is not a bible; it's a tool. Like any tool, you use it to get a job done. You add as much detail as you, the stakeholders, and the developers need to get going. Then you adapt it, change it, and update it as the feature develops.
Treat a spec as a sacred, unchangeable document and you're building the wrong thing perfectly ('running very very fast in the wrong direction'). Treat it as a living tool and you're building something that actually solves problems.
This agile approach to specs creates a particular challenge: if the feature can evolve as you learn, how the hell do you estimate it? How do you know when you're done? That's what this article is about.
In general a principle I've lived by in my career; ALL process whether it be specs / filling in reports / even code reviews etc... are a tax. Like all tax it needs to deliver value for money in terms of a better result than it would be without it or it needs to go. If your process says you need to have a strict story point system and burn down graphs but no bugger uses them for anything but harassing your team???
Fundamentally; a Feature Spec is a conversational tool to make the feature better NOT a dogmatic, unchanging LAW.
Agile isn’t stand-ups and sticky notes. It’s an economic strategy for building the right thing under uncertainty. Specs live inside that uncertainty, so they have to be agile too. Read the Agile Manifesto, let it become how you think about building ANYTHING. Think of it as a design pattern for product development. It's not a process; it's a mindset.
Every loop shortens the distance between “idea” and “useful”:
Update the spec after each loop. The change log is the story of what you learned.
The single most important principle for writing specs: Always start with the problem, not the solution.
This pattern is simple:
I've seen countless specs that jump straight into "User clicks button X which calls API Y" without ever explaining what the user is actually trying to achieve. This is arse-backwards. The implementation details should flow naturally from understanding the problem.
Remember developers are feature building machines REALLY (code is the tool to deliver features); tell them what needs doing NOT how to do it. if you have a UX person who's responsible for the UX spec then the dev and them should work together. The point is making the best feature for the user that can change and anyone is empowered to push for the change (in the spec) and have that review process test the idea.
flowchart TD
A[Feature Idea] --> B[Spec / Proposal]
B --> C[Visuals: Flowcharts, Figma, UI Mockups]
C --> D[Implementation]
D --> E[Internal Testing]
E --> F[Feedback Loop]
F -->|Refine| B
F -->|Ship| G[Release to Users]
G --> H[User Feedback]
H -->|Iterate| B
Before you write a single word about implementation, you need to answer one question: WHY?
Why are we building this? What problem does it solve? Who benefits? If you can't answer these questions clearly, you haven't got a feature; you've got a wish list.
A good spec starts with:
This is where most specs go tits-up. Too vague and developers are left guessing; too detailed and you're micromanaging implementation choices that developers are better qualified to make.
The trick is to specify WHAT needs to happen without prescribing HOW it happens. For example:
Good: "When a user attempts to submit a form with invalid data, they should receive immediate feedback indicating which fields need correction."
Bad: "On form submission, the submit button's onClick handler should call validateForm() which iterates through formFields array checking each field.value against its validation.regex property and if any fail should call showError() with the field.name and validation.message parameters."
The first tells me what the user experience should be; I can implement it in React, Vue, vanilla JavaScript, or carrier pigeon for all it matters. The second assumes implementation details that might be completely wrong for the tech stack or introduce unnecessary constraints. Different people have different strengths often the person writing the spec isn't technical / isn't the one writing the code. Imagine being a cab driver and not being told the destination but every gear change, mirror look etc..etc..makes you all stabby.
Remember you're trying to get people to understand what you're suggesting. Some teams include Figma documents (a storyboard / ux 'spec') or images of the UI the designer built. Like everything else though these are 'until we try it' suggestions until they've been through a feedback loop. It's all about ensuring you're being understood. Use whatever tools you need.
In a Wiki mermaid.js diagrams are GREAT for this! ; remember AI is GREAT at generating these too given a textual description.
Some people can parse written descriptions, some need pictures and movies!
flowchart LR
A[User on Profile Page] --> B[Click 'Add Profile Picture']
B --> C[Upload Dialog Opens]
C --> D[Select Image File]
D --> E[Preview + Crop Options]
E --> F{User Confirms?}
F -->|Yes| G[Profile Updated with New Picture]
F -->|No| C
G --> H[User Sees Updated Profile]
If there's one thing I've learned it's this: Users will find ways to break your shit that you never imagined.
A good spec doesn't just describe the happy path; it considers:
You don't need to solve all these in the spec, but you need to acknowledge they exist. Nothing irritates developers more than discovering halfway through implementation that nobody thought about what happens when the external API is down.
For MANY it's likely they're out of scope for THIS spec. You may have 'technical specs' which DO detail the implementation details and technical solutions to 'technical issues'
These shouldn't be afterthoughts shoehorned in during code review. If there are specific security requirements (authentication levels, data encryption, audit logging) spell them out in the spec.
Similarly, if there are performance constraints that matter ("This search needs to complete in under 200ms for datasets of up to 1 million records"), put them in the spec. Don't leave developers to guess at non-functional requirements.
Here's the template I use for feature specs. It's not gospel, but it's served me well:
A paragraph or two summarising what we're building and why it matters. Your CEO should be able to read just this section and understand the value.
What's the current state of affairs? What prompted this feature? What have users been asking for? What would help us make more money? This helps developers understand the problem space without having been in every product meeting.
Got it—let’s expand your section on User Stories with personas woven in, so it’s not just a checklist but a living map of how different kinds of users interact with the system.
User stories aren’t just a box-ticking exercise—they’re a way to embody real people and their goals. You know, your users the whole point of building this shit. By anchoring each story to a persona, you force yourself to think about actual usage patterns, motivations, and constraints. The format is simple but powerful:
In the end personas are a greeat way of identifying HOW your software can serve different TYPES of users. Maybe Alex needs a dashboard to view security issues in your feature, maybe Morgan needs his permissions restricted to stop him breaking shit etc.
As a [persona / type of user] I want [to do something] So that [I achieve some goal].
The “so that” clause is the safeguard against building features nobody needs—it ties every function back to a real-world outcome.
| Persona | Story | Why it matters |
|---|---|---|
| Alex (Administrator) | As an Administrator, I want to assign roles and permissions so that I can ensure data security and compliance. | Prevents unauthorized access and keeps the system trustworthy. |
| Jamie (Casual User) | As a Casual User, I want a simple dashboard so that I can quickly see the most important information without being overwhelmed. | Reduces friction and increases adoption. |
| Priya (Power User) | As a Power User, I want to create custom workflows so that I can automate repetitive tasks and save time. | Unlocks efficiency and advanced use cases. |
| Morgan (Newcomer) | As a Newcomer, I want guided tutorials and tooltips so that I can learn the system without feeling lost. | Improves onboarding and retention. |
| Taylor (Stakeholder) | As a Stakeholder, I want regular reports emailed to me so that I can track progress without logging in. | Keeps decision-makers informed and engaged. |
This is your meat and potatoes. Break it down by functional area. Use subheadings liberally. Include mockups or wireframes if you have them; a picture is worth a thousand words of description.
For each requirement, specify:
Performance targets, security requirements, accessibility standards, browser/device support. Don't assume these are obvious. But in some teams these may be WHOLE OTHER TEAMS...but don't lose focus. If one part of your cycle becomes a waterfall then you've lost agility by definition.
This section is just as important as what's IN scope. Be explicit about what you're NOT doing in THIS spec.
Why this matters:
Examples of good Out of Scope items:
If someone argues an out-of-scope item should be in scope, that's a conversation worth having BEFORE development starts, not halfway through implementation.
Be honest about what you don't know. Mark these clearly and make sure they get answered before development starts. Nothing worse than blocking development because nobody decided whether we're doing soft deletes or hard deletes.
What other systems/teams/features does this rely on? What needs to be ready before development can start?
How will QA test this? These should be concrete, testable statements. Bonus points if they're written in a format that could become automated tests (Given/When/Then style).
Here's something that doesn't get talked about enough: Specs can have bugs too.
A spec bug is when the specification itself is wrong. Maybe it contradicts itself, or it specifies behaviour that's technically impossible, or it solves the wrong problem entirely. These are insidious because developers might implement exactly what's written and still end up with a product that doesn't work properly (in Agile the main focus is making this 'feedback loop' as short as possible for exactly this reason).
When you find a spec bug as a developer, you have a few options:
This is almost always the right answer. As soon as you spot something that doesn't make sense, raise it. Don't wait until you're halfway through implementation.
Send a clear message to whoever owns the spec:
Do this in writing (email, ticket, whatever) so there's a record.
Sometimes you might be tempted to just build what's specified even though you know it's wrong. DON'T DO THIS.
I've seen developers implement specs they knew were wrong because "that's what it said to do" and then act surprised when QA rejects it or users complain. You're a professional; part of your job is to speak up when you see problems.
The exception is if you've raised the issue, been told to proceed anyway, and got that in writing. Then fine; you've done your due diligence.
If you're confident you know what the spec should say, you might be tempted to just correct it yourself. This is fine for obvious typos or formatting issues, but for substantive changes you need to get agreement from stakeholders.
Never silently change requirements. That's how you end up building features nobody asked for.
The best approach is to prevent spec bugs in the first place:
Some people think more detail is always better. It's not. A 50-page spec that nobody reads is worse than a 5-page spec that everyone understands.
If your spec is turning into War and Peace, you either:
The opposite problem: "Build a reporting system." Right, cheers for that. I'll just knock up something and we'll see if it matches what you had in your head, shall we?
If your spec can be fully captured in a single sentence, it's not a spec; it's a vague wish.
"We need a dashboard" isn't a requirement; it's a preconceived solution. Maybe you do need a dashboard, but maybe you need something completely different. Start with the problem. "Bob the system admin can't see when there's issues in the system quickly and easily"
Requirements that change daily aren't requirements; they're chaos. If things are changing that fast, you don't understand the problem well enough yet. Stop and do more discovery before writing specs.
"While we're in there, could we also..." No. No we couldn't. Every feature has a cost. If you want to add something new, write a separate spec for it and prioritise it properly.
This is the mindset shift that changed how I write specs: Treat your spec exactly like you treat source code.
Your specs should live in version control alongside your code. Check them in. Track changes. Write meaningful commit messages when you update them. This creates a history of how requirements evolved.
At Microsoft, we kept specs in the same repositories as code. When a spec changed, it went through the same review process as code. This wasn't bureaucracy; it was ensuring everyone understood what was changing and why. Even revision tracking in Word is better than nothing (you can have a 'revisions' section but don't let this get out of control; TOO MANY revisions after dev starts means the spec wasn't cooked when you started building).
Just as code needs refactoring, so do specs. As you learn more during implementation, the spec should evolve to reflect that learning.
Found a better way to solve the problem? Update the spec to reflect the new approach and explain why you changed direction. Discovered an edge case you hadn't considered? Add it to the spec.
The spec after development should be more refined than the spec before development. If it's not, you've missed an opportunity to document what you learned.
A spec isn't "done" when development starts, it's just 'ready' for that stage . It's done when the feature ships and becomes maintenance mode. Until then, it's a living document that evolves with your understanding of the problem.
This doesn't mean the spec should change daily. Major changes to requirements need discussion and agreement. But clarifications, additional examples, newly discovered edge cases should all be folded back into the spec as you find them.
Think of it this way: if you wouldn't leave outdated comments in code, don't leave outdated information in specs.
Here's something that doesn't get discussed enough: your spec becomes the foundation for everything that comes after.
Test Plans: QA writes test cases based on the spec. If the spec is outdated, tests are testing the wrong thing. You get false positives (tests pass but feature is broken) or false negatives (tests fail but feature works fine).
Documentation: User documentation, API docs, help systems, your fancy RAG AI support agent - they all start from the spec. If the spec describes features that don't exist or misses features that do, your docs are wrong from day one.
Future Development: When someone needs to extend the feature six months later, they'll read the spec to understand how it works. If it doesn't match reality, they're starting with incorrect assumptions.
Onboarding: New team members learn the system partly by reading specs. Outdated specs teach them the wrong mental model of how features work.
This is why the spec must stay current. It's not just about the initial implementation; it's foundational to everything else.
At Microsoft, we treated spec updates with the same importance as code updates. Spec changes went through review. They were versioned alongside code. When a feature changed, updating the spec wasn't optional; it was part of the definition of "done."
If you change the code but don't update the spec, you've created TECHNICAL DEBT. Future work will be slower because nobody knows what the current state actually is.
Here's something junior developers often don't grasp: The spec is not the source of truth; the code is.
The spec tells you what you're trying to build. The code is what you actually built. These two things should align, but when they don't, the code wins. You can't run a spec; you can run code (BDD not withstanding...future topic!).
This means:
Different people need different things from specs:
Executives - Want to know the business value and rough timeline. Give them the overview and success criteria.
Product Managers - Need to understand how it fits into the broader product strategy and roadmap. Give them the user stories and dependencies.
Developers - Need enough detail to implement correctly without being told how to do their job. Give them the requirements, edge cases, and non-functional requirements.
QA - Need to know how to verify it works. Give them the acceptance criteria.
Designers - Need to know what the user experience should be. Give them the user stories and interaction flows. Even better have them develop a UX spec / storyboards in parallel while working with the dev & spec writer; be that PM, BA etc. Who writes the spec is less important than it making the end feature BETTER.
A good spec serves all these audiences without being bloated. Use sections and structure so people can read what matters to them.
Before you call a spec done, ask yourself:
"But we're agile! We don't need specs!" I hear this a lot. It's nonsense.
Agile doesn't mean "no planning" or "no documentation." It means responding to change over following a plan. The key insight: specs are tools, not contracts. You create them with just enough detail to get started, then evolve them as you learn. My 'Agile journey' was even more extreme; as you get super good at specs even those become more Agile, you wil ladapt and improve based on what your team wants / needs.
The fundamental difference isn't format or length; it's mindset and process.
Waterfall Specs:
Agile Specs:
The waterfall approach assumes you can specify everything perfectly before writing a line of code. That's a lovely fantasy. In reality, you discover half the requirements once users actually try the feature. Plan for that, embrace it. Users are the ULTIMATE testers. They can break shit you didn't even know you'd made at a pace that seems to violate causality. Expect it, plan it, log it and fix it (and add it to a future spec / this one if you're still in the spec's 'lifespan').
In agile speccing, feedback loops are your best friend. You're constantly gathering input and updating the spec:
Developer Feedback: "The initial approach won't work because of X. I'm proposing Y instead." → Update spec to reflect new approach and why it changed. In the end you're ALWAYS the first 'user' of a feature. If it looks shit...sepc bug and get it sorted (even if you stop whatever sprint / spike etc to do it...don't wait!)
User Feedback: Try the feature with real users (even internally). "This doesn't actually solve my problem because..." → Pivot the spec based on what you learn.
Implementation Feedback: As you build, you discover edge cases, technical constraints, or better approaches. → Fold these learnings back into the spec.
QA Feedback: "The spec says X but didn't consider Y scenario." → Add the scenario to the spec.
Each of these feedback loops makes the spec better. The spec after a sprint of development should be more accurate than the spec before, because you've learned things you couldn't have known at the start.
This is why waterfall specs often fail: they skip the feedback loops. By the time you discover the spec was wrong, you've built the wrong thing and "changing the spec" means massive rework.
Big thing, feedback AS EARLY AS FEASIBLE. It's why I built LLMApi it helps you build a BIT then use fake data to get useful feedback.
Here's something that makes traditional project managers nervous: it's completely fine if the initial spec has gaps.
Mark sections as "TBD" if you don't know yet. List open questions prominently. Be explicit about what you haven't figured out yet.
This isn't sloppiness; it's honesty. You don't know everything up front. Pretending you do just means you'll write confident specifications for the wrong solution.
Start with:
Then fill in the gaps as you learn. It's far better to have an incomplete-but-honest spec than a complete-but-wrong one.
Accept this now: your spec will change during development. If it doesn't, you either got incredibly lucky or you're not learning anything.
Changes you should expect:
Each change should be:
The spec's version history becomes a record of what you learned. That's valuable documentation for future features.
The agile approach can fail if you forget one critical thing: "will change" doesn't mean "no boundaries."
Bad agile speccing:
Good agile speccing:
The spec is a living document, but it's not chaos. It evolves based on learning, not on whims.
AGILE IS NEVER DOING WHATEVER THE FUCK YOU WANT AND CALLING IT AGILE.
It's a dynamic process that has the SOLE GOAL of building the best stuff as quickly as possible. As the Agile Manifesto says as it's first principle.
"Our hi Start
The question isn't "how detailed should the spec be?" It's "what do we need to know to start building confidently?"
For some features that might be:
For others it might be:
Add detail where uncertainty exists. If everyone agrees on how something should work, you don't need to write it down in excruciating detail. If there's disagreement or confusion, that's where you need specifics.
But in the end it's 'is there enough detail to start the feedback loop'.
Don't overthink the initial spec. The purpose at the beginning is to have enough to meet your immediate needs, whether that's:
Use Templates: Have a basic template with the key sections (Problem, Solution, In Scope, Out of Scope, Done Criteria). Fill in what you know. Leave sections blank if you don't know yet. Mark them as "TBD" and move on.
A simple template might be:
# [Feature Name]
## Problem
[What's broken? What pain exists?]
## Proposed Solution
[High-level approach]
## What "Done" Looks Like
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3
## In Scope
-
-
## Out of Scope
-
-
## Open Questions
-
-
That's it. Five minutes of filling that in and you've got enough to start discussing or even building.
Using AI to Draft Specs: Tools like Claude or ChatGPT can be brilliant for getting a first draft. Feed it the problem and some context, ask it to draft a spec.
BUT - and this is critical - don't let the AI's thoroughness seduce you into adding everything.
AI loves to be comprehensive. It'll give you sections on Security Considerations, Performance Requirements, Accessibility, Internationalization, Error Handling, Logging, Monitoring, Deployment Strategy, Rollback Plans, and seventeen other things you might need... eventually.
Strip most of that out. Keep what you need NOW. The rest can be added later when you actually need it.
Think of the AI-generated spec as a menu. Pick the bits that matter for getting started. Ignore the rest. You can always come back for seconds.
The goal isn't a complete spec; it's enough spec to start working. Whether that's a quick estimate, a decision on priority, or just clarity on what you're building for yourself.
Here's what changes in agile: You don't write a spec and throw it over the wall to developers. The spec is a collaborative effort.
The best approach I've seen:
Everyone contributes to the spec. Nobody owns it exclusively. This collaborative approach catches problems early when they're cheap to fix rather than late when they're expensive.
More importantly, it means the spec reflects what's actually possible, not what someone wished for in isolation.
Here's where agile specs differ from traditional ones: the feature can evolve as you build it.
You discover that your initial approach won't work? Update the spec to reflect the new approach.
You try the feature and realise it doesn't actually solve the problem? Pivot and document why.
User feedback reveals a better solution? Incorporate it and explain the change.
This evolution is a feature, not a bug. You're responding to new information. The spec should capture that learning, not pretend you had perfect knowledge from day one.
But this creates a problem: if the feature can change, how do you estimate it? How do you know when you're done?
This is the dirty secret of agile: estimation is bloody difficult when features can evolve.
Traditional estimation assumes you know what you're building. You can break it down into tasks, estimate each task, add them up. Simple.
Agile estimation acknowledges you don't know everything up front. The feature might change as you learn. So how do you estimate?
You estimate ranges, not absolutes. Instead of "this will take 3 weeks" you say "somewhere between 2 and 5 weeks depending on what we discover."
You estimate in iterations. "We'll spend one sprint exploring this and report back on what we learned. Then we can estimate the rest more accurately."
You time-box instead of scope-boxing. "We'll spend 2 weeks on this. At the end of 2 weeks we'll have the best version we can build in that time."
But all of these approaches have one critical requirement: you need to know what "done" means. Without a clear definition of done, a feature can keep metastasising forever.
It's a common criticism of Agile compared to Waterfall approaches 'without a concrete spec there can be no good estimates'. Dunno I'd rather have a floppy estimate which leads to a good feature than a dead on one for crap.
This is where many agile specs fall apart. Everyone's excited about flexibility and iteration, but nobody wants to be the one who says "right, that's it, we're done."
Without a clear definition of done, features don't finish; they metastasise. They spread. They grow tendrils into other parts of the system. Before you know it, your "simple comment system" has morphed into a full social network with messaging, profiles, and friend requests.
I've seen specs with acceptance criteria like:
These aren't definitions of done; they're vague aspirations. What does "relevant information" mean? What's "works well"? You can iterate on these forever and never be done.
The developer needs to know: what specific thing, when implemented, means I can stop working on this feature?
Good "done" criteria are:
Bad: "Comments should be moderated" Good: "Admin users can approve, reject, or delete comments from the admin panel. Non-approved comments are not visible to regular users. Email notification sent to admin when new comment is posted."
Bad: "Search should be fast" Good: "Search returns results within 200ms for the 95th percentile of queries against a dataset of 100,000 posts. Results are ranked by relevance (full-text search score) with date as tie-breaker."
Bad: "Dashboard shows useful metrics" Good: "Dashboard displays: total page views (last 30 days), unique visitors (last 30 days), top 5 posts by views (last 7 days), and visitor breakdown by country. All metrics update once per hour."
Notice the difference? The good examples tell you exactly what needs to exist and when you can stop adding things.
Remember earlier when I said the Out of Scope section is as important as what's in scope? This is why.
For every feature, there are dozens of things you could add. The Out of Scope section explicitly calls out what you're NOT doing. This prevents the "while we're in there, we could also..." conversations that cause feature metastasis.
In Scope: Nested comments (one level of replies) Out of Scope: Unlimited comment threading, comment voting, comment threading, best comment sorting, comment permalinks (these may come later as separate features)
Now when someone suggests "shouldn't comments have upvotes?" you can point to the spec and say "that's out of scope for this iteration. Let's discuss it as a separate feature once basic comments are working."
Oh and the NEXT spec? Well you have a bunch of unused good ideas already captured! Way easier to start!
Sometimes you genuinely don't know exactly what "done" looks like when you start. The problem space is too uncertain, entirely novel or even some back end system is having to be built simultaneously. In these cases, time-boxing can work:
"We'll spend 2 weeks (or until backend is ready) prototyping different approaches to the recommendation algorithm. At the end of 2 weeks we'll evaluate what we've learned and decide whether to productionise one approach, try something different, or abandon the feature."
But notice: you still have a concrete "done" condition (2 weeks, then evaluate). You're not just building indefinitely. These explorations are often done in a context like a 'Sprint in SCRUM called a 'Spike'
A Spike is one of these 'go have a play and figure out this tech' it can last as long as a Sprint (or longer) but it typically just a few days. When I have devs do these I typically ask for a mail at the end (or a wiki post etc) with the findings, is it worth it, should we adopt it etc.
A Sprint is expected to have deliverables at the end (something someone other than the person engaged in it can test for the loop). A Spike MIGHT have but probably the only deliverable is the knowledge for the team.
They're also FUN for devs and help the team I often collect Spike ideas during a project and when there's a lull I let devs pick one to explore (USUALLY for some future dev but often just to stop Jim the junior dev KEEP GOING ON ABOUT IT).
Even with clear "done" criteria, scope can creep. You discover edge cases. You realise users need something you hadn't considered. How do you handle this without breaking your definition of done?
Document it, don't just do it. When you discover something new that needs to be added, update the spec. Make it explicit that the scope has changed. Get agreement from stakeholders.
This serves two purposes:
If your spec keeps growing, that's a signal. Either you're building the wrong thing (and need to step back and rethink), or this should be multiple features, or you need to cut scope to ship something useful sooner.
At some point, you need to ship. The feature doesn't need to be perfect; it needs to be useful.
A good test: Can users get value from this feature as it stands?
If yes, ship it. You can always iterate in the next version. Done doesn't mean "will never be improved." It means "solves the problem well enough that users benefit and we can move on to other work."
If no, you're not done yet, regardless of what your spec says.
The hardest part of agile isn't starting work; it's stopping work. Clear "done" criteria make stopping possible.
But remember that you have to weigh up whether you release it to everyone, have a close group for A/B / UAT (user acceptance testing). That's often a business decision around risk. Sometimes the public is FUCKING DUMB and sees a partially completed preview feature as the GOSPEL FOR YOUR SYSTEM QUALITY. If that's an issue a controlled group is safer.
A spec isn't done when you finish writing it; it's done when it's been reviewed by the people who'll use it.
The best practice I learned at Microsoft: spec reviews work exactly like code reviews. They're collaborative, not adversarial (though the Microsoft 'boys club' often made the spec reviews feel like gladiatorial combat if someone was a dick; hey Simon!). The goal isn't to catch you out; it's to make the spec better.
When reviewing specs:
When your spec is being reviewed:
The best spec reviews are conversations. You go back and forth. You learn from each other. The spec that emerges is better than what either person could have written alone.
Get reviews from all the perspectives that matter:
Developer Review - Will this actually work? Are there technical constraints we haven't considered? Is there enough detail to implement? What questions would you have if you were building this?
Product Review - Does this solve the right problem? Does it align with product strategy? What's missing? Does the "done" criteria actually indicate value to users?
Design Review - Does the user experience make sense? Have we considered accessibility? What about mobile? Are we solving the user's problem or just building features?
QA Review - Can we test this? Are the acceptance criteria clear enough? What about edge cases? What could go wrong?
You don't need formal sign-off from everyone. You need their input to make the spec better. Think of it as "request for comments" not "request for approval."
Good reviewers ask questions that improve the spec:
None of these are gotchas. They're genuine questions that help flesh out the spec.
You won't accept every suggestion. That's fine. But for each piece of feedback:
The spec should get better with each round of review. If it doesn't, you're not listening or your reviewers aren't engaged.
Get reviews from all these perspectives before you start implementation. Finding problems in the spec costs minutes; finding them in production costs weeks.
To make this all less abstract, here's what a spec might look like for the automatic markdown translation feature I built for this blog. This demonstrates the principles we've discussed.
Blog posts written in English only exclude non-English speaking readers. Manual translation of each post to multiple languages is time-consuming and delays publication. We need an automated solution that translates markdown blog posts to multiple target languages without requiring manual intervention for each post.
Implement a background service that automatically translates markdown files to configured target languages using the EasyNMT machine translation service. The service will:
These criteria tell us exactly when we can stop working on this feature:
Notice these are specific and testable. We can verify each one. When all are met, we're done. We don't keep adding features like "translation quality scoring" or "manual translation editing" unless we explicitly expand the scope.
Several things emerged during development that refined the spec:
Batch Size Tuning: Started with 20-line batches, but found 10 lines more reliable for staying under EasyNMT's word limit while maintaining context.
Image Detection: Initially, image filenames in markdown were being sent to the translation service, breaking sentence parsing. Added file extension detection to skip image paths.
Service Availability: EasyNMT can be temperamental on startup. Added health check that queries the /model_name endpoint before attempting translations.
Hash Storage: Originally planned database storage for file hashes, but filesystem-based .hash files proved simpler and avoided database dependency for this service.
These learnings were folded back into documentation and informed similar features later.
This spec followed the principles discussed:
The result: a feature that's been running in production for months, automatically translating every blog post with minimal intervention.
Based on what we've covered, here are questions that come up frequently:
It depends on "small." If it's truly trivial (changing button text, fixing a typo), no. But if you need to:
Then yes, even a quick spec helps. It doesn't need to be formal. A few bullet points in a ticket covering Problem, Solution, and Done criteria is often enough.
The test: if you can't explain what "done" looks like in two sentences, you need a spec.
Point to the Out of Scope section. Explain that:
If they insist everything is equally critical, suggest they choose which other work to delay instead. That usually clarifies priorities quickly.
That's fine, as long as:
If the spec is unrecognizable because you completely misunderstood the problem initially, that's a sign to do more discovery before starting next time. But iteration and learning are expected.
The spec's version history should tell the story of what you learned.
In Startups this is called a 'Pivot' where you start buildign a game and end up building an amazing messaging system instead..you haven't heard of mobile game Glitch, you likely HAVE heard of the messaging bit; 'Slack'.
Don't get too locked in. If there's opportunities by pivoting TAKE THEM.
For critical bugs: no, just fix them.
For complex bugs that affect multiple systems or require architectural changes: yes. Treat it like a feature. What's broken (problem), how you'll fix it (solution), how you'll know it's fixed (done criteria), what you're not changing (out of scope).
For everything in between: use your judgement. If the fix isn't obvious or might have side effects, a quick spec helps.
This is ESPECIALLY true for security bugs. You need to know EXACTLY what you're fixing and how you'll verify it & share the fixes WIDELY.
As formal as your team needs. Some teams are fine with detailed JIRA tickets. Others want proper documents in version control.
The formality matters less than the content:
You can write that in Markdown, Confluence, Word, or scrawled on a napkin. The format doesn't matter; the thinking does.
This is the often unmentioned KEY to Agile development; and why I hate Agile Frameworks (and SCRUM). The WHOLE POINT is that like an agile spec your process needs to be adaptive too. If writing a little doesn't work for one team but a lot does, do that. If no docs works for a tiny team but full docs work for a big one, do that. If 5 day cycles work for one team but 2 week sprints for another, do that. The WHOLE IDEA is to make the best product; your team is the machine MAKING that product. Make the machine work as smoothly as possible.
As a manager look at what your outputs are; if the board needs a burn down graph then how can YOU use the current data to build one. If you have to use the risible 'story points' does THAT get the data you need?
In the end you team outputs features AND what stakeholders need. If YOU can reduce the impact on the team then that's YOUR PART.
You still need specs, maybe more so. In six months when you need to extend this feature, you won't remember why you made certain decisions. The spec is your past self talking to your future self.
Plus you still need to:
Writing specs for yourself is like writing unit tests: it feels slower now but saves time later (like me, I'm in my 50s, I FORGET SHIT nowadays, write it down so it gets done, even if it's only a github issues list).
Call it out. When someone says "Oh, I forgot to mention it should also do X," that's not clarification; it's new scope.
Response: "That's a good requirement, but it's not what we agreed in the spec. Let's add it to the Out of Scope section for now and discuss whether to include it or save it for version 2."
If it really is a requirement (not a nice-to-have), then:
Never silently absorb scope creep. It'll destroy your estimates and credibility.
Yes, if you're prototyping to answer open questions. No, if you're building for production.
Prototyping to learn is good: "We have three approaches. Let me spike each one to see which works best." That informs the spec.
Building production code before the spec is ready means you're guessing at requirements. You'll probably build the wrong thing.
Exception: if you're the product owner and developer (solo project), you can spec and code simultaneously. But still document your decisions as you go.
The 'until the spec is ready' is a GREAT way to get the devs charged up to begin. Evaluating technology approaches, writing common boilerplate etc.
Find out why:
If people skip spec reviews and then build the wrong thing, make the pain visible. "This wasn't in the spec, so we'll need to rework it" is a lesson learned.
Also: make specs easy to find. If they're buried in some obscure wiki, nobody will read them.
Rule of thumb: 5-10% of development time.
For a 2-week feature: 1-2 days on the spec. For a 1-week feature: half a day on the spec. For a 2-day feature: an hour or two on the spec.
But don't be religious about it. Some features need more up-front thinking. Others are obvious and the spec takes 20 minutes.
If you're spending more time on the spec than on implementation, you're overthinking it. Remember: specs are tools to help you work, not artworks.
Because software estimation is fundamentally difficult. Here's the uncomfortable truth: estimates only work if you've done EXACTLY that task before, in that environment, with those tools, with unchanging requirements.
Which almost never happens.
Every time you estimate, you're dealing with:
This is why:
The more novel the work, the worse your estimates. Building the same CRUD form you've built 50 times? You'll be close. Integrating with a new service using an unfamiliar protocol? Your estimate is a guess wrapped in hope.
This is why specs need clear "done" criteria. You can't estimate accurately, but you can define when to stop. That's more valuable.
These need different "done" criteria. Instead of "feature X works," it's "we've answered question Y."
Example spec for exploration:
Time-boxing is critical for exploration. Without it, research tasks never end.
Start with what you know:
Mark sections as "TBD." Be honest about uncertainty.
Then use the spec review process to fill gaps. The conversations during review often clarify what you didn't understand.
Remember: incomplete-but-honest beats complete-but-wrong.
Absolutely. The spec doesn't need to be a separate document. A well-written GitHub issue or JIRA ticket can serve as the spec perfectly well.
What matters is the content, not the container. A good issue-as-spec should have:
The advantages of using issues:
Tips for using issues as specs:
The test: could someone read the issue and know what to build, what "done" means, and what's out of scope? If yes, it's a good spec regardless of format.
If you're in healthcare, finance, aerospace, or other regulated fields, you might need more formal specs for compliance. The principles still apply:
But you'll also need to:
Even in regulated environments, agile speccing works. You just have more hoops to jump through. The spec is still a tool; it's just a tool that needs to satisfy regulators as well as developers.
Writing good feature specs in an agile environment is a skill that improves with practice. The goal isn't to write perfect specs up front (they don't exist); it's to write specs that help your team get started and evolve as you learn.
The key principles:
The hardest part isn't writing the initial spec. It's knowing when to stop working on a feature. Without clear "done" criteria, features grow forever and never ship.
This is why agile estimation is so difficult. You're not just estimating implementation time; you're estimating learning time. How long will it take to discover what actually solves the problem? Nobody knows, because you haven't discovered it yet.
The best you can do: be clear about what "done" means, time-box uncertainty, and update the spec as you learn. Treat it like code: version it, refactor it, improve it.
A good spec empowers developers to solve problems intelligently while knowing exactly when they can stop. It's a conversation starter, not a straitjacket.
And if you're a developer reading a spec that doesn't make sense or has no clear "done" criteria: speak up. It's not being difficult; it's being professional. Better to sort it now than to build a feature that keeps growing until it takes over the entire application.
© 2025 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.