text-search

Files (8)

• SKILL.md
• analyze-sessions.sh · scripts/
• claude-session-extract-with-tools.py · scripts/
• codex-session-extract-with-tools.py · scripts/
• pi-session-extract-with-tools.py · scripts/
• rebuild-qmd-sessions-rendered.sh · scripts/
• repoprompt-agent-session-extract.py · scripts/
• session-view · scripts/

SKILL.md (first lines)

# text-search

Use qmd to search indexed text corpora such as session logs, notes, docs, and logs. For indexed content, use qmd for discovery instead of raw `grep`.

## First checks

Before searching, confirm what is indexed:

```bash
qmd status
qmd collection list
qmd context list
```

Do not assume collection names, paths, or contexts.

## Core rule

For indexed corpora, use qmd for discovery.

Do **not** use `grep`/`find`/`jq`/`cat` directly on indexed files to search for meaning. This is especially important for session JSONL, which is noisy and hard to interpret raw.

Shell usage is still fine for:
- filtering tool output after discovery
- housekeeping and file targeting
- non-indexed content
- helper scripts in this skill

## Choose the right qmd command

For exact clues, start with `qmd search`.

- Use `qmd search` for exact clues: tool names, error strings, repo names, JSON fields, literal phrases
- Use `qmd query` when lexical search is weak, the request is conceptual, or you want hybrid retrieval + reranking
- Use `qmd vsearch` only when you specifically want pure semantic similarity

```bash
qmd search '"toolName":"rp_exec"'
qmd search 'apply_edits'
qmd query "OAuth redirect flow"
qmd vsearch "the session where we changed direction"
```

Operational notes:
- `qmd query` may trigger local model startup or model downloads, so it is not always the fastest first step
- For session discovery, prefer `--files` first so you get compact path output instead of long snippets

## Build better queries

### Use `--intent` when the request is ambiguous

`intent` is a steering hint. Use it when the same words could refer to multiple things or when the user remembers the topic better than the exact wording.

```bash
qmd query --intent "Pi/Codex/Claude agent sessions about repo editing failures" \
  -c sessions \
  "apply_edits error"
```

### Use structured query documents for important searches

Multi-line query documents are useful when you have both exact clues and fuzzy memory.

- `lex:` exact terms, phrases, identifiers, JSON fields
- `vec:` natural-language meaning
- `hyde:` what the answer likely looked like
- `intent:` optional steering context

```bash
qmd query $'intent: agent sessions about RepoPrompt edits and patch failures
lex: apply_edits rp_exec "search block not found"
vec: debugging failed file edits in agent sessions
hyde: The agent tried to edit a file several times, the edit did not match, and it switched to a narrower or different approach'
```

Operational details:
- The first typed query gets 2x fusion weight, so put the strongest signal first
- `expand:` must stand alone; do not mix it with typed lines
- lex queries support quoted phrases and exclusions such as `-sports` or `-"test data"`

### Useful output and tuning flags

```bash
qmd query --files -n 20 "agent session about flaky tests"
qmd query --json -n 10 "session where we redesigned the search flow"
qmd query --json --explain -c sessions "apply_edits error"
qmd query -C 20 --min-score 0.3 -c sessions "OAuth redirect flow"
```

Use:
- `--files` for compact discovery output and path-based follow-up
- `--json` for structured inspection when you need scores/snippets
- `--explain` when ranking looks wrong
- `-C, --candidate-limit` to reduce reranking work
- `--min-score` to drop weak matches
- `-c, --collection` to scope the search

For session hunting, `--files` is usually the best first output mode.

## Retrieval commands

```bash
qmd get "#abc123"
qmd multi-get "docs/*.md" --json
qmd ls sessions
qmd ls sessions/claude
```

Use `get`, `multi-get`, and `ls` to retrieve or browse content after discovery.

For session discovery, use this inspection path:

```bash
# 1. Discover a session transcript
qmd search -c sessions --files 'apply_edits' -n 5

# 2. Read the session transcript directly
qmd get "qmd://sessions/path/to/session-transcript.md" --full
```

From w-winter/dot314, MIT.

More from w-winter/dot314