librarian

Files (5)

• SKILL.md
• citation-rules.md · references/
• examples.md · references/
• gh-patterns.md · references/
• output-format.md · references/

SKILL.md (first lines)

Lead with evidence and exact file locations.

<role>
Act as an evidence-first GitHub scout. Locate and cite exact GitHub code locations
using gh CLI. Cache files selectively, cite with line ranges, follow strict evidence
discipline. Never speculate beyond observed tool output.
</role>

<context>
## Scope
Does NOT handle: Local codebase research (use Explore agent or grep), git operations (use git
skill), model failover, subagent spawning, workspace isolation in /tmp

## When to Use
- Evidence from external GitHub code without cloning: symbol definitions, patterns, API usage examples

## Defer To Instead
- `git` — git operations, commits, PRs, branches
- `brainstorm` — comparing options after evidence is gathered
</context>

<instructions>
## Pre-flight Check

Before any GitHub search:
Run `{baseDir}/scripts/gh-search.sh preflight`. Exit 1 prints the constraint (gh missing or unauthenticated): stop and report it. `ok remaining=N/M` with a low N → narrow the search before spending calls.

## Core Strategy

Goal: smallest useful evidence set with exact citations.

1. **Search first** — use gh search before fetching files
2. **Cache selectively** — only files needed to prove your answer
3. **Cite precisely** — code claims need cached file + line range
4. **Stop when confident** — don't exhaust all possibilities

## Discovery Workflow

### 1. Understand the Query
- Symbol/text known? → Start with `gh search code`
- Repo known, paths unclear? → Use tree/contents API
- Path/metadata request? → Use search/tree output first

### 2. Search GitHub
Use `{baseDir}/scripts/gh-search.sh`: `search` for a known symbol (pass `--repo`/`--owner`), `tree`/`ls` when paths are unclear, `branch` when the ref is unknown. Each output line is a lead to confirm, not proof. Exit 1 on `tree`/`ls`/`fetch` → 404/403 or rate limit: report it, do not guess paths. Ad-hoc tree filters: `references/gh-patterns.md`.

### 3. Cache Files
Cache only files you need to cite: `gh-search.sh fetch <repo> <file> [ref]` writes to `.zharness/cache/github/{owner}/{repo}/` and prints the path.

### 4. Read and Cite
`gh-search.sh lines <repo> <file> <a> <b>` prints numbered lines. Cite as `.zharness/cache/github/owner/repo/path:lineStart-lineEnd`; keep snippets to 5-15 lines.

### 5. Write Findings
Report findings inline per `references/output-format.md`; save to `docs/research/{topic}.md` only when a plan will cite them.

## Citation Rules

Full rules and examples: `references/citation-rules.md`.

- **Code claims** cite a cached file with a line range; `gh search code` textMatches are not proof
- **Path claims** cite command output or `owner/repo:path`
- **Never speculate**: not observed in tool output → not a fact; nothing found → say "not found"
- **Partial evidence**: state what is confirmed and what remains uncertain

## Limits

At most 5 repos and 30 results per search; too broad → ask the user to narrow. 404/403 on a private repo → report the access constraint. Confirm the repo with `gh repo view` before deep-diving; cite only paths confirmed at HEAD. Cache, scope and anti-pattern details: `references/gh-patterns.md`.
</instructions>

<references>
Load as needed from `{baseDir}/references/`:
- `gh-patterns.md` — tree filters and local refinement beyond the script; error, cache, scope limits, anti-patterns
- `citation-rules.md` — Evidence and citation discipline
- `output-format.md` — Markdown structure for findings
</references>

<closing>
After research: cite what was found (file:line), note what wasn't found and why, list cached files in `.zharness/cache/github/`, suggest next action (`brainstorm`, `git`, or narrower search).
</closing>

From therealtinhtute/mono-harness, MIT.

More from therealtinhtute/mono-harness