/doc-research

name: doc-research
description: Public documentation extraction methodology. Search sequence (3 tiers), behavioral claim extraction rules, output structure, termination criteria, and gap analysis. Loaded by the analyzer agent for documentation research.

Documentation Research Methodology

This skill defines the complete methodology for extracting behavioral specifications from public documentation. Follow it step by step. Every section is normative.

1. Search Sequence

Search proceeds from most authoritative to least authoritative. Execute every pattern in each tier before moving to the next tier.

digraph search_sequence {
    rankdir=TB;

    "Start documentation research" [shape=doublecircle];
    "Search Tier 1: Official documentation" [shape=box];
    "Traverse full official site structure" [shape=box];
    "Search Tier 2: Machine-readable specs" [shape=box];
    "Search Tier 3: Community knowledge" [shape=box];
    "Diminishing returns?" [shape=diamond];
    "Page budget exhausted?" [shape=diamond];
    "Write claims file and gaps file" [shape=box];
    "Run gap analysis by product type" [shape=box];
    "Research complete" [shape=doublecircle];

    "Start documentation research" -> "Search Tier 1: Official documentation";
    "Search Tier 1: Official documentation" -> "Traverse full official site structure";
    "Traverse full official site structure" -> "Search Tier 2: Machine-readable specs";
    "Search Tier 2: Machine-readable specs" -> "Search Tier 3: Community knowledge";
    "Search Tier 3: Community knowledge" -> "Diminishing returns?";
    "Diminishing returns?" -> "Write claims file and gaps file" [label="yes"];
    "Diminishing returns?" -> "Page budget exhausted?" [label="no"];
    "Page budget exhausted?" -> "Write claims file and gaps file" [label="yes"];
    "Page budget exhausted?" -> "Search Tier 3: Community knowledge" [label="no, continue"];
    "Write claims file and gaps file" -> "Run gap analysis by product type";
    "Run gap analysis by product type" -> "Research complete";
}

Tier 1: Official Documentation (source type: `official-docs`)

Execute these search patterns in order. Replace `{product}` with the target product name and `{domain}` with the official domain if known.

| # | Search Pattern | Purpose | |---|----------------|---------| | 1 | `{product} documentation` | Main documentation site | | 2 | `{product} API reference` | API surface | | 3 | `{product} getting started` | Installation, first run, quick setup | | 4 | `{product} configuration reference` | Config files, keys, defaults | | 5 | `{product} CLI reference` | Commands, flags, arguments | | 6 | `{product} changelog` | Version history, behavioral changes | | 7 | `{product} release notes` | Feature additions, breaking changes | | 8 | `{product} migration guide` | Version-to-version behavioral differences | | 9 | `{product} FAQ` | Common behavioral questions and answers | | 10 | `{product} troubleshooting` | Error conditions and resolutions | | 11 | `{product} security` | Auth, encryption, permissions | | 12 | `site:{domain} {product}` | Catch pages not found by keyword search |

After finding the official documentation site, traverse its full structure:

• Fetch the table of contents, sitemap, or sidebar navigation.
• Queue every linked page that has not already been fetched.
• Follow "next page" and pagination links.

Tier 2: Machine-Readable Specifications (source type: `official-docs`)

Execute the patterns relevant to the target product type. Not all patterns apply to all products.

| # | Search Pattern | Applies When | |---|----------------|--------------| | 1 | `{product} openapi` or `{product} swagger` | Product has a REST API | | 2 | `{product} graphql schema` | Product has a GraphQL API | | 3 | `{product} protobuf` or `{product} grpc` | Product uses protocol buffers | | 4 | `{product} json schema` | Product defines data formats | | 5 | `{product} man page` | Product is a CLI tool on Unix | | 6 | `{product} --help` | Product is a CLI tool | | 7 | `{product} wsdl` | Product has a SOAP API |

Machine-readable specs are higher value than prose because they are precise and unambiguous. When a machine-readable spec exists, it takes precedence over prose documentation for the same topic.

Tier 3: Community Knowledge (source type: `community-knowledge`)

| # | Search Pattern | Purpose | |---|----------------|---------| | 1 | `{product} site:stackoverflow.com` | Community Q&A about behavior | | 2 | `{product} site:github.com discussions` | Maintainer and community discussions | | 3 | `{product} blog` (filter for maintainer blogs) | Design rationale, behavioral explanations | | 4 | `{product} tutorial` (filter for expert content) | Practical behavioral descriptions |

Community sources are valuable for:

• Behaviors that official docs fail to document
• Edge cases discovered by users
• Practical workarounds that reveal behavioral constraints
• Corroborating claims from official docs (upgrades confidence to `confirmed`)

Community sources are NOT authoritative for:

• Exact parameter values or limits (may be outdated)
• Version-specific behavior (community content may describe a different version)
• Internal implementation details (community speculation is not evidence)

Prioritization

When the same behavioral information appears in multiple sources, prefer:

1. Official API reference over tutorials 2. Latest version documentation over older versions 3. Machine-readable specifications over prose 4. Maintainer content over community content 5. Specific documentation (configuration reference) over general documentation (overview)

2. Fetching Rules

Rate Limiting

• Insert at least 2 seconds between consecutive fetches to the same domain.
• On HTTP 429, respect the `Retry-After` header. If no header is present, wait 30 seconds.
• Maximum 3 retries per URL. After 3 failures, record the URL in `gaps.md` and move on.

Content Handling

• Convert fe