Loading, empty or broken: show the right next step

# Apply the “Loading, empty or broken: show the right next step” guide in your agent

## Objective
Treat loading, an empty account, filtered emptiness and failure as different states. Preserve context and offer an action that can actually help. A skeleton describes waiting, not proof that data exists. Retry should retain the query and filters rather than silently resetting the task.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Distinguish waiting, first-use emptiness, no matching results and a failed service.
- Preserve the correct decisions already in place.

## Guide steps
- 1. Map response states — For a project list, name not requested, loading, populated, empty and failed states. Add refreshing with old data if necessary. Associate each state with actual response evidence. Do not convert every failure into an empty array. No projects is a valid result; a failed request leaves the contents unknown. Permission denial is another distinct case.
- 2. Choose waiting feedback — Use a loading label for unknown duration. A skeleton reserves a known shape; a percentage needs measurable work and a total. Do not simulate a fake completion rate. Keep independent controls usable. Label old results during refresh so they are not mistaken for new results. Avoid repeating announcements on every animation frame.
- 3. Example: three empty lists — A new workspace offers Create a project. A filter with no matches shows active criteria and Clear filters. A network failure offers Try again while retaining the query. Do not offer all three actions indiscriminately. If creation is forbidden, explain the access boundary and the available contact route without pretending to submit an automatic request.
- 4. Reject stale responses — When a new query replaces the first, cancel or ignore the older result. Its late success must not overwrite the current query’s failure or matches. Keep query and displayed data aligned. Browser cancellation does not undo server work. For read-only lists it prevents obsolete rendering; writes need a separate recovery contract. Avoid unbounded automatic retry loops.
- 5. Verify each next action — Exercise one response per state and two responses out of order. Verify each action changes the right condition. If a focused retry control disappears, provide a sensible focus destination. Keep status understandable without motion and at 320 px. DOM roles alone do not prove actual screen-reader announcements; keep that qualification distinct.

## Acceptance criteria — Verify in your product
- Loading is not emptiness.
- Initial and filtered emptiness differ.
- Failure retains input.
- Retry has a bounded effect.
- Late data cannot overwrite current data.
- Status survives motion removal.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Anchor the guide in the project

## Objective
Turn the applied steps into durable repository conventions.

## Checks
- Link each decision made to the guide step that justifies it.
- Add the checklist to the relevant reviews.
- Record out-of-scope cases for the neighboring guides.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:ddf58ba759c28f48e931550526c366b753a404faef7f9cc65c572506bfa32ee7

# Diagnose a failed application of the “Loading, empty or broken: show the right next step” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. Map response states — For a project list, name not requested, loading, populated, empty and failed states. Add refreshing with old data if necessary. Associate each state with actual response evidence. Do not convert every failure into an empty array. No projects is a valid result; a failed request leaves the contents unknown. Permission denial is another distinct case.
- 2. Choose waiting feedback — Use a loading label for unknown duration. A skeleton reserves a known shape; a percentage needs measurable work and a total. Do not simulate a fake completion rate. Keep independent controls usable. Label old results during refresh so they are not mistaken for new results. Avoid repeating announcements on every animation frame.
- 3. Example: three empty lists — A new workspace offers Create a project. A filter with no matches shows active criteria and Clear filters. A network failure offers Try again while retaining the query. Do not offer all three actions indiscriminately. If creation is forbidden, explain the access boundary and the available contact route without pretending to submit an automatic request.
- 4. Reject stale responses — When a new query replaces the first, cancel or ignore the older result. Its late success must not overwrite the current query’s failure or matches. Keep query and displayed data aligned. Browser cancellation does not undo server work. For read-only lists it prevents obsolete rendering; writes need a separate recovery contract. Avoid unbounded automatic retry loops.
- 5. Verify each next action — Exercise one response per state and two responses out of order. Verify each action changes the right condition. If a focused retry control disappears, provide a sensible focus destination. Keep status understandable without motion and at 320 px. DOM roles alone do not prove actual screen-reader announcements; keep that qualification distinct.

## Possible causes
- A step was skipped or executed out of order.
- The actual need falls outside the guide scope.
- A checklist criterion was never verified.

## Bounded fixes
- Redo only the diverging step and what depends on it.
- Document the gap if the guide scope does not cover the need.

## Final verification — Verify in your product
- Loading is not emptiness.
- Initial and filtered emptiness differ.
- Failure retains input.
- Retry has a bounded effect.
- Late data cannot overwrite current data.
- Status survives motion removal.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Prevent the next drift

## Objective
Turn the first diverging step into an explicit project check.

## Checks
- Add a focused check on the step that diverged.
- Verify the checklist on a second real case.
- Document the scope limit you hit.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:63d0abf5036c40a567697074573c1d51998324d4a1d3693f23a9849feb2a9d87