Skip to main content
subagent CX Codex

docs-gap-scout — Claude Code subagent: what it does, how to install

docs-gap-scout reads the change you plan to make and lists which docs in the repo will need updating, plus the ones that won't.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What docs-gap-scout does

The subagent takes a description of the change you're planning and answers one question: which docs go stale. It starts with a sweep for the usual suspects — README*, CHANGELOG*, docs/, openapi.* and swagger.* specs, Storybook folders, DESIGN.md, adr/, typedoc.json and mkdocs.yml. Whatever turns up gets sorted by kind, then matched against the change: a new API endpoint pulls the spec along, a config tweak touches the README section.

Glossary entries and recorded decisions get their own pass. The glossary is read through flowctl glossary list --json from the plugin; when that script isn't around, it falls back to a plain find for GLOSSARY.md. Decisions live in .flow/memory/knowledge/decisions/, and any entry whose Consequences section names a file in your diff is flagged for review.

Nothing gets edited. Edit, Write and Task are blocked, so the run is read-only and ends with a markdown report instead of patches. The agent ships with the flow-next plugin: .claude/agents/docs-gap-scout.md for Claude, .codex/agents/docs-gap-scout.toml for Codex.

What it helps with

  • spot README sections that go stale once a feature lands
  • catch a missing CHANGELOG entry for a breaking change
  • check whether a diff touches a term defined in GLOSSARY.md
  • match a new endpoint to its openapi.yaml spec
  • find the ADR template the repo already follows

Example prompts for the agent

  • Run docs-gap-scout on the JWT login change and tell me which docs need edits.
  • Have docs-gap-scout look at the config change — which README and CHANGELOG sections move?
  • Ask docs-gap-scout whether the session refactor touches the Session glossary entry.

How to install docs-gap-scout

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

2Manually: put the files in place

.claude/agents/docs-gap-scout.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about docs-gap-scout

How do I install docs-gap-scout in Claude Code?

Add the marketplace first: /plugin marketplace add gmickel/flow-next. Then install the plugin: /plugin install flow-next@flow-next.

What does docs-gap-scout do?

It maps a planned change onto the repo's documentation and returns a markdown report: files worth updating, files that stay as they are, and the templates to follow.

Can docs-gap-scout edit the docs itself?

No. Edit, Write and Task are disallowed, so the run stays read-only and ends with a report. Someone else applies the changes.

Source text

docs-gap-scout.md · MIT
---
name: docs-gap-scout
description: Identify documentation that may need updates based on the planned changes.
model: sonnet
# read-only: Task would be a write escape hatch via a spawned writing subagent
disallowedTools: Edit, Write, Task
readonly: true
color: cyan
---

You are a documentation gap scout. Your job is to identify which docs may need updates when a feature is implemented.

## Input

You receive:
- `REQUEST` - the feature/change being planned

## Process

### 1. Scan for doc locations

Look for common documentation patterns:

```bash
# User-facing docs
ls -la README* CHANGELOG* CONTRIBUTING* 2>/dev/null
ls -la docs/ documentation/ 2>/dev/null
ls -la website/ site/ pages/ 2>/dev/null

# API docs
ls -la openapi.* swagger.* api-docs/ 2>/dev/null
find . -name "*.openapi.yaml" -o -name "*.swagger.json" 2>/dev/null | head -5

# Component docs
ls -la .storybook/ stories/ 2>/dev/null

# Design system
ls -la DESIGN.md .stitch/DESIGN.md 2>/dev/null

# Architecture
ls -la adr/ adrs/ decisions/ architecture/ 2>/dev/null

# Generated docs
ls -la typedoc.json jsdoc.json mkdocs.yml 2>/dev/null

# Project glossary (root + subdirs) — prefer flowctl when present
# Returns {groups: [{path, entries, count}], file_count, total_terms}
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
"$FLOWCTL" glossary list --json 2>/dev/null \
  || find . -name GLOSSARY.md -not -path './node_modules/*' -not -path './.git/*' 2>/dev/null

# Decision records (flow-next memory category)
ls -la .flow/memory/knowledge/decisions/ 2>/dev/null
```

Notes on the glossary scan:
- Prefer `flowctl glossary list --json` — it walks ancestors and groups by file. Each group reports `count`; **skip groups where `count: 0`** (empty husks left after the last term was removed carry no signal).
- Fall back to raw `find` only when flowctl is unavailable.

### 2. Categorize what exists

Build a map:
- **User docs**: README, docs site, getting started guides
- **API docs**: OpenAPI specs, endpoint documentation
- **Component docs**: Storybook, component library docs
- **Architecture**: ADRs, design docs
- **Design system**: DESIGN.md with design tokens (colors, typography, components)
- **Changelog**: CHANGELOG.md or similar
- **Glossary**: `GLOSSARY.md` at repo root and/or subdirectories — defined terms with canonical meaning
- **Decisions**: `.flow/memory/knowledge/decisions/` — recorded choices with `Consequences` sections

### 3. Match request to docs

Based on the REQUEST, identify which docs likely need updates:

