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:
1. Run `gh --version` — if fails, report "gh CLI not installed. Install: https://cli.github.com"
2. Run `gh auth status` — if fails, report "gh not authenticated. Run: gh auth login"

If either check fails, stop and report the constraint.

## 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 the command templates in `references/gh-patterns.md`: code search with `--repo`/`--owner`/`--limit`, tree API for structure, contents API for listings; find symbol, explore structure, find examples, compare implementations.

### 3. Cache Files
Cache only files you need to cite, into `.zharness/cache/github/{owner}/{repo}/`, with the contents-API recipe in `references/gh-patterns.md`.

### 4. Read and Cite
Read cached files with line numbers. 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` — 7 known-good gh command templates; 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