Find an item in a long list without hidden filters

# Apply the “Find an item in a long list without hidden filters” guide in your agent

## Objective
Separate search text, inclusion filters, sorting and pagination: they answer different questions. Keep active criteria visible, reset the page when the result set changes and explain no matches without removing the query. Choose explicit Apply when several expensive filters need to change together.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Combine text search, filters, sorting and pagination while preserving a clear result count and reset path.
- Preserve the correct decisions already in place.

## Guide steps
- 1. Define each control — In an order list, text can find a reference, status narrows eligible orders, date sort changes order and pagination changes the visible slice. Sorting must not silently filter out records. Document whether several values in one group mean OR and separate groups mean AND. Show the interpretation in ordinary words, especially for date ranges and inclusive boundaries.
- 2. Choose immediate or applied filters — Immediate filtering suits cheap local changes if typing and focus remain stable. An Apply button suits multiple remote criteria and lets users finish choosing before a request. Do not mix both behaviors without clear feedback. Keep selected criteria visible when a mobile filter panel closes. A count badge alone cannot explain what is excluded; provide readable criteria and a way to remove each one.
- 3. Example: overdue orders — Select Pending and a delivery date before today, then Apply. Show the resulting count and both criteria. Changing the filter from page five returns to the first valid page rather than an apparently empty page five. No results offers removing the date or clearing filters while retaining the text query unless explicitly cleared too. Keep the difference between zero matches and failed loading visible.
- 4. Choose pagination deliberately — Pagination gives a bounded slice and a return location. Load more keeps earlier items but needs a reachable control. Infinite loading needs a reason and reliable access to the footer, focus and previous position. Use a stable sort tie-breaker in the data contract. If live updates move records between pages, disclose refresh behavior and avoid presenting a stale total as exact. UI controls cannot repair inconsistent backend ordering.
- 5. Verify combinations — Test one criterion, two combined criteria, no results, clear one, clear all and Back from a detail. Resolve remote requests out of order to ensure the visible criteria match the visible items. Check keyboard labels and result announcements without moving focus on each update. This guide does not promise search relevance at arbitrary scale; indexing and backend query costs remain separate.

## Acceptance criteria — Verify in your product
- Search, filter and sort differ.
- Active criteria remain visible.
- Combined logic is explained.
- Page reset avoids false emptiness.
- Clear actions have an explicit scope.
- Results match the latest request.

## 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:de143f61028c351d2b001251a0416f9b25cf0ce94a41332319e71180696a7422

# Diagnose a failed application of the “Find an item in a long list without hidden filters” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. Define each control — In an order list, text can find a reference, status narrows eligible orders, date sort changes order and pagination changes the visible slice. Sorting must not silently filter out records. Document whether several values in one group mean OR and separate groups mean AND. Show the interpretation in ordinary words, especially for date ranges and inclusive boundaries.
- 2. Choose immediate or applied filters — Immediate filtering suits cheap local changes if typing and focus remain stable. An Apply button suits multiple remote criteria and lets users finish choosing before a request. Do not mix both behaviors without clear feedback. Keep selected criteria visible when a mobile filter panel closes. A count badge alone cannot explain what is excluded; provide readable criteria and a way to remove each one.
- 3. Example: overdue orders — Select Pending and a delivery date before today, then Apply. Show the resulting count and both criteria. Changing the filter from page five returns to the first valid page rather than an apparently empty page five. No results offers removing the date or clearing filters while retaining the text query unless explicitly cleared too. Keep the difference between zero matches and failed loading visible.
- 4. Choose pagination deliberately — Pagination gives a bounded slice and a return location. Load more keeps earlier items but needs a reachable control. Infinite loading needs a reason and reliable access to the footer, focus and previous position. Use a stable sort tie-breaker in the data contract. If live updates move records between pages, disclose refresh behavior and avoid presenting a stale total as exact. UI controls cannot repair inconsistent backend ordering.
- 5. Verify combinations — Test one criterion, two combined criteria, no results, clear one, clear all and Back from a detail. Resolve remote requests out of order to ensure the visible criteria match the visible items. Check keyboard labels and result announcements without moving focus on each update. This guide does not promise search relevance at arbitrary scale; indexing and backend query costs remain separate.

## 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
- Search, filter and sort differ.
- Active criteria remain visible.
- Combined logic is explained.
- Page reset avoids false emptiness.
- Clear actions have an explicit scope.
- Results match the latest request.

## 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:f36d837fd9fdf4c2a030216b3979452d73932ce1bd92364b8f315cbf9cd6b6ce