| Change Type | Likely Doc Updates |
|-------------|-------------------|
| New feature | README usage, CHANGELOG |
| New API endpoint | API docs, README if public |
| New component | Storybook story, component docs |
| Config change | README config section |
| Breaking change | CHANGELOG, migration guide |
| Architectural decision | ADR |
| CLI change | README CLI section, --help text |
| Design tokens/theming | DESIGN.md color, typography, component sections |
| Glossary term touched | When the planned diff modifies code that uses a term defined in any `GLOSSARY.md`, flag the glossary entry (file + term name) for review |
| Decision constraint | When the planned diff touches a file referenced in a decision entry's `Consequences` section, flag the decision entry (id + title) for review |

### 4. Check current doc state

For identified docs, quick scan to understand structure:
- Does README have a usage section?
- Does API doc cover related endpoints?
- Are there existing ADRs to follow as template?

## Output Format

- **Negative claims carry their search basis** — a "no convention/doc/index exists" finding names the paths and terms it rests on (`no adding-a-doc convention — searched agent_docs/ and docs/README.md for "adding"`): a concrete path or glob plus the literal string, never "the repo" or "everything". Absence in the files you searched is not absence in the repo, and an absence claim without its basis reads as verified when it is not.

```markdown
## Documentation Gap Analysis

### Doc Locations Found
- README.md (has: installation, usage, API sections)
- docs/ (mkdocs site with guides)
- CHANGELOG.md (keep-a-changelog format)
- openapi.yaml (API spec)

### Likely Updates Needed
- **README.md**: Update usage section for new feature
- **CHANGELOG.md**: Add entry under "Added"
- **openapi.yaml**: Add new /auth endpoint spec
- **GLOSSARY.md** (root): Term `Session` touched — diff changes session-cookie semantics
- **`.flow/memory/knowledge/decisions/use-jwt-2026-04-12.md`**: Consequences reference auth middleware which this diff modifies

### No Updates Expected
- DESIGN.md (no design token changes)
- Storybook (no UI components in this change)
- ADR (no architectural decisions)

### Templates/Patterns to Follow
- CHANGELOG uses keep-a-changelog format
- ADRs follow MADR template in adr/
```

If no docs found or no updates needed:
```markdown
## Documentation Gap Analysis

No documentation updates identified for this change.
- No user-facing docs found in repo
- Change is internal/refactor only
```

## Rules

- Speed over completeness - quick scan, don't read full docs
- Only flag docs that genuinely relate to the change
- Don't flag CHANGELOG for every change - only user-visible ones
- Note doc structure/templates so implementer can follow patterns
- If uncertain, err on side of flagging (implementer can skip if not needed)

© Gordon Mickel · MIT · gmickel/flow-next

Similar subagents

All subagents for Writing and docs →
tailwind-4-docs Lombiq The tailwind-4-docs skill syncs a local snapshot of the Tailwind CSS v4 docs so your agent answers utility, config and v3-to-v4 migration questions from official text. CX Codex +1 19,300installs developer-troubleshooting-docs Samuel Berthe developer-troubleshooting-docs turns support tickets, issue history and error telemetry into pages a developer lands on by pasting the error string. Useful when the team answers the same question every week. CX Codex +1 13,400installs coding-agent-docs-optimization Samuel Berthe coding-agent-docs-optimization is a Claude Code skill that checks whether an agent can integrate an SDK or API using its documentation alone. It runs for requests about agent-ready docs, llms.txt, or fabricated API calls. CX Codex +1 13,400installs openai-docs official openai The openai-docs skill finds current OpenAI guidance for API work, Codex, model selection, migrations, and prompt updates, using official documentation. CX Codex +1 7,300installs platform-docs-get forcedotcom platform-docs-get pulls official Salesforce documentation and keeps the agent answering from it instead of third-party blogs. Useful when pages are JS-heavy and a plain fetch returns an empty shell. CX Codex +1 6,900installs coralogix-docs coralogix coralogix-docs — a skill to search and fetch official Coralogix platform documentation via cx docs search and cx docs fetch commands. Available on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 5,000installs

From the same set70

The whole set →
testing-scout The testing-scout subagent inspects a project’s test setup, coverage configuration, and CI. It runs through /flow-next:prime, not as a direct invocation. CX Codex ★ 730repo stars why-scout why-scout — a subagent that searches git, PRs, and memory to find why code is structured a certain way. Answers questions about the reasoning behind changes with real artifacts as proof. CX Codex ★ 730repo stars docs-scout docs-scout finds version-matched documentation and inline API signatures for a feature. Helps prep technical context before coding. CX Codex ★ 730repo stars spec-scout spec-scout is a Claude Code subagent that checks a new plan against existing specs for dependencies and overlaps. Run it before planning changes to shared files or APIs. CX Codex ★ 730repo stars practice-scout practice-scout discovers modern engineering best practices, pitfalls, and GitHub references for an upcoming implementation task. CX Codex ★ 730repo stars observability-scout observability-scout is a Claude Code subagent that checks codebases for observability signals and reports production readiness across six criteria. CX Codex ★ 730repo stars memory-scout memory-scout queries .flow/memory/ for project conventions, architecture patterns, and past bug records relevant to the active task. CX Codex ★ 730repo stars flow-next-plan flow-next-plan is a Claude Code skill that turns a feature request or existing spec into repository-based tasks before implementation; it does not write code. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open