Step 1
Step 1 — Turn requirements into states and evidence
0 views
Step 1 — Turn requirements into states and evidence
“The upload works” is too broad. Define success, waiting, partial completion, and failure before implementation, including what can be retried.
| State | Server fact | User feedback | Next action |
|---|---|---|---|
| success | all required contracts hold | counts and next step | verify the public path |
| in progress | work still has an owner | progress and duplicate-click protection | wait or leave |
| partial failure | some work completed and failures remain | processed/failed counts and details | retry failed items |
| failure | a transaction or required check was rejected | safe error and retry guidance | fix and retry |
Use five perspectives: product defines normal and exceptional behavior; design covers narrow screens, keyboard, focus, and copy; engineering aligns API and DB contracts; users can see current state; operations can health-check, observe, and recover. The completion chain is:
requirement → state/error → API/DB → UI feedback → automated check → deployment smoke
Codingstairs Admin seed must return 409 and an error list when a source file is invalid. The UI should expose role=status, counts, expandable details, and retry guidance instead of reporting a quiet success.
Practice
Choose one feature and write this table. Add one command or log location as evidence for every row, then add a partial-failure test to any test that only checks success.