| name | docs-gap |
| description | Use when analyzing release branch changes for missing user-facing documentation. Compares the release branch against devel, filters for user-facing changes, scans v3-docs/docs/ for coverage, and produces a gap report (.md file) with prioritized documentation opportunities. Does NOT write documentation — only identifies gaps and outputs a plan for later action. |
Documentation Gap Analysis
Analyze release changes and identify missing user-facing documentation. Produces a gap report as a .md file for later action — does not write the documentation itself.
Branching Model
Releases are prepared on release-<VERSION> branches. The main development branch is devel.
- Change scope = all changes on
release-<VERSION> that are not on devel
- Always compare against
devel to determine what is new in the release
- Use
git log devel..HEAD when on the release branch
This is the same branching model used by the changelog and version-bump skills.
Step 1: Gather Release Changes
Fetch merged PRs targeting the release branch:
Primary — gh CLI:
gh pr list --repo meteor/meteor \
--base release-<VERSION> \
--state merged \
--limit 200 \
--json number,title,labels,author,body,url
Fallback — git log:
git log --oneline devel..HEAD --merges | grep -oP '#\K[0-9]+'
Then fetch details per PR with gh pr view.
Step 2: Filter to Release-Relevant Changes
Apply the same inclusion rules as the changelog skill.
Include only PRs that touch:
tools/ — CLI and build systempackages/ — core Meteor packagesnpm-packages/ — published @meteorjs/* packagesscripts/ — dev bundle build scripts
Exclude PRs that are:
- Docs-only (touching only
docs/, v3-docs/, guide/)
- CI/test-infrastructure-only (
.github/workflows/, E2E harness)
- Release tooling only (version bumps, changelog generation)
- Dependabot PRs unless they bump a user-visible dependency
- Internal refactors with no user-facing impact
Step 3: Classify Changes for Documentation Potential
Not all release changes need documentation. Classify each included PR:
High Priority (likely needs docs)
| Change Type | Signal | Expected Doc Section |
|---|
| New package | New packages/*/package.js created | packages/ — new article |
| New CLI command or option | Changes to tools/cli/commands.js adding new commands/flags | cli/ — update or new section |
| New skeleton or template | New entries in tools/static-assets/ | about/ — getting started update |
| New integration or bundler feature | Changes to packages/rspack/, packages/tools-core/, npm-packages/meteor-rspack/ | about/modern-build-stack/ — update or new article |
| Breaking change | PR title/body mentions "breaking", "removed", "renamed" | Relevant section + migration note |
Medium Priority (may need docs)
| Change Type | Signal | Expected Doc Section |
|---|
| New feature in existing package | New exports, new methods, new options | packages/ — update existing article |
| Behavior change | Changed defaults, new error messages | packages/ or troubleshooting/ |
| Performance improvement (user-actionable) | New config option or recommended pattern | performance/ |
Low Priority (usually no docs needed)
| Change Type | Signal | Expected Doc Section |
|---|
| Bug fix | Fix to existing behavior, no API change | Usually none — unless the bug was a known issue in troubleshooting/ |
| Internal optimization | No user-visible change | None |
| Type definition fix | .d.ts changes only | None |
Skip low-priority items in the gap report unless they fix a documented known issue.
Step 4: Scan Existing Documentation for Coverage
For each high and medium priority change, search v3-docs/docs/ for existing coverage.
Search Strategy
For each PR, extract keywords from:
- PR title (e.g., "Rspack CSS delegation", "TypeScript Tailwind skeleton")
- Package name (e.g.,
accounts-base, rspack)
- Feature name (e.g.,
swc.config.ts, getUserIdsInRoleAsync)
Then search:
grep -rl "<keyword>" v3-docs/docs/ --include="*.md"
grep -rl "<package-name>" v3-docs/docs/ --include="*.md"
Documentation Scope (In-Scope Sections)
Only scan and report on user-facing documentation sections:
| Section | Path | What It Covers |
|---|
| About / Quick Start | v3-docs/docs/about/ | Getting started, install, concepts, modern build stack |
| Packages | v3-docs/docs/packages/ | Official package guides |
| CLI | v3-docs/docs/cli/ | Command-line reference |
| Tutorials | v3-docs/docs/tutorials/ | Step-by-step framework guides |
| Troubleshooting | v3-docs/docs/troubleshooting/ | Common issues and solutions |
| Performance | v3-docs/docs/performance/ | Optimization guides |
| Community Packages | v3-docs/docs/community-packages/ | Third-party package docs |
Out-of-Scope Sections (Do NOT Report Gaps For)
| Section | Path | Why Excluded |
|---|
| API Reference | v3-docs/docs/api/ | Auto-generated from JSDoc — separate concern |
| Generators | v3-docs/docs/generators/ | Build tooling for the doc site |
| JSDoc | v3-docs/docs/jsdoc/ | JSDoc configuration |
| Components | v3-docs/docs/components/ | Vue components for doc site |
| Data / Search / Public | v3-docs/docs/data/, search/, public/ | Site infrastructure |
Coverage Assessment
For each change, classify as:
- Documented — existing docs cover the feature adequately (file path + relevant section)
- Partially documented — feature is mentioned but not fully explained (file path + what's missing)
- Not documented — no docs found for this change
Step 5: Produce the Gap Report
Output a .md file at docs/plans/<DATE>-docs-gap-<VERSION>.md with this structure:
# Documentation Gap Report: v<VERSION>
**Generated:** <DATE>
**Branch:** release-<VERSION> vs devel
**PRs analyzed:** <COUNT>
**Gaps found:** <COUNT>
---
## Already Documented
Changes that have adequate documentation coverage.
| PR | Change | Doc File | Notes |
|----|--------|----------|-------|
| [PR#NNN](url) | Description | `v3-docs/docs/path/file.md` | Covered in section X |
---
## Partially Documented
Changes mentioned in docs but needing updates.
| PR | Change | Doc File | What's Missing |
|----|--------|----------|---------------|
| [PR#NNN](url) | Description | `v3-docs/docs/path/file.md` | Missing: new option X, updated example |
---
## Not Documented
Changes with no corresponding documentation.
### High Priority
| PR | Change | Suggested Action |
|----|--------|-----------------|
| [PR#NNN](url) | Description | Create `v3-docs/docs/section/file.md` — describe X for end users |
### Medium Priority
| PR | Change | Suggested Action |
|----|--------|-----------------|
| [PR#NNN](url) | Description | Update `v3-docs/docs/section/file.md` — add section about Y |
---
## Summary
- **Total user-facing changes:** N
- **Documented:** N
- **Partially documented:** N
- **Not documented:** N (high: N, medium: N)
Prioritization
Rank gaps in this order:
- New features / new packages — users cannot discover these without docs
- Breaking changes — users need migration guidance
- New CLI commands/options — users need to know they exist
- New integrations / build features — expanding ecosystem
- Behavior changes — users may be surprised
- Performance improvements — only if user-actionable (e.g., new config)
Bug fixes and internal optimizations generally do not need documentation.
Writing Guidelines for Suggested Actions
When describing what documentation to write in the gap report, keep suggestions user-friendly:
Do:
- Frame from the user's perspective ("How to use X", "Getting started with Y")
- Suggest practical examples and code snippets
- Reference existing doc patterns in the same section
- Suggest updating existing articles before creating new ones
Don't:
- Suggest documenting internal implementation details
- Suggest documenting private APIs or internal methods
- Frame documentation as technical specs
- Suggest documentation for changes only relevant to Meteor contributors
Preserving Style and Integration
When the gap report is used to write documentation, the new content must feel native to the existing docs — not bolted on. Each suggested action in the report should include guidance on how to integrate cleanly:
- Read the target file first. Before suggesting where to add content, note the writing style, heading levels, use of components (e.g.,
<ApiBox>), code example format, and tone.
- Match the surrounding pattern. If nearby sections use a brief intro paragraph followed by a code block and a tip, follow the same structure. If they use bullet lists, use bullet lists.
- Find the right spot. Place new content next to related existing content — not appended at the end. For example, a new API method goes next to similar methods; a new framework section goes alongside the other framework sections.
- Use the same components. If the doc uses
<ApiBox>, :::warning, :::info, code groups, or other VitePress/Vue components, use them for new content too.
- Preserve categorization. New package docs go in
packages/, new CLI options go in cli/, new getting-started content goes in about/. Do not create new top-level sections unless no existing section fits.
Review Checklist
Before finalizing the gap report:
