Search Checkpoints

entire search

Response Format

Entire Search:

• Apply the header to the first response of the invocation only. Do not re-print it on follow-up turns within the same invocation (e.g. after the user answers a clarifying question).
• Do not include the header on error or early-exit responses (e.g. "Entire CLI not installed", "authentication required", "no matches"). The header's presence should signal that the skill ran and produced real output.

When to Use

• The user asks things like "have we done this before?", "search past work", "find the previous implementation", or "look for checkpoints about X"
• You need prior context from another branch, repo, author, or recent time period
• You want likely matches first, then a deeper transcript read only for the best hit

session-handoff

Process

1. Run a focused search with JSON output so results are easy to inspect:

entire search "<query>" --json

entire search "<query>" --json --repo owner/name --branch branch-name --author "Name" --date week

author:<name>

date:<week|month>

branch:<name>

repo:<owner/name>

repo:*

1. Review the top matches and summarize the likely candidates for the user. Do not dump raw JSON unless they ask for it.
2. If the user wants details on a specific result, open the checkpoint with:

entire explain --checkpoint <checkpoint-id> --full --no-pager

--full

entire explain --checkpoint <checkpoint-id> --raw-transcript --no-pager

Search Heuristics

• Start with the user's domain terms, feature name, error text, file name, or ticket ID
• Prefer narrower searches before increasing

  --limit

• Add

  --repo

  or

  repo:*

  explicitly when repository scope matters
• If there are no useful hits, broaden in this order: remove branch filter, widen date, simplify query terms

Failure Modes

• If search says authentication is required, tell the user to run

  entire login

• If there are no matches, say that clearly and mention the filters or query terms you tried
• If the user really wants the current session, switch to

  session-handoff

  instead of searching checkpoints