Chapter 11: Requirements Analysis: From Vague to Precise

Adapted public course. Concepts, procedures and examples are adapted from the internal textbook. Case sizes, timings, improvement figures and target thresholds are illustrative, not site delivery results or universal standards. Verify tools, platforms and skills in your environment. Prompts do not grant permissions and retry counts do not authorize recovery. Preserve work and verify targets, sharing and external-state effects first.

Lesson explanation

11.1 Why Requirements Analysis Comes First (Changing Requirements During Coding Costs Far More Than During Analysis)

You are building an equipment lending management system. The product manager tosses you a one-liner: “Build a borrowing request feature.” You open your AI tool, repeat that sentence. The AI spends 30 seconds generating a plan with 5 data tables and 12 API endpoints. You look at this plan and feel something is off — but you cannot articulate it. You let it proceed with coding.

Two weeks later, the feature is done. You demo it to the business department. They take one look and say: “Wrong. Our workflow is not like this.”

You then realize the AI’s default workflow was “request -> approval -> warehouse dispatch -> return,” but your company’s actual workflow is “request -> check out for use -> use -> return -> inspection.” Moreover, “checking out for use” and “warehouse dispatch” are two entirely different actions in business terms — checking out means an employee retrieves equipment from the warehouse, while warehouse dispatch means the warehouse administrator records the equipment leaving inventory. The AI treated them as the same thing.

The problem was in the very first step. You handed a vague requirement directly to the AI. The AI has no mind-reading ability; it can only “guess” the most likely implementation from its training data. And guessing is the most expensive thing in engineering.

The root cause of most AI coding failures is not “AI cannot write code” — it is “AI built the wrong feature.” You described one requirement, the AI understood one version, and you had another version in mind. By the time the AI finishes writing the code, you discover it is not what you wanted. At that point, the cost of rework far exceeds what it would have cost to clarify things upfront.

The root of this problem is: requirements in people’s heads are vague, but code must be precise. When you say “build a borrowing request feature,” you have an entire business context in mind — who can borrow, what can be borrowed, for how long, under what conditions borrowing is allowed, and under what conditions it is not. But when this sentence is passed to the AI, all of that context is lost. “Borrowing request” in the training data could mean library book lending, tool room equipment checkout, or corporate fixed asset borrowing — three systems with enormous differences.

You might think: “No problem, I will just modify it after the AI builds it.” But there is a hidden cost issue here: changing a requirement during the coding phase typically costs far more than during requirements analysis — an order-of-magnitude factor of ten is the figure commonly cited in practice (i.e., the classic software-engineering rule that “the cost of change escalates with each phase,” extended into AI coding). Because changing a requirement during coding means rewriting code, rerunning tests, and redoing acceptance testing, whereas changing a requirement during analysis only requires changing one line of text.

Requirements Analysis solves this problem — turning the vague ideas in your head into a structured document that both AI and humans can accurately understand. Its core output is not code, but a “precisely aligned description for both sides.”

11.2 Event Storming: Aligning Requirements Through “Business Events”

The traditional requirements analysis method is the “feature list approach.” An analyst asks business personnel: “What features do you want the system to have?” The business personnel respond: “Borrowing management, equipment management, personnel management.” The analyst takes this list and designs the system.

This approach has a fundamental problem: the feature list is a product of the technical perspective, not the business perspective. What business personnel truly care about is not the “borrowing management” module, but the process of “what do I need to do after an employee submits a borrowing request.” When you hand “borrowing management” to the AI as a feature, it does not know whether your business process is “approve first, then dispatch” or “check out first, then register.” It can only guess a default generic process.

Event Storming changes the question. Instead of asking “what features does the system need,” it asks “what events happen in the business.” This shift in framing pulls the conversation anchor from “technical solution” back to “business process.”

Let us walk through a complete example of the Event Storming process.

Scenario: You are building an equipment lending management system. You gather business personnel for a requirements discussion meeting. Instead of asking “what features does the system need,” you ask: “Starting from when an employee borrows equipment to when the equipment is returned, what happens in between?”

The business personnel will say:

Example type: pseudocode. Pseudocode; it is not executable. It expresses decision order only, so implementation must supply real interfaces, authority and error handling.

Employee submits request -> Supervisor approves -> Warehouse dispatches equipment -> Employee checks out equipment -> Employee uses equipment -> Employee returns equipment -> Warehouse inspects equipment condition -> Equipment returned to inventory

