Skip to content
BSWEN
Blog

Why Getting Detailed Specifications from Clients Is So Difficult

Cowrie
Cowrie
Dev @ Bswen

The Problem

I was browsing Reddit recently and found a thread that hit home. A developer asked about getting detailed specs from clients, and the top comment (393 points) said:

“Getting a detailed spec from the client is the hardest work I do. But somehow everybody thinks the hard part is writing business code.”

Another developer chimed in with frustrated humor:

“A detailed and precise spec? Whose dick do I have to suck to get one of those?”

I’ve been there. A client says “users should be able to upload files to share with their team.” Sounds simple, right? Then I start building and realize:

  • What file types?
  • What size limit?
  • Where do files go?
  • Who can see them?
  • What about viruses?
  • What if the team is deleted?

The client gave me a vague overview, not a spec. This is the gap that kills projects.

The Illusion of Clarity

Clients believe they know what they want. They can visualize the end result—the happy path where everything goes right. But visualization isn’t specification.

I see this pattern constantly:

Client says:     "Make it fast"
Developer hears: "Optimize for performance"
Reality:         Client meant "load in under 3 seconds on mobile"
                  But never specified the metric, the device, or the network

The client’s mental model has gaps they’ve never noticed. They haven’t considered:

  • What happens when a user enters invalid data?
  • How should the system handle concurrent access?
  • What are the edge cases for permissions?
  • How should errors be communicated?

The Gap Between Request and Spec

Let me show you the real gap. Here’s what a client actually said to me:

"Users should be able to upload files to share with their team."

And here’s what I needed to build this feature:

file-upload-spec.yaml
File Upload Specification:
  accepted_formats:
    - pdf
    - docx
    - xlsx
    - png
    - jpg
  max_file_size: 10MB
  storage_location: S3 bucket with team-specific prefix
  permissions:
    - uploader: full access (read, delete, share)
    - team_members: read, download
    - non_team_members: no access (unless explicitly shared)
  virus_scanning: required before storage
  duplicate_handling: reject with error message
  quota_per_team: 50GB
  audit_logging: required (who, when, what file)
  retention_policy:
    - active_teams: indefinite
    - deleted_teams: 30 days, then purge

One sentence from the client. Fourteen decisions I had to make.

Why This Happens

1. Specification Requires Technical Thinking

To write a truly detailed specification, you need to think like an engineer:

Client thinking:     "I want users to upload files"
Engineer thinking:   "What's the state machine for file upload?
                     What validations? What error handling?
                     What performance constraints? Security?"

Clients hire developers precisely because they lack this technical thinking capability. Expecting them to produce detailed specs is asking them to do the job they’re paying someone else to do.

2. Discovery Costs Are Hidden

The effort to extract requirements is investigative work:

Visible work:        Coding, testing, deploying
Hidden work:         Probing questions, domain translation,
                     assumption surfacing, stakeholder reconciliation

I’ve learned to budget 30 minutes of requirements clarification for every hour of coding. Most project plans assume zero.

3. Communication Asymmetry

Clients speak business value. Developers speak data structures. This translation layer is where specs break down:

Client says:         "Make it user-friendly"
Developer needs:     Specific UX patterns, interaction flows,
                     accessibility requirements, mobile breakpoints

The gap isn’t a failure of communication—it’s a fundamental mismatch in mental models.

How I Handle This Now

Technique 1: Specification by Decision Table

Instead of open-ended questions, I force specificity with tables:

User Registration Decision Table
+------------------+-------------+---------------+-------+-----------+
| Input Validation | Valid Email | Invalid Email | Empty | Duplicate |
+------------------+-------------+---------------+-------+-----------+
| Valid Password   | Create user | Error 400     | Error | Error 409 |
| Weak Password    | Error 400   | Error 400     | Error | Error 400 |
| Empty Password   | Error 400   | Error 400     | Error | Error 400 |
+------------------+-------------+---------------+-------+-----------+

I hand this to clients and ask: “What should happen in each cell?”

Gaps become obvious. They fill in blanks they didn’t know existed.

Technique 2: Prototype Reviews

Clients can’t describe what they want, but they can identify what’s wrong. I’ve learned to build something—anything—early.

Wrong approach:    "Describe the user interface"
Better approach:   "Here's a mockup. Tell me what's wrong."

Their feedback on what’s wrong is 10x more specific than their description of what’s right.

Technique 3: Document the Undecided

When clients can’t provide specifics, I make the gap visible:

open-questions.md
## Open Questions (Defaults Applied)


- [ ] Error handling for invalid inputs
      Default: Return 400 with generic error message
- [ ] Maximum file upload size
      Default: 10MB
- [ ] Session timeout duration
      Default: 30 minutes of inactivity
- [ ] Concurrent edit conflict resolution
      Default: Last write wins

This does two things: it keeps the project moving, and it surfaces decisions the client hasn’t made.

Technique 4: Budget for Discovery

I stopped treating specification as a pre-development phase. Requirements gathering IS development work.

Old approach:      Phase 1: Requirements (1 week)
                   Phase 2: Development (4 weeks)
                   Phase 3: Testing (1 week)


Reality:           Requirements are discovered throughout.
                   Every sprint surfaces new questions.
                   Every demo reveals misunderstandings.

Now I build requirements discovery into every sprint. Not as a separate phase, but as an ongoing activity.

Common Misconceptions

Misconception 1: “If clients just thought harder, they could give better specs.”

No. Clients have optimized their thinking for their domain. Asking them to think like engineers is asking them to do your job.

Misconception 2: “Agile means we don’t need specifications.”

Agile means we acknowledge specs evolve. It doesn’t mean we don’t need clarity. You still need enough detail to build something useful.

Misconception 3: “AI will solve this by extracting requirements.”

AI can organize and document requirements, but it can’t make decisions clients haven’t made. The human decision-making bottleneck remains.

Misconception 4: “Detailed specs upfront will prevent problems.”

Over-specification has its own problems. You can build the wrong thing perfectly. Balance detail with flexibility.

The Real Value

Here’s what I’ve realized: the gap between what clients think they want and what they actually need is where developers provide value.

Client's mental model → [GAP: Engineer's expertise] → Working system

This gap is where technical expertise meets domain knowledge. This is where engineering thinking clarifies business intent.

The Reddit comment was right: getting a detailed spec IS the hardest work. Not because clients are difficult, but because the intellectual heavy lifting happens before a single line of code is written.

What Changed for Me

I used to get frustrated with vague requirements. Now I expect them. I’ve built processes to extract clarity:

  1. Budget time for discovery: 30 minutes of clarification per hour of coding
  2. Use structured techniques: Decision tables, state diagrams, prototypes
  3. Iterate on requirements: Build walking skeletons early, surface questions
  4. Make ambiguity visible: Document defaults and open questions
  5. Stay engaged: The client’s job isn’t done when they hand off requirements

The best developers I know aren’t just better at writing code—they’re better at bridging this gap. They ask the right questions, surface hidden assumptions, and translate business needs into technical reality.

This is the real “hard work” that no methodology can eliminate.

In this post, I explained why getting detailed specifications from clients is inherently difficult—not because of client failure, but because specification requires technical thinking that clients hire developers to provide. The key insight is that requirements gathering is development work, not pre-development work.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: