gap-scan

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 issues (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 so the next run's tree is clean and pip install . isn't broken by it. Per item:

### <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).