Discover the Workflow People Actually Perform
Requirements are not waiting in a meeting to be collected. They are scattered across actions, workarounds, records, and disagreements.
Lesson 48 of 54Learn + Build~70 minutesPython (stdlib)
Before this: Lesson 47 of Phase 14
On this page
Learning Objectives
- Model the current workflow as ordered actions with evidence.
- Separate direct observation from reported or inferred behavior.
- Locate friction, handoffs, authority, and hidden state.
- Keep uncertain claims visible instead of turning them into requirements.
Start with the Current System
Do not begin by asking what features people want. Begin by reconstructing what happens now.
For each step, record:
| Field | Example |
|---|---|
| Actor | On-call engineer |
| Trigger | Production alert arrives |
| Action | Opens alert, then searches dashboards |
| Input | Alert payload and deployment record |
| Output | Candidate service and owner |
| Friction | Context switching across three tools |
| Authority | Incident commander approves a write |
| Evidence | Screen recording, incident log, runbook |
The workflow is larger than the screen. It includes waiting, copy-paste, side channels, approval, error recovery, and the steps people have stopped noticing.
Evidence Has Strength
Use a simple evidence ladder:
- Direct behavior: observation, trace, recording, or system event.
- Artifact: ticket, runbook, log, form, or completed output.
- Reported behavior: a person describes what they do.
- Inference: the team concludes what probably happens.
All four can be useful. Only the first two prove current behavior directly. Label the rest so confidence does not silently inflate.
Search for Four Things
- Friction: repeated effort, delay, re-entry, or recovery.
- Hidden state: facts carried in memory, chat, or personal notes.
- Authority: the person or system allowed to make a consequential change.
- Exceptions: the case where the normal workflow stops being normal.
AI features often fail at handoffs and exceptions because the happy path was the only path shaped.
Do Not Average Away Disagreement
Two users can perform different workflows for good reasons. Preserve the variants until you understand whether they represent:
- different roles;
- different risk levels;
- legacy and current process;
- expertise differences;
- a genuine policy disagreement.
An averaged workflow can describe nobody.
Build It
The lab stores evidence on every workflow step, validates ordering and confidence, calculates the direct-evidence ratio, and writes outputs/workflow-evidence.json.
python3 code/main.py
python3 -m unittest discover code/tests -vAdd an exception path in which the deployment record is missing. Keep the main order intact and record where the branch begins.
Exercises
- Reconstruct one workflow from a log without interviewing anyone.
- Interview a user and mark every claim that still lacks direct evidence.
- Add one authority boundary and one failure-recovery step.
- Model two workflow variants without merging them.
- Identify a proposed feature that removes a visible step but leaves hidden work untouched.
Further Reading
- Nuseibeh and Easterbrook, Requirements Engineering: A Roadmap, especially its treatment of elicitation as interpretation, modelling, and validation rather than simple capture.
- Gotel and Finkelstein, An Analysis of the Requirements Traceability Problem, for the difficulty of preserving the relationship between requirements and their sources.
What You Keep
Keep outputs/workflow-evidence.json. It turns observed friction and uncertainty into an assumption map in the next lesson.
Check yourself
Quick quiz
Why start with current behavior instead of requested features?
- The real workflow reveals workarounds, handoffs, state, and constraints
- Features are never useful
- It guarantees production readiness
- It avoids users
Show the answer
A. The real workflow reveals workarounds, handoffs, state, and constraints Requirements emerge from how work actually happens, not only what people request.
Which is the strongest direct evidence?
- A user says what usually happens
- A roadmap
- A system trace of the action
- A team guess
Show the answer
C. A system trace of the action A trace observes behavior directly rather than reporting or inferring it.
What four workflow surfaces deserve special attention?
- Branches, commits, tags, releases
- Friction, hidden state, authority, and exceptions
- Color, font, layout, animation
- Model, tokens, temperature, prompt
Show the answer
B. Friction, hidden state, authority, and exceptions These surfaces commonly contain the real problem and risk.
Why preserve workflow variants?
- An average may describe nobody and erase valid role or risk differences
- Variants are easier to code
- All users are identical
- It removes evidence needs
Show the answer
A. An average may describe nobody and erase valid role or risk differences Differences can encode roles, policy, expertise, or legacy state.
What does a direct-evidence ratio communicate?
- Deployment cost
- Model accuracy
- Feature completeness
- How much of the workflow is grounded in observation rather than report or inference
Show the answer
D. How much of the workflow is grounded in observation rather than report or inference It keeps the strength of evidence visible.
What is a hidden workflow step?
- A public API
- A unit test
- A CSS transition
- Work carried in memory, chat, or personal notes outside the formal process
Show the answer
D. Work carried in memory, chat, or personal notes outside the formal process Hidden state often explains why the visible process is incomplete.
Questions people ask
How do you find what to automate in a business?
Map how a task is actually done now: each step, who does it, the trigger, inputs, outputs, waiting, approvals and workarounds. Repeated, rule-based steps with lots of copying or waiting are good candidates.
Why are interviews alone not enough to gather requirements?
People describe the official process and forget the workarounds they no longer notice. Watching the work and checking records, logs and real examples reveals the hidden steps that a new system must handle.
Lessons from AI Engineering from Scratch by Rohit Ghumare and contributors, MIT license. Notes for owners by Lozo. License