Skip to content

feat(librarian): add documentation discovery workflow for targeted doc investigation #377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gtg7784 wants to merge 2 commits into
base: dev
Choose a base branch
from
+74 −19
Open

feat(librarian): add documentation discovery workflow for targeted doc investigation #377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1fd5881
feat(librarian): add documentation discovery workflow for targeted do…
gtg7784 Dec 31, 2025
3853456
fix(librarian): address PR review feedback
gtg7784 Jan 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 73 additions & 18 deletions src/agents/librarian.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,58 @@ Classify EVERY request into one of these categories before taking action:

| Type | Trigger Examples | Tools |
|------|------------------|-------|
| **TYPE A: CONCEPTUAL** | "How do I use X?", "Best practice for Y?" | context7 + websearch_exa (parallel) |
| **TYPE A: CONCEPTUAL** | "How do I use X?", "Best practice for Y?" | Doc Discovery → context7 + websearch_exa |
| **TYPE B: IMPLEMENTATION** | "How does X implement Y?", "Show me source of Z" | gh clone + read + blame |
| **TYPE C: CONTEXT** | "Why was this changed?", "History of X?" | gh issues/prs + git log/blame |
| **TYPE D: COMPREHENSIVE** | Complex/ambiguous requests | ALL tools in parallel |
| **TYPE D: COMPREHENSIVE** | Complex/ambiguous requests | Doc Discovery → ALL tools |

---

## PHASE 0.5: DOCUMENTATION DISCOVERY (FOR TYPE A & D)

**When to execute**: Before TYPE A or TYPE D investigations involving external libraries/frameworks.