These are the “business events.” Notice that events are all described in the past tense — “submitted a request,” “approved,” “dispatched” — because events are things that have happened, not things that will happen.

From these events, you can derive:

• Commands — who triggered this event? “Submit request” is triggered by “employee,” so the command is “submit borrowing request”; “approve” is triggered by “supervisor,” so the command is “approve request”;
• Aggregates — what is the core data that these events and commands operate on? Borrowing requests, equipment, employees, warehouse records — these are all aggregates;
• Bounded Contexts — which events and aggregates belong to the same business domain? Borrowing requests and approvals belong to the “borrowing management” context; equipment dispatch and return belong to the “inventory management” context; employee information belongs to the “personnel management” context.

Here is a concrete comparison:

Example type: pseudocode. Pseudocode; it is not executable. It expresses decision order only, so implementation must supply real interfaces, authority and error handling.

Feature list approach:
1. Borrowing management: request, approval, query
2. Equipment management: add, edit, delete, query
3. Personnel management: add, edit, delete

Event Storming approach:
Business event flow: Employee submits request -> Supervisor approves -> Equipment dispatched -> Employee checks out -> In use -> Return -> Inspection -> Back in inventory
Bounded contexts:
1. Borrowing management context: request, approval
2. Inventory management context: dispatch, return, inspection
3. Personnel management context: employee information maintenance

Do you see the difference? The feature list tells you “what modules the system has,” while the event flow tells you “how the system works.” The latter inherently includes the dependency relationships of the business process — you cannot build the dispatch feature before the request feature, because dispatch happens after the request. This dependency relationship is explicit in the event flow but invisible in the feature list.

Event Storming has another hidden benefit: it lets business personnel align on “events” rather than on “technical solutions.” Business personnel may not understand “databases,” “APIs,” or “bounded contexts,” but they certainly understand the difference between “employee submits a request” and “warehouse dispatches equipment.” When you say “let us first list the business events,” business personnel can participate in the discussion without friction. When you say “let us first design the database tables,” business personnel can only stay silent.

In one sentence: Event Storming describes business in the language of business, not in the language of technology.

11.3 Two Major Outputs of Requirements Analysis: REQUIREMENTS.md and Dispute Records

After requirements analysis is complete, two documents should be produced.

Output 1: REQUIREMENTS.md.

A complete REQUIREMENTS.md should include:

1. Project overview — one sentence describing what the project does;
2. User roles — who uses the system and what each role can do;
3. Feature list — features ranked by priority;
4. Business events — event flow of core business processes;
5. Data entities — core data model (initial);
6. Constraints — technical constraints, timeline constraints, compliance requirements.

Output 2: Dispute records.

During requirements analysis, there is one easily overlooked but extremely important output: dispute records.

The essence of requirements analysis is “making decisions.” But many people only focus on “what was ultimately decided” and ignore “what was dropped.” Why is it important to record “what was dropped”? Because behind every rejected option there is a trade-off — and someday in the future, when project conditions change, that trade-off may need to be revisited.

Here is a pedagogically reorganized example (details merged and anonymized). During the MVP phase of a project, the product manager requested support for a “partial refund” feature. After discussion, the team decided not to include it in the first version, but recorded the dispute:

Example type: reference. Reference fragment; it is not guaranteed to run alone. Adapt it to the lesson context, project versions and real interfaces, then validate with observed output.

Dispute 1: Should we support partial refunds?
Decision: Not supported in the first version.
Reason: The MVP phase needs scope control. Partial refunds involve complex
        amount-splitting logic, and integration with the payment gateway
        requires additional development work.
Impact scope: Order state machine, refund process, financial reports.
Date recorded: 2025-03-15

Six months later, the business grew rapidly, and users frequently requested partial refunds. The team opened the dispute records and immediately understood why it had not been built originally, what the impact scope was, and what was needed to support it. They started designing directly from this record, avoiding repeated discussions and pitfalls.

What would have happened without this record? New developers seeing “partial refunds not supported” would assume it was “forgotten” rather than “intentionally dropped.” They might spend a great deal of time discussing “should we build it” — a discussion that had already taken place six months earlier.

The core value of dispute records is: carrying “the reasoning behind past decisions” across time to provide context for future decisions. The record format does not need to be complex; the key is three pieces of information: what the dispute was, what the decision was, and why that choice was made.

Example type: reference. Reference fragment; it is not guaranteed to run alone. Adapt it to the lesson context, project versions and real interfaces, then validate with observed output.

