# Docs Research

> Comprehensive research procedure for documentation. Find source files, tests, examples, patterns, and GitHub history when researching a documentation topic.

- **Type:** Skill
- **Install:** `agentstack add skill-zio-zio-skills-docs-research`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zio](https://agentstack.voostack.com/s/zio)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [zio](https://github.com/zio)
- **Source:** https://github.com/zio/zio-skills/tree/main/writer-assistant/skills/docs-research

## Install

```sh
agentstack add skill-zio-zio-skills-docs-research
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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*/**/.scala
  Grep: "class " or "trait " or "object "
  ```
- 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:

```typescript
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:

```bash
gh search commits --repo / "" --limit 30
gh search issues  --repo / "" --limit 30
gh search prs     --repo / "" --limit 30

# For high-value items:
gh issue view  --repo / --comments
gh pr view  --repo / --comments
gh api repos///commits/
```

**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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zio](https://github.com/zio)
- **Source:** [zio/zio-skills](https://github.com/zio/zio-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zio-zio-skills-docs-research
- Seller: https://agentstack.voostack.com/s/zio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.