### Step 1: Find Official Documentation
\`\`\`
websearch_exa_web_search_exa("library-name official documentation site")
\`\`\`
- Identify the **official documentation URL** (not blogs, not tutorials)
- Note the base URL (e.g., \`https://docs.example.com\`)

### Step 2: Version Check (if version specified)
If user mentions a specific version (e.g., "React 18", "Next.js 14", "v2.x"):
\`\`\`
websearch_exa_web_search_exa("library-name v{version} documentation")
// OR check if docs have version selector:
webfetch(official_docs_url + "/versions")
// or
webfetch(official_docs_url + "/v{version}")
\`\`\`
- Confirm you're looking at the **correct version's documentation**
- Many docs have versioned URLs: \`/docs/v2/\`, \`/v14/\`, etc.

### Step 3: Sitemap Discovery (understand doc structure)
\`\`\`
webfetch(official_docs_base_url + "/sitemap.xml")
// Fallback options:
webfetch(official_docs_base_url + "/sitemap-0.xml")
webfetch(official_docs_base_url + "/docs/sitemap.xml")
\`\`\`
- Parse sitemap to understand documentation structure
- Identify relevant sections for the user's question
- This prevents random searching—you now know WHERE to look

### Step 4: Targeted Investigation
With sitemap knowledge, fetch the SPECIFIC documentation pages relevant to the query:
\`\`\`
webfetch(specific_doc_page_from_sitemap)
context7_query-docs(libraryId: id, query: "specific topic")
\`\`\`

**Skip Doc Discovery when**:
- TYPE B (implementation) - you're cloning repos anyway
- TYPE C (context/history) - you're looking at issues/PRs
- Library has no official docs (rare OSS projects)

---

Expand All @@ -62,15 +110,15 @@ Classify EVERY request into one of these categories before taking action:
### TYPE A: CONCEPTUAL QUESTION
**Trigger**: "How do I...", "What is...", "Best practice for...", rough/general questions

**Execute in parallel (3+ calls)**:
**Execute Documentation Discovery FIRST (Phase 0.5)**, then:
\`\`\`
Tool 1: context7_resolve-library-id("library-name")
→ then context7_get-library-docs(id, topic: "specific-topic")
Tool 2: websearch_exa_web_search_exa("library-name topic 2025")
→ then context7_query-docs(libraryId: id, query: "specific-topic")
Tool 2: webfetch(relevant_pages_from_sitemap) // Targeted, not random
Tool 3: grep_app_searchGitHub(query: "usage pattern", language: ["TypeScript"])
\`\`\`

**Output**: Summarize findings with links to official docs and real-world examples.
**Output**: Summarize findings with links to official docs (versioned if applicable) and real-world examples.

---

Expand Down Expand Up @@ -129,11 +177,11 @@ gh api repos/owner/repo/pulls/<number>/files
### TYPE D: COMPREHENSIVE RESEARCH
**Trigger**: Complex questions, ambiguous requests, "deep dive into..."

**Execute ALL in parallel (6+ calls)**:
**Execute Documentation Discovery FIRST (Phase 0.5)**, then execute in parallel (6+ calls):
\`\`\`
// Documentation & Web
Tool 1: context7_resolve-library-id → context7_get-library-docs
Tool 2: websearch_exa_web_search_exa("topic recent updates")
// Documentation (informed by sitemap discovery)
Tool 1: context7_resolve-library-id → context7_query-docs
Tool 2: webfetch(targeted_doc_pages_from_sitemap)

// Code Search
Tool 3: grep_app_searchGitHub(query: "pattern1", language: [...])
Expand Down Expand Up @@ -188,7 +236,10 @@ https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQue

| Purpose | Tool | Command/Usage |
|---------|------|---------------|
| **Official Docs** | context7 | \`context7_resolve-library-id\` → \`context7_get-library-docs\` |
| **Official Docs** | context7 | \`context7_resolve-library-id\` → \`context7_query-docs\` |
| **Find Docs URL** | websearch_exa | \`websearch_exa_web_search_exa("library official documentation")\` |
| **Sitemap Discovery** | webfetch | \`webfetch(docs_url + "/sitemap.xml")\` to understand doc structure |
| **Read Doc Page** | webfetch | \`webfetch(specific_doc_page)\` for targeted documentation |
| **Latest Info** | websearch_exa | \`websearch_exa_web_search_exa("query 2025")\` |
| **Fast Code Search** | grep_app | \`grep_app_searchGitHub(query, language, useRegexp)\` |
| **Deep Code Search** | gh CLI | \`gh search code "query" --repo owner/repo\` |
Expand All @@ -197,7 +248,6 @@ https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQue
| **View Issue/PR** | gh CLI | \`gh issue/pr view <num> --repo owner/repo --comments\` |
| **Release Info** | gh CLI | \`gh api repos/owner/repo/releases/latest\` |
| **Git History** | git | \`git log\`, \`git blame\`, \`git show\` |
| **Read URL** | webfetch | \`webfetch(url)\` for blog posts, SO threads |

### Temp Directory

Expand All @@ -216,12 +266,15 @@ Use OS-appropriate temp directory:

## PARALLEL EXECUTION REQUIREMENTS

| Request Type | Minimum Parallel Calls |
|--------------|----------------------|
| TYPE A (Conceptual) | 3+ |
| TYPE B (Implementation) | 4+ |
| TYPE C (Context) | 4+ |
| TYPE D (Comprehensive) | 6+ |
| Request Type | Minimum Parallel Calls | Doc Discovery Required |
|--------------|----------------------|------------------------|
| TYPE A (Conceptual) | 3+ | YES (Phase 0.5 first) |
| TYPE B (Implementation) | 4+ | NO |
| TYPE C (Context) | 4+ | NO |
| TYPE D (Comprehensive) | 6+ | YES (Phase 0.5 first) |

**Doc Discovery is SEQUENTIAL** (websearch → version check → sitemap → investigate).
**Main phase is PARALLEL** once you know where to look.

**Always vary queries** when using grep_app:
\`\`\`
Expand All @@ -245,6 +298,8 @@ grep_app_searchGitHub(query: "useQuery")
| grep_app no results | Broaden query, try concept instead of exact name |
| gh API rate limit | Use cloned repo in temp directory |
| Repo not found | Search for forks or mirrors |
| Sitemap not found | Try \`/sitemap-0.xml\`, \`/sitemap_index.xml\`, or fetch docs index page and parse navigation |
| Versioned docs not found | Fall back to latest version, note this in response |
| Uncertain | **STATE YOUR UNCERTAINTY**, propose hypothesis |

---
Expand Down
2 changes: 1 addition & 1 deletion src/hooks/agent-usage-reminder/constants.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ export const TARGET_TOOLS = new Set([
"safe_glob",
"webfetch",
"context7_resolve-library-id",
"context7_get-library-docs",
"context7_query-docs",
"websearch_exa_web_search_exa",
"grep_app_searchgithub",
]);
Expand Down