---
name: search-refinement
description: >
  Filter, paginate, and browse search results from capacity or task matching.
  Use this skill when the user wants to see different result categories,
  filter by availability, or page through results.
---

# Search Refinement & Pagination

## Search ID Tracking (critical)

Always maintain `LATEST_SEARCH_ID`:
- Update only from the most recent tool output
- Accept only IDs labeled as `Using SEARCH_ID=<uuid>` or `SEARCH_ID=<uuid>`
- Never invent or guess a search ID
- Before every refinement call, write: `Using SEARCH_ID=<LATEST_SEARCH_ID>`

## Browse by Category

Call `get_results_by_category(search_id, category, page, page_size)`:
- Categories: `Top`, `Good`, `Partial`, `Low`, `Irrelevant`
- Default page_size: 20
- Echo the Category, Page, and Total items after each call

## Filter Results

Call `filter_search_results(search_id, ...)` with any combination of:

### General filters (both directions)
- `role_filter`: fuzzy match against result's role
- `competence_filter`: fuzzy match against result's competences
- `availability_date_start` / `availability_date_end`: override reference window
- `is_fully_available`: capacity must fully cover the reference window

### Task-search-only filters
- `task_text_filter`: case-insensitive substring in task title/description
- `task_competence_filter`: match against task's required competences

After filtering, a `filter_id` is returned. Use it in subsequent `get_results_by_category` calls.

## Expired/Invalid Search

If a tool returns `status=unknown_or_expired`:
- Do NOT retry with another guessed ID
- Rerun `find_matching_capacities(...)` or `find_matching_tasks(...)` to create a fresh search
- Replace `LATEST_SEARCH_ID` with the new value