pproenca/dot-skills/docs-search

Docs Search — Navigation Methodology for Official Library Documentation

Methodology distillation of the generic moves an agent makes when reaching for a library's official documentation. Not a per-library skill — one skill plus a thin per-library record in the shared knowledge graph (`/knowledge/libraries/`), because 90% of the work is the same regardless of which library you're searching.

This is the navigation layer that sits next to `library-reference-distillation`. That skill is for authoring a full library-ref rule pack when you have time to extract idioms. This skill is for just looking something up when you don't — a lighter-weight, faster-to-author alternative whose unit of growth is a ~30-line topography record, not a full rule pack.

When to Apply

Use this skill when:

• An agent needs a specific answer from a library's official documentation and "search the docs" is the next move
• The user asks "where do I find X in <library> docs?" or "did <library> change Y recently?"
• The documentation appears to match the situation but production behavior diverges
• The agent is about to Google a library question and would benefit from going to the library's own site search, llms.txt, or changelog first
• A library has been used before and a topography record exists in registry/ — read it before navigating
• A library has been used and no record exists yet — apply the methodology, then capture findings in registry/<library>.md so the next lookup is faster

This skill is not for:

• Authoring a library-reference rule pack — when you want to extract idioms and failure-gap rules into a distilled skill, use `library-reference-distillation` instead. Once a full library-ref skill exists for library X, the registry entry for X becomes redundant and should be cut.
• General web search — if the question is not about a specific library's official docs (e.g., "what's the best practice for X across the ecosystem"), this is the wrong tool.
• Reading internal/proprietary docs — no llms.txt, no public changelog, no public issues. The methodology assumes public, versioned, OSS-style documentation.

How to Use

The four categories are orthogonal moves. Match the symptom to the move:

For category overviews and ordering rationale, see `references/_sections.md`.

Rule Categories

Quick Reference

1. Choose Source

• `src-decision-tree` — Classify the question (API behavior / changelog / idiom / known-bug / migration) before picking a section; "search the docs" is not a plan
• `src-llms-txt-first` — Probe <docs-root>/llms.txt or /llms-full.txt before scraping HTML; AI-canonical format if it exists
• `src-bounded-knowledge-read` — Filename is the index: read only knowledge/libraries/<slug>.md, never scan the dir; bounds per-invocation token cost regardless of knowledge-store size

2. Match Version

• `ver-find-selector` — Find the version selector before reading any reference page; ask the user or read package.json to pin
• `ver-changelog-first` — When the question contains "since I upgraded" or "did X change", read the changelog before the reference

3. Fall Back

• `fall-known-issues` — When docs match the user's code but reality doesn't, check GitHub issues, status page, and Discord/forum for known bugs before re-reading docs
• `fall-samples-over-prose` — For "how should I structure this?" go to the examples/ dir or samples repo first; idiomatic structure lives in code, not prose

4. Capture for Reuse

• `capture-registry-record` — After a successful lookup against a new library, write the docs: section of knowledge/libraries/<library>.md so future lookups skip the discovery phase

Knowledge Store

Per-library topography records live in the repo-root shared knowledge graph at `/knowledge/libraries/`. The same files are written by `code-distill` — each skill owns one section (docs: for this skill, code: for code-distill) and never overwrites the other. See `knowledge/README.md` for the merged schema, wiki-link conventions, and the merge discipline.

The knowledge store is intentionally empty at v0.1.0. First entries are added when a real lookup demands one, not pre-emptively. If you find yourself adding a record for a library you have not actually queried, stop — wait for the real need.

Read discipline: when the user names a library, do exactly read knowledge/libraries/<slug>.md. Never scan knowledge/libraries/ to "see what's available" — the filename is the index, and lazy access is what keeps per-invocation token cost bounded regardless of knowledge-store size.

Related Skills

• `library-reference-distillation` — Authoring playbook for full library-ref rule packs (the heavier sibling); when a full library-ref skill ships for library X, retire the registry entry for X
• `radical-simplification` — The thinking layer above this skill; this skill itself is an instance of the "constrain → name the invariant" move applied to the question "how do I look this up?"
• `init` (and similar) — When the lookup is about your own codebase, that's a different problem; this skill is for external library docs

Authoring Note

These rules are load-bearing, not decorative. Each names a wrong default an agent has when reaching for documentation: treating all questions as "search docs," ignoring llms.txt, reading the latest reference page while the user is on an older version, re-reading docs when reality contradicts them, preferring narrative over code, and redoing lookup work next time. If a rule restates something a capable model already does correctly when prompted, cut it. Coverage is proven by /dev-skill:eval on real doc-lookup prompts, not by rule count. The registry grows organically as real lookups demand entries.