Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

docs-gap

/docs-gap

Analizuje zmiany gałęzi wydania pod kątem brakującej dokumentacji dla użytkownika i tworzy raport luk z priorytetami w pliku .md, bez pisania samej dokumentacji.

Repozytorium
meteor ↗
Licencja
MIT
Ostatnia zmiana repozytorium
24.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 24.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Analizuje zmiany gałęzi wydania pod kątem brakującej dokumentacji dla użytkownika i tworzy raport luk z priorytetami w pliku .md, bez pisania samej dokumentacji.

Oryginalny opis (EN)

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.

Jak działa

  1. Branching Model
  2. Step 1: Gather Release Changes
  3. Step 2: Filter to Release-Relevant Changes
  4. Step 3: Classify Changes for Documentation Potential
  5. Step 4: Scan Existing Documentation for Coverage
  6. Step 5: Produce the Gap Report
  7. Prioritization
  8. Writing Guidelines for Suggested Actions
  9. Review Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 270 linii, 1 465 słów
Podgląd SKILL.md
---
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](../changelog/SKILL.md) and [version-bump](../version-bump/SKILL.md) skills.

---

## Step 1: Gather Release Changes

Fetch merged PRs targeting the release branch:

**Primary — `gh` CLI:**

```bash
gh pr list --repo meteor/meteor \
  --base release-<VERSION> \
  --state merged \
  --limit 200 \
  --json number,title,labels,author,body,url
```

**Fallback — git log:**

```bash
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 system
* `packages/` — core Meteor packages
* `npm-packages/` — published `@meteorjs/*` packages
* `scripts/` — 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:

```bash
# Search by feature keyword
grep -rl "<keyword>" v3-docs/docs/ --include="*.md"

# Search by package name
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:

````markdown
# 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:

1. **New features / new packages** — users cannot discover these without docs
2. **Breaking changes** — users need migration guidance
3. **New CLI commands/options** — users need to know they exist
4. **New integrations / build features** — expanding ecosystem
5. **Behavior changes** — users may be surprised
6. **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:

- [ ] All high and medium priority PRs have been assessed
- [ ] Each "Not Documented" item has a concrete suggested action (file path + description)
- [ ] "Partially Documented" items specify what exactly is missing
- [ ] No low-priority items (pure bug fixes, internal refactors) are included unless they fix a documented known issue
- [ ] All doc file paths in "Already Documented" are verified to exist
- [ ] Suggested new articles align with the existing doc structure and naming conventions
- [ ] Gap report is saved to `docs/plans/<DATE>-docs-gap-<VERSION>.md`

Wersje

W bazie nie ma innych skilli o nazwie docs-gap.

Migawka bazy z 13.11.2026 · wersja paczki 5e1de69361d5 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100docs-sync-audit
    Przeprowadza audyt rozjazdu dokumentacji tylko do odczytu dla funkcji, PR, gałęzi, wydania, API, konfiguracji lub CLI, sprawdzając README, przewodniki, dokumentację API, changelogi i przykłady.
  • 100news-release-docs
    Tworzy lub odświeża docs/RELEASE_HISTORY.md i docs/NEWS.md na podstawie changelogu oraz przygotowuje materiał dla devel/make_release.py przy wydaniu.
  • 100documentation
    Stosuje standardy dokumentacji przy zmianach kodu: pisze i przegląda dokumentację, docstringi i komentarze, opisuje publiczne API i zmiany widoczne dla użytkownika oraz poprawia README.
  • 100docs-sync
    Analizuje implementację i konfigurację głównej gałęzi, znajduje braki i nieaktualne fragmenty angielskiej dokumentacji w docs/ i przed edycją składa raport do zatwierdzenia.
  • 95update-docs-from-commits
    Przegląda ostatnie commity pod kątem zmian widocznych dla użytkownika i przygotowuje lub aktualizuje odpowiednie strony dokumentacji, na przykład przed wydaniem.
  • 100nvidia-nemoclaw-contributor-update-docs
    Przegląda ostatnie commity pod kątem zmian widocznych dla użytkownika, pisze lub aktualizuje strony dokumentacji i odświeża generowane skille użytkownika przy przygotowaniu wydania.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.