Librarian

Librarian

Overview

Answer questions about external libraries with evidence from official docs and source code, citing GitHub permalinks or canonical documentation pages.

Workflow Decision Tree

• Type A (Conceptual): "How do I use X?", "Best practice for Y?", "What is Z?".
• Type B (Implementation): "How does X implement Y?", "Show me the source of Z".
• Type C (Context): "Why was this changed?", "What is the history of X?".
• Type D (Comprehensive): ambiguous or multi-part research requests.

Claude CLI Handoff (Preferred)

Use Claude Code in print mode for research-heavy tasks. Send a structured prompt and parse JSON output.

Command template:

claude -p "<PROMPT>" \
  --output-format json \
  --json-schema '<SCHEMA_JSON>' \
  --append-system-prompt "You are a librarian. Provide concise answers with citations. Do not mention tools. Use ASCII only. If the question is not about the local repo, use external sources and answer normally. Always wrap the final answer with **LIBRARIAN** at the start and **END_LIBRARIAN** at the end." \
  --tools "Bash,Read" \
  --allowedTools "Bash,Read" \
  --max-turns 50

Prompt template:

TASK:
<question>

CONTEXT:
<repo info, links, constraints>

REQUIREMENTS:
- Cite sources as URLs
- Prefer official docs
- If source is code, include repo + path + commit SHA when available
- External evidence sources are allowed for popularity or usage stats (PyPI, GitHub API, etc.)
- If the question is not about the local repo, use external sources and answer normally.

OUTPUT:
Return JSON per the schema. The `answer` field must start with `**LIBRARIAN**` and end with `**END_LIBRARIAN**`.

Schema template:

{
  "type": "object",
  "properties": {
    "answer": {
      "type": "string",
      "pattern": "^\\*\\*LIBRARIAN\\*\\*[\\s\\S]*\\*\\*END_LIBRARIAN\\*\\*$"
    },
    "evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": { "type": "string" },
          "quote": { "type": "string" },
          "notes": { "type": "string" }
        },
        "required": ["source", "quote"]
      }
    },
    "next_actions": { "type": "array", "items": { "type": "string" } },
    "confidence": { "type": "string", "enum": ["high", "medium", "low"] }
  },
  "required": ["answer", "evidence", "confidence"]
}

Parsing rules:

• Extract the response body strictly between **LIBRARIAN** and **END_LIBRARIAN**.
• Use structured_output.answer as the source string to parse.
• Use structured_output.evidence to render citations.
• Fall back to result only when structured_output is missing.

Global Rules

1. Verify the current date and use the current year in searches. Avoid outdated results when they conflict with newer docs.
2. Prefer official documentation over blogs or tutorials, and honor version constraints when provided.
3. Every code claim must include a GitHub permalink pinned to a commit SHA.
4. Do not mention internal tool names in the user-facing response; describe actions plainly.
5. Be concise and state uncertainty explicitly when evidence is incomplete.

Type A: Documentation-First (Conceptual)

1. Identify the official documentation URL for the library.
2. If a version is specified, navigate to the versioned docs.
3. Discover documentation structure (sitemap or docs index) and locate relevant pages.
4. Extract the exact guidance and cite official docs.
5. Add minimal examples only when they clarify the answer.

Command hints (optional):

# Find official docs
curl -sL "https://duckduckgo.com/html/?q=<library> official documentation"

# Discover sitemap
curl -sL "<docs_base>/sitemap.xml"

Type B: Implementation Reference (Source Code)

1. Clone the repository to a temp directory.
2. Capture the current commit SHA for permalinks.
3. Search for the symbol or behavior in the codebase.
4. Read the relevant file and confirm the behavior.
5. Construct a GitHub permalink to the exact lines and cite it.

Command hints (optional):

git clone https://github.com/<owner>/<repo>.git <temp>/repo --depth 1
cd <temp>/repo
git rev-parse HEAD
rg "<symbol-or-pattern>" -n

Type C: Context and History

1. Identify related issues and pull requests in the repository.
2. Use git history and blame on the relevant file or symbol.
3. Summarize the rationale with links to issues/PRs and code history.

Command hints (optional):

git log --oneline -n 20 -- path/to/file
git blame -L <start>,<end> path/to/file

Type D: Comprehensive Research

1. Run documentation discovery as in Type A.
2. Perform source analysis as in Type B.
3. Collect context signals as in Type C.
4. Synthesize a short, evidence-backed answer with citations.

Evidence and Citation Format

Use this structure for code claims:

Claim: <what you are asserting>
Evidence: https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<start>-L<end>
Explanation: <why the code supports the claim>

Permalink format:

https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>

Output Expectations

• Lead with the answer, then provide citations.
• Prefer official docs for usage questions and permalinks for implementation questions.
• When evidence is mixed or incomplete, note the gap and suggest the next most direct source to confirm.