Skip to content
Skills Library
Programming · Review & audit

gap-scan

/gap-scan

Survey one or more repos (code, commits, docs, tests, issues) and return a ranked, evidence-cited list of gaps, bugs, and extension ideas as issue-ready items. Read-only apart from its report. Use for "what's missing", "find gaps", "what should I work on in this repo".

Repository
skills ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Survey one or more repos (code, commits, docs, tests, issues) and return a ranked, evidence-cited list of gaps, bugs, and extension ideas as issue-ready items. Read-only apart from its report. Use for "what's missing", "find gaps", "what should I work on in this repo".

Triggers from the description

whatfind gapswhat should I work on in this repo

Arguments

/gap-scan [repo path | owner/repo, ...] [--commits N]
Original author description

Survey one or more repos (code, commits, docs, tests, issues) and return a ranked, evidence-cited list of gaps, bugs, and extension ideas as issue-ready items. Read-only apart from its report. Use for "what's missing", "find gaps", "what should I work on in this repo".

How it works

  1. 1. Sync
  2. 2. Survey
  3. 3. Rank
  4. 4. Report
Original SKILL.md headings · 51 lines, 550 words
SKILL.md preview
---
name: gap-scan
description: Survey one or more repos (code, commits, docs, tests, issues) and return a ranked, evidence-cited list of gaps, bugs, and extension ideas as issue-ready items. Read-only apart from its report. Use for "what's missing", "find gaps", "what should I work on in this repo".
argument-hint: "[repo path | owner/repo, ...] [--commits N]"
---

Read-only. The one write is the report under `skilleddocs/gaps/`. Issues, comments, labels, and board changes each need an explicit yes for that action. Every `gh` call targets the repo resolved per the `next` skill's `BOARD.md`, Target repo section (`-R <o>/<r>`); on a fork, the yes for a write also names the repo it goes to.

No argument: current repo. Several: §1–3 per repo, one combined report. `--commits N` (default 20).

## 1. Sync

- Dirty = tracked changes, or untracked files outside `skilleddocs/` (`git status --porcelain -- . ':!skilleddocs'`), so this skill's own report never makes the next run dirty. Dirty → skip the pull and say so; survey as-is.
- No upstream (`git rev-parse --abbrev-ref @{u}` fails) or no remote (`git remote` prints nothing) → skip the pull, say so (`no upstream, pull skipped`); never set one yourself.
- Clean with an upstream → `git pull --ff-only`; diverged → report it like dirty.
- Fork → `git fetch upstream`; report ahead/behind; also list the parent's open `good first issue`s (`gh issue list -R <parent> --label "good first issue"`; reading the parent is fine).

## 2. Survey

- **Docs vs code**: every README/docs/roadmap claim the code contradicts (or code the docs miss), cited `doc:line` beside `code:line`.
- **Commits**: reverts, repeated fixes to one area (fragile spot), messages admitting shortcuts.
- **`TODO|FIXME|XXX`** in code, by `file:line`.
- **Tests**: find the command. Cheap (no network, GPU, paid calls, credentials) → run it, report failures. Otherwise "tests not run: <why>".
- **Open issues**: `gh issue list -R <o>/<r> --state open --json number,title,labels`. A gap matching one is **already tracked: #n**, listed but not re-proposed. `gh` can't reach issues (non-GitHub remote, not authed, no remote) → `Issues: not checked (<why>)`, and every item's status is `new (issues unchecked)`.
- **UI apps only** (frontend, served site, dashboard), with the `run` skill or a screenshot tool: screenshot the main views and note layout, spacing, style, and dead-link problems, citing screenshot + component. Otherwise "visual pass: skipped (<not a UI app | no tool>)".

## 3. Rank

Value for effort, highest first; the trade-off in one clause. Size `S` (one session, one area) or `L` (multi-area or needs a design call → `divide` candidate). **Evidence or drop it**: every item cites `file:line`, a SHA, or `#n`. A secret is cited by `file:line` or SHA only, never its value, in the report and the reply.

## 4. Report

`skilleddocs/gaps/<local-date>.md`, uncommitted unless asked. Untracked → exclude `skilleddocs/` per [TRACKING.md](../handoff-auto/TRACKING.md) so the next run's tree is clean and `pip install .` isn't broken by it. Per item:

```markdown
### <title>
- Why: <what's missing/broken and why it matters>
- Evidence: <file:line | SHA | #n>
- Size: S | L
- Suggested labels: <bug, enhancement, ...>
- Status: new | new (issues unchecked) | already tracked: #<n>
```

Chat reply:

```
Scanned <repo> (synced clean | dirty, pull skipped | no upstream, pull skipped). 12 candidates → 5 after filters.
Report: skilleddocs/gaps/<date>.md
1. [S] <title> — <why> (path/file.py:42)
2. [L] <title> — <why> (a1b2c3d)
Issues: <N open, M matched | not checked (why)>
Tests: <N passed/failed | not run: why>   Visual: <findings | skipped: why>
```

Then offer, don't run: `kanban-setup` (user-only: tell them to type `/kanban-setup`; board from this list), `divide` (split an `L`), `grill-docs` (stress-test a big call).
Files in this package (2)
  • README.md 8 KB
  • SKILL.md 4 KB

Versions

The database has no other skills named gap-scan.

Database snapshot: 13.11.2026 · package version 573e4a7dbf24 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-gap-sweeping
    Sweep one or more local repositories for implementation gaps and produce deterministic, evidence-backed remediation lanes. Use when you need cross-repo detection of missing tests, docs lockstep drift, risky TODO/FIXME additions, and release-hygiene misses.
  • 100docs-gap
    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…
  • 90find-test-gaps
    Runs the test-gap-analyzer agent on the files changed in a branch, or on a directory, and returns missing test cases as JSON. Use for CI or headless runs, for example `claude -p "/agents-virtuoso:find-test-gaps origin/main"`.
  • 90feature
    Implement a feature from a spec (docs/specs/NNN_<name>.md), a spec slice, or a GitHub issue: write the code and tests, run the checks, and stop with a working tree to review. --commit also commits; --pr also opens the PR and runs its review. Use for 'implement the auth spec',…
  • 100architecture-scan
    Scan a large codebase and produce a detailed, evidence-backed architecture document with diagrams. Use when asked to map, audit, document or explain a project's architecture.
  • 100awesome-test-gap-audit
    Read-only audit of which tests are missing, weak, stale or mis-scoped, mapped by what tests actually call, ranked P0-P3 by risk, with a verdict and a worklist for awesome-test-writing. Use when asked what tests are missing, where the coverage gaps are, or to audit a test suite.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.