Open details without losing your place

# Apply the “Open details without losing your place” guide in your agent

## Objective
Use a page for a destination worth linking to, a temporary panel for related details and a modal only for a bounded task that must interrupt the page. Preserve the list context when returning. Position on the screen is not enough to decide modality, keyboard behavior or navigation history.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Choose a page, side panel or dialog and preserve list filters, Back behavior and focus.
- Preserve the correct decisions already in place.

## Guide steps
- 1. Choose the surface by task — A customer record with its own history deserves a stable page. A quick preview can stay beside the list. Confirming a destructive change is a different interruption, not a reason to put every detail in a modal. A drawer may be modal or non-modal; decide whether the underlying page remains usable. A permanent sidebar organizes navigation. Do not assign dialog semantics to a sidebar merely because it is on an edge.
- 2. Define return behavior — Record which filter, sort order, page and item establish the user’s place. A meaningful route should survive reload; purely temporary presentation need not become a separate public URL. Put only shareable, non-sensitive state in a query string. URL fragments avoid ordinary HTTP transmission but remain visible to page scripts and browser history. Do not treat either as secret storage.
- 3. Example: inspect a filtered list — From page three of open tickets, open one record, then return. Restore the filter and page, and place focus on the originating row when it still exists. If it was removed, use the list heading or a nearby stable control. For a modal preview, opening moves focus inside, Tab stays within it and Escape closes it and focus returns to the opening control when it still exists. For a non-modal panel, do not trap focus; retain a clear route between list and panel.
- 4. Handle small screens and edits — A side-by-side view can become a full-width detail on mobile without losing its return contract. Keep the close or back control visible. Do not render two independently focusable copies of the same form. If leaving discards edits, use the product’s draft or explicit discard policy. Closing a panel is not automatically cancelling a server operation. Explain these boundaries rather than tying data loss to a visual transition.
- 5. Verify navigation as a round trip — Check opening, browser Back, explicit Close, reload and a directly opened link. Repeat with a deleted origin item and keyboard-only input. Assert the restored context, not just that a panel closed. This guide helps choose navigation behavior. It does not supply authorization, a router implementation or a guarantee of preserved scroll on every platform; record those platform limits explicitly.

## Acceptance criteria — Verify in your product
- The surface matches the task.
- Modality is explicit.
- Filters survive return.
- Focus has a valid destination.
- Direct links and reload work.
- Sensitive state stays out of shared URLs.

## 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:34c3c3d84f4c1d38422d636749f14f86e968ae1085ac20df788ebcaa1afedb17

# Diagnose a failed application of the “Open details without losing your place” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. Choose the surface by task — A customer record with its own history deserves a stable page. A quick preview can stay beside the list. Confirming a destructive change is a different interruption, not a reason to put every detail in a modal. A drawer may be modal or non-modal; decide whether the underlying page remains usable. A permanent sidebar organizes navigation. Do not assign dialog semantics to a sidebar merely because it is on an edge.
- 2. Define return behavior — Record which filter, sort order, page and item establish the user’s place. A meaningful route should survive reload; purely temporary presentation need not become a separate public URL. Put only shareable, non-sensitive state in a query string. URL fragments avoid ordinary HTTP transmission but remain visible to page scripts and browser history. Do not treat either as secret storage.
- 3. Example: inspect a filtered list — From page three of open tickets, open one record, then return. Restore the filter and page, and place focus on the originating row when it still exists. If it was removed, use the list heading or a nearby stable control. For a modal preview, opening moves focus inside, Tab stays within it and Escape closes it and focus returns to the opening control when it still exists. For a non-modal panel, do not trap focus; retain a clear route between list and panel.
- 4. Handle small screens and edits — A side-by-side view can become a full-width detail on mobile without losing its return contract. Keep the close or back control visible. Do not render two independently focusable copies of the same form. If leaving discards edits, use the product’s draft or explicit discard policy. Closing a panel is not automatically cancelling a server operation. Explain these boundaries rather than tying data loss to a visual transition.
- 5. Verify navigation as a round trip — Check opening, browser Back, explicit Close, reload and a directly opened link. Repeat with a deleted origin item and keyboard-only input. Assert the restored context, not just that a panel closed. This guide helps choose navigation behavior. It does not supply authorization, a router implementation or a guarantee of preserved scroll on every platform; record those platform limits explicitly.

## 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
- The surface matches the task.
- Modality is explicit.
- Filters survive return.
- Focus has a valid destination.
- Direct links and reload work.
- Sensitive state stays out of shared URLs.

## 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:96fe13bafa6bddaf722f90b1d3f78761becb24b2d16f2c225d0984aca0b18e98