Step 1
Step 1 — Turn requirements into states and evidence
2 views
“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 |
Zero rows and a failed read are different states. If refresh fails, preserve the last successful list instead of replacing it with an empty array. Show a separate retryable error. When a mutation succeeds but the follow-up refresh fails, say “saved; refresh failed,” not “save failed,” so the user does not repeat the mutation.
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
An admin console content 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.