# Code 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. Use when this capability is needed.

- Skill: `tomevault-io/code-gap-sweeping` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/code-gap-sweeping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/code-gap-sweeping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/code-gap-sweeping

---


# Code Gap Sweeping

Use this skill to run a repeatable cross-repo gap scan and convert findings into concrete follow-up actions.

## Workflow

1. Run the gap sweep script across one or more local repos.
2. Review severity-ranked findings (`critical`, `high`, `medium`).
3. Route each finding into the smallest existing skill lane that can fix it.
4. Emit machine-readable evidence for admission, planning, and release notes.
5. For repeated multi-repo operations, generate a deterministic repo-family command matrix.

## Canonical Run

```bash
python3 "$CODEX_HOME/skills/code-gap-sweeping/scripts/code_gap_sweep.py" \
  --repo "<PRIVATE_REPO_A>=/path/to/<PRIVATE_REPO_A>" \
  --repo "<PRIVATE_REPO_B>=/path/to/<PRIVATE_REPO_B>" \
  --since-days 14 \
  --json-out /tmp/code-gap-sweep.json
```

One-command sweep for all repos under a workspace root:

```bash
python3 "$CODEX_HOME/skills/code-gap-sweeping/scripts/code_gap_sweep.py" \
  --repos-root "$env:USERPROFILE\\Documents\\GitHub" \
  --exclude-repo "docs" \
  --since-days 14 \
  --json-out /tmp/code-gap-sweep-all.json
```

Working-tree focused sweep during active local edits:

```bash
python3 "$CODEX_HOME/skills/code-gap-sweeping/scripts/code_gap_sweep.py" \
  --repo "skill-arbiter=." \
  --diff-mode working-tree \
  --json-out /tmp/code-gap-sweep-working-tree.json
```

Full pipeline matrix for repo families (`repo_a`/`repo_b`/`repo_c`/`repo_d`):

```bash
python3 "$CODEX_HOME/skills/code-gap-sweeping/scripts/repo_family_pipeline.py" \
  --repo "<PRIVATE_REPO_A>=/path/to/<PRIVATE_REPO_A>" \
  --repo "<PRIVATE_REPO_B>=/path/to/<PRIVATE_REPO_B>" \
  --repo "<PRIVATE_REPO_C>=/path/to/<PRIVATE_REPO_C>" \
  --repo "<PRIVATE_REPO_D>=/path/to/<PRIVATE_REPO_D>" \
  --family "<PRIVATE_REPO_A>=repo_a" \
  --family "<PRIVATE_REPO_B>=repo_b" \
  --family "<PRIVATE_REPO_C>=repo_c" \
  --family "<PRIVATE_REPO_D>=repo_d" \
  --since-days 14 \
  --json-out /tmp/repo-family-pipeline.json \
  --bash-out /tmp/repo-family-pipeline.sh
```

## Scope Boundary

Use this skill when the primary task is detecting and prioritizing implementation gaps across repositories.

Do not use this skill for:

1. Skill install/quarantine decisions (use `skill-arbiter-lockdown-admission`).
2. Skill discovery portfolio curation (use `skills-discovery-curation`).
3. Repo-specific deep debugging where a dedicated repo skill exists.

## Gap Contracts

The script detects deterministic gap categories:

1. `tests_missing`: code changed without corresponding test changes.
2. `docs_lockstep_missing`: behavior-impacting files changed without docs updates.
3. `todo_fixme_added`: newly introduced `TODO`/`FIXME` markers in the patch window.
4. `release_hygiene_missing`: release-impacting changes without `pyproject.toml` + `CHANGELOG.md` updates.

## Triage Mapping

Route findings consistently:

1. `tests_missing` -> repo-specific execution/test lane.
2. `docs_lockstep_missing` -> `docs-alignment-lock`.
3. `todo_fixme_added` -> repo-specific cleanup lane, then re-sweep.
4. `release_hygiene_missing` -> `skill-arbiter-release-ops`.

## Output

JSON report includes:

- scan metadata (`generated_at`, `since_days`, repo list)
- per-repo findings with severity and evidence
- aggregate counters by category and severity
- suggested skill lanes for remediation

## References

- `references/gap-rubric.md`
- `scripts/code_gap_sweep.py`
- `references/repo-family-pipeline.md`
- `scripts/repo_family_pipeline.py`

## Loopback

If this lane is unresolved, blocked, or ambiguous:

1. Capture the JSON report path and unresolved findings.
2. Route back through `$skill-hub` for chain recalculation.
3. Resume only after the updated chain returns a deterministic next step.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/grtninja) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->