docs-research

name	docs-research
description	Comprehensive research procedure for documentation. Find source files, tests, examples, patterns, and GitHub history when researching a documentation topic.
allowed-tools	Read, Glob, Grep, Bash(gh:*)

Source Code Research for Documentation

Use this procedure when researching a documentation topic to understand the complete landscape of types, methods, patterns, and integrations before writing documentation.

Core Mission

Provide documentation authors with comprehensive understanding of:

• Complete public API surface (all methods, signatures, variants)
• Real-world usage patterns and composition examples
• Design decisions and architectural relationships
• Dependencies, integrations, and supported use cases
• Gaps, edge cases, and performance characteristics

Analysis Approach

1. Discovery Phase

Locate core source files:

• Use Glob and Grep to find source files for the topic:

  Glob: **/src/main/scala*/**/<TypeName>.scala
  Grep: "class <TypeName>" or "trait <TypeName>" or "object <TypeName>"
  

• For modules: identify all core types and their source file locations

Identify scope and boundaries:

• Read the full source file(s) — understand every public method, type parameter, companion object, and factory method
• Map what is public API vs. internal implementation
• Note accessibility modifiers, deprecated methods, and alternative names

2. Code Flow & Usage Tracing

Understand how the API is used:

1. Search test suites (*/src/test/scala/) for idiomatic usage patterns

   • Look for construction patterns (how objects are created)
   • Trace method call sequences and data transformations
   • Identify edge cases and boundary conditions (empty values, single elements, large inputs)
   • Document error conditions and exception handling

2. Find real-world examples

   • Glob **/examples/**/*.scala for companion examples
   • Search integration tests combining multiple types
   • Look for cross-module usages via Grep to reveal composition patterns

3. Trace type dependencies

   • Grep imports in test files to reveal the full dependency graph
   • For each public method returning a complex type, trace that type's documentation
   • Identify implicit instances and type class derivation patterns

3. Architecture & Design Analysis

Map abstraction layers and patterns:

• Identify layers: constructors → transformations → queries → finalization
• Document common patterns: builders, factories, functional chains, state management
• Note which operations are composable vs. terminal
• Understand type relationships: inheritance, composition, sealed traits vs. open hierarchies

Design rationale:

• Search GitHub history for design decisions, API evolution, known tradeoffs
• Identify any documented anti-patterns or common misconceptions

4. Documentation Landscape

Understand existing coverage:

• Check docs/reference/ and docs/ for existing documentation
• Identify what is already documented vs. gaps to address
• Note examples or patterns already documented elsewhere

Identify documentation gaps:

• Methods lacking test coverage
• Performance characteristics not captured
• Edge cases not exercised in tests
• Composition examples not yet documented

Research Workflow — Step by Step

Step 1a: Read Core Source Files

For each core type, read the full source file to understand:

• All public methods and their signatures
• Type parameters, variance, constraints
• Companion object and factory methods
• Javadoc/scaladoc comments (design intent)

Step 1b: Read Test Files

Search and read test suites to understand:

• Construction patterns and common usages
• Method chaining and composition examples
• Edge cases: empty inputs, single elements, large data
• Error handling and exception cases
• Integration with other types

Step 1c: Find Supporting Types

Identify every type that core methods depend on:

1. Grep imports in test files for the full dependency graph
2. For each supporting type, read enough source and documentation to explain it in context
3. Trace return types through multiple layers if needed

Step 1d: Search for Real-World Patterns

1. Examples directory: Glob for **/examples/**/*.scala
2. Integration tests: Look for tests combining multiple types from this module
3. Cross-module usage: Grep across other modules to find how core types integrate
4. Documentation patterns: Check if similar types have documented examples you can mirror

Step 2: GitHub History Research

Use the github-research tool (available in tools/github-research.ts) to systematically gather design rationale and context:

import {
  conductGitHubResearch,
  readIssueDetails,
  readPullRequestDetails,
} from '../tools/github-research.js';

// Comprehensive search and analysis
const findings = await conductGitHubResearch({
  repository: 'zio/zio',
  topic: 'Cached',
  limit: 30,
});

// Results organized by category:
// - findings.designRationale: Items discussing design decisions
// - findings.architectureDecisions: Items discussing architecture
// - findings.keyInsights: Performance, error handling, patterns
// - findings.commits, findings.issues, findings.prs: All results

// For high-value items, read full discussions:
const issue = findings.issues[0];
if (issue) {
  const fullDiscussion = readIssueDetails('zio/zio', parseInt(issue.id));
  // Use fullDiscussion for detailed context in research notes
}

const pr = findings.prs[0];
if (pr) {
  const fullReview = readPullRequestDetails('zio/zio', parseInt(pr.id));
  // Use fullReview for implementation context
}

Alternative (direct GitHub CLI):

If you prefer to use GitHub CLI commands directly:

gh search commits --repo <owner>/<repo> "<topic>" --limit 30
gh search issues  --repo <owner>/<repo> "<topic>" --limit 30
gh search prs     --repo <owner>/<repo> "<topic>" --limit 30

# For high-value items:
gh issue view <n> --repo <owner>/<repo> --comments
gh pr view <n> --repo <owner>/<repo> --comments
gh api repos/<owner>/<repo>/commits/<sha>

Prerequisites: gh (GitHub CLI) must be installed and authenticated.

Internal Research Notes

As you complete your research, build and maintain these internal notes (not a deliverable report, but a foundation for writing):

• Core types with fully qualified names and source file paths (with line numbers)
• Public API organized by category (constructors, transformations, queries, etc.)
• Usage patterns from tests: construction, composition, error handling
• Dependencies: which types use which other types, and why
• Real-world examples: concrete composition patterns from tests/examples
• Documentation gaps: methods with no test coverage, undocumented behavior
• Architecture insights: design patterns, abstraction layers, design decisions
• Critical files (5-10 most important files) prioritized by relevance

Purpose: These notes prepare you to write clear, accurate documentation. You do not need to emit them as a formal report—use them to guide your writing in the parent skill.

---

Design Rule

This skill targets comprehensive research for documentation. Focus on understanding what documentation authors need to write well. The research itself is scaffolding; the parent skill (data-type-ref, module-ref, how-to-guide, tutorial) owns the final documentation output.