Dispute N: [Description of the issue]
Decision: [Final choice]
Reason: [Why this choice was made]
Impact scope: [Which modules this decision affects]
Date recorded: [YYYY-MM-DD]

11.4 Common Requirements Analysis Mistakes: Over-Abstraction, Feature Pile-Up, Ignoring Non-Functional Requirements

Mistake 1: Over-abstraction.

“Build a generic workflow engine that supports various business scenarios.” This is the most common requirements analysis trap. Generic = vague. AI cannot design the solution you want for something “generic.”

The correct approach: start with a concrete scenario, then abstract. “First build a leave approval workflow, then we will see if we can abstract it into a generic engine.”

Mistake 2: Feature pile-up.

“This system needs: order management, user management, product management, inventory management, financial management, report analysis, push notifications, permission management…” When the feature list exceeds 10 items, the focus of requirements analysis should shift from “adding features” to “prioritizing.”

The correct approach: distinguish the MVP (minimum viable product) from subsequent versions. “The first version only includes: order management + user management. Other features will be added gradually in later versions.”

Mistake 3: Ignoring non-functional requirements.

A system that processes “1,000 orders per day” versus “1,000,000 orders” requires entirely different technical solutions. Non-functional requirements (performance, security, availability, scalability) directly influence architectural design. If not stated clearly, the AI may choose a solution that does not fit your scale.

The correct approach: clarify non-functional requirements during the analysis phase. “Data volume: approximately 100 orders per day, total data under 100,000 records. No high concurrency needed. However, data security requirements are high because financial information is involved.”

[Hands-On] Using Event Storming to Analyze a Business Scenario

Exercise: Choose a business scenario you are familiar with (e.g., library book borrowing, meeting room reservation, expense reimbursement, food ordering) and use the Event Storming method to complete a requirements analysis.

Step-by-step guidance:

1. List events: From start to finish, list all business events (in past tense). List at least 8.
2. Derive commands: For each event, note “who triggered it?” -> produce a command list.
3. Identify aggregates: What core data do these commands and events operate on? -> produce an aggregate list.
4. Define contexts: Which events and aggregates belong to the same business domain? -> produce a bounded context list.
5. Write dispute records: If there are any “should we build it” debates during the analysis, record them using the dispute record format.

Reference answer (using library book borrowing as an example):

Example type: pseudocode. Pseudocode; it is not executable. It expresses decision order only, so implementation must supply real interfaces, authority and error handling.

Business event flow: Patron submits borrowing request -> System checks availability -> Librarian confirms checkout ->
                     Patron receives checkout notification -> Patron returns on time -> Librarian inspects book condition -> System registers return

Commands: Submit borrowing request (patron), confirm checkout (librarian), register return (librarian)
Aggregates: Borrowing record, book, patron, overdue record
Bounded contexts: Borrowing management (request/confirmation/return), collection management (book status/quantity), patron management (patron records)

Dispute records:
Dispute 1: Should overdue items automatically generate fines?
Decision: First version uses manual registration, no automatic calculation.
Reason: Fine rules involve rate configuration and payment integration; MVP phase needs scope control.

Acceptance criteria:

• Did the trainee describe events using the past tense (not “will happen”)?
• Did the trainee distinguish between “events” and “features”?
• Does the trainee’s dispute record include: dispute, decision, reason, impact scope, and date?

---

Independent exercise

Use fictional or authorized deidentified material. Answer independently before revealing the reference. Save chapter-11.md with versions, decisions, evidence and gaps.

From ticket submission, information completion and category confirmation, extract events, commands, roles and conflicts, then write three testable requirements and two questions.

Required chapter artifact: requirements scoping package

The submission for this independent exercise must contain the evidence below. The existing prompts supply content but do not replace these acceptance items.

• O1: The requirements scoping package connects business event, ownership and scope and stop condition in input-output order
• O2: Every step in the requirements scoping package states its owner, input, output and completion rule
• O3: The artifact links all five scoping evidence types to one event and marks gaps

Reveal reference feedback (answer first)

Reference feedback

An event is ‘ticket submitted’; a command is ‘submit ticket.’ Specify who may enrich or confirm it and how empty or unknown titles behave. Confirm retention and whether classification may override humans; do not promote assumptions into approved requirements.

Self-review and next steps

Check whether your decision is explicit, evidence reproducible and unknowns honestly recorded. The reference illustrates one defensible approach, not a unique answer. Seek peer review for alternatives with equivalent evidence. Mark unsupported parts unfinished and revisit the corresponding step.