From Ambiguous Requirements to Buildable Software

Complex software rarely begins with a complex specification. It usually begins with a sentence that sounds deceptively simple: “Customers should be able to approve this request,” “Managers need access to the report,” or “The service must validate the cheque before registration.”

Each sentence appears actionable. None is ready to build.

Between business language and working software sits a field of missing decisions: who qualifies as a customer, which manager is in scope, what “approve” changes, which system owns the truth, what happens when another service is unavailable, and whether an apparently exceptional case is actually part of the normal lifecycle.

The job of systems analysis is not to make the document longer. It is to make those decisions visible early enough that they do not become accidental code.

A requirement becomes buildable when the team can explain its actors, rules, states, boundaries, data, exceptions, and proof of completion without inventing policy during implementation.

Why ambiguity survives ordinary requirement documents

Ambiguity is not simply a writing problem. It survives because different groups use the same words to describe different mental models.

A product owner may describe an outcome. An operations team may think in procedures. A compliance specialist may think in obligations and prohibitions. A developer may look for inputs, outputs, states, and failure modes. A support team may care most about recovery. Everyone can agree with the sentence while disagreeing about the system.

That is why collecting statements is not enough. The analyst has to reconstruct the model behind them.

Three warning signs appear repeatedly:

• Nouns without definitions. Words such as user, account, organization, request, and status hide multiple business concepts.
• Verbs without state changes. Approve, activate, verify, and cancel sound clear until we ask what becomes true afterward.
• Rules without ownership. A rule may exist in policy, an upstream platform, an API gateway, a service, or an interface. If ownership is unclear, enforcement drifts.

Start with the system around the request

Before writing user stories or endpoint specifications, I begin with the system around the problem. The goal is to establish a shared frame in which detailed questions have a place.

Identify actors and responsibilities

An actor is not only a job title. It is any person, organization, system, or automated process that makes a decision, supplies information, changes state, or receives an outcome.

For each actor, ask:

1. What can this actor initiate?
2. What information can it see or change?
3. Which decisions belong to it?
4. In what organizational or transactional context does it act?
5. What happens when it cannot complete its responsibility?

This separates business responsibility from interface placement. A button is not an actor, and hiding a button is not an authorization model.

Draw the boundary before the flow

Teams often draw a happy-path sequence before agreeing on the system boundary. That makes the diagram look precise while ownership remains unresolved.

First establish which capabilities belong inside the product, which belong to external services, and which are manual or organizational. Mark sources of truth, integration contracts, and responsibilities that cannot be delegated. Only then draw the flow.

The boundary reveals where assumptions cross teams. It also prevents a familiar failure: specifying the behavior of another system as if the current team controlled it.

Translate statements into explicit models

No single artifact can represent a complex system completely. I use several small, connected views, each answering a different kind of question.

View	Question it answers	Typical output
Context	Who and what surrounds the capability?	Actors, systems, boundaries
Process	In what order does work happen?	BPMN or activity flow
Domain	Which concepts and responsibilities matter?	Domain model and glossary
State	What may change, and under which conditions?	State machine or lifecycle
Interaction	How do components collaborate?	Sequence or service flow
Data	What must persist and remain consistent?	ERD and data rules
Decision	How do conditions produce outcomes?	Decision table or rule matrix

The value comes from agreement between the views. If the process permits a transition the state model forbids, the contradiction is useful evidence. If a sequence needs data that the domain model does not own, a decision is missing. Models are not decoration; they are instruments for finding disagreement.

Make business rules testable

A business rule should be more precise than “the system validates the request.” A buildable rule identifies the subject, condition, decision, consequence, and reason.

Consider the difference:

Vague: A manager can approve requests for their organization.

Buildable: An active user assigned the Request Approver system role may approve a pending request when the request’s organization is within the user’s active organizational scope and the user did not submit the request. Approval records the decision time, acting scope, and policy version, then moves the request to Approved.

The second statement exposes several models: identity, role assignment, organizational scope, separation of duties, audit evidence, policy versioning, and state transition. It also creates meaningful test cases.

For rules with several conditions, decision tables are often clearer than prose. They make combinations visible, especially the combinations stakeholders forgot to discuss.

Treat exceptions as part of the design

An exception is not merely an error message. It can change responsibility, state, timing, and recovery.

Ask about four families of failure:

• Business rejection: the request is understood but violates a rule.
• Technical failure: the system cannot complete an operation.
• Dependency uncertainty: an external system times out or returns an ambiguous result.
• Human interruption: a task is abandoned, reassigned, corrected, or resumed later.

For each one, define what the user sees, what the system records, whether retry is safe, who owns recovery, and which state remains authoritative. This is particularly important in integration-heavy environments, where “try again” can create duplicate or contradictory outcomes.

Connect requirements to implementation evidence

The final step is traceability—not a giant spreadsheet that no one maintains, but a visible chain from intent to proof.

A useful chain looks like this:

Business objective → capability → rule → model → service behavior → acceptance condition

Each link should answer a practical question. Why does this endpoint exist? Which policy justifies this validation? Which lifecycle transition does this event represent? Which acceptance condition proves the requirement is satisfied?

This is the same reasoning applied in my Digital Identity Systems case study: shared process, domain, data, and service models give business and engineering teams a common definition of the product.

A compact readiness check

Before a capability enters implementation, I look for evidence that the team can answer the following:

• Are the actors and their responsibilities explicit?
• Is the system boundary agreed?
• Are key terms defined in one shared language?
• Are lifecycle states and transitions modeled?
• Can every important rule be evaluated from known data?
• Are authorization and organizational scope part of the model?
• Are external dependencies and uncertain outcomes handled?
• Are exceptions, retries, and recovery responsibilities defined?
• Can acceptance conditions be traced back to business intent?
• Do engineering, operations, support, and business stakeholders recognize the same system?

Not every project needs every possible diagram. It does need enough connected evidence to remove policy-making from the coding phase.

Clarity is an implementation capability

Good systems analysis does not eliminate complexity. It gives complexity a structure that people can inspect, challenge, and build.

When the model is coherent, developers spend less time reverse-engineering intent. Product and business teams can see where decisions are still open. Testers can derive meaningful scenarios. Operations and support can recognize failure states before production. Architecture becomes connected to behavior rather than discussed as a separate layer.

That is the real transition from an ambiguous requirement to buildable software: not more documentation, but fewer invisible decisions.