fresh-eyes-sweep
starsforks
How to install fresh-eyes-sweep?
paulrberg/agent-skills/fresh-eyes-sweep
$npx -y skills add PaulRBerg/agent-skills --skill fresh-eyes-sweepAudit an entire repository with fresh eyes for correctness errors, bugs, omissions, duplication, inconsistencies, and other evidenced mistakes; fix every safe issue and verify the result.
SKILL.md
| 1 | # Fresh Eyes Sweep |
| 2 | |
| 3 | Inspect the requested Git scope for evidenced mistakes, fix every safe issue, and continue until every mapped file is |
| 4 | accounted for and a full pass finds nothing new. A verified no-op is valid only after that coverage. |
| 5 | |
| 6 | ## Ledger Interface |
| 7 | |
| 8 | Resolve `scripts/sweep-ledger.py` from this `SKILL.md`. Create the scratch ledger outside the repository: |
| 9 | |
| 10 | ```sh |
| 11 | uv run "<skill-dir>/scripts/sweep-ledger.py" init \ |
| 12 | --root <repo> --ledger <scratch.json> [<path>...] |
| 13 | ``` |
| 14 | |
| 15 | With no paths, `init` maps the whole repository. With paths, it maps exactly those Git scopes. It records every tracked |
| 16 | and non-ignored untracked file plus each path's pre-existing worktree status. The helper does not classify generated, |
| 17 | vendored, binary, safe, important, or defective files. |
| 18 | |
| 19 | Record an agent decision atomically only after inspecting or otherwise accounting for the path: |
| 20 | |
| 21 | ```sh |
| 22 | uv run "<skill-dir>/scripts/sweep-ledger.py" mark \ |
| 23 | --ledger <scratch.json> --status <pending|inspected|fixed|reported|excluded> \ |
| 24 | --path <path> [--path <path>...] [--reason <text>] |
| 25 | ``` |
| 26 | |
| 27 | `excluded` requires an agent-written reason. Unknown paths or invalid batches fail without a partial update. |
| 28 | |
| 29 | ```sh |
| 30 | uv run "<skill-dir>/scripts/sweep-ledger.py" pending --ledger <scratch.json> [--limit <n>] |
| 31 | uv run "<skill-dir>/scripts/sweep-ledger.py" summary --ledger <scratch.json> |
| 32 | ``` |
| 33 | |
| 34 | `pending` returns the next unaccounted paths in stable order. `summary` returns exact status counts, pre-existing edit |
| 35 | count, completeness, percentage inputs, and a ten-cell bar. Use those facts directly; never estimate progress or |
| 36 | reimplement ledger arithmetic. |
| 37 | |
| 38 | ## Setup |
| 39 | |
| 40 | 1. Require Git and read applicable repository instructions. |
| 41 | 2. Initialize the ledger for the requested scope. The agent may additionally inspect shared configuration and |
| 42 | instructions needed to understand that scope; do not silently widen the ledger. |
| 43 | 3. Classify generated, vendored, minified, binary, and bulk-data artifacts. Validate them through their generator, |
| 44 | schema, or invariants when line-by-line review is inappropriate, then mark them with the agent's reason. |
| 45 | 4. Inspect recent history and diffs, especially the newest changes, to find affected callers, dependencies, tests, |
| 46 | configuration, and docs. Recency sets order, never coverage. |
| 47 | 5. Discover build, test, lint, typecheck, format, and codegen checks. |
| 48 | 6. Preserve every pre-existing edit recorded by the ledger. Do not revert, absorb, commit, or report it as a finding. |
| 49 | |
| 50 | After mapping, report `### 🔎 Sweep mapped — <files> files · <slices> slices`. Slice count is an agent organization |
| 51 | choice; file count comes from the ledger. |
| 52 | |
| 53 | ## Inspect and Fix |
| 54 | |
| 55 | Work through coherent slices so implementation, callers, tests, configuration, and documentation stay visible together. |
| 56 | Trace important control, data, and error paths end to end. Hunt for concrete bugs, omissions, invalid assumptions, |
| 57 | unhandled edges, security/reliability failures, inconsistencies, duplication, dead code, stale docs, and needless |
| 58 | complexity. Style preferences and unverified hunches are not findings. |
| 59 | |
| 60 | Confirm each issue before editing. Fix the smallest root cause when intent is clear and verification is available; add a |
| 61 | focused regression test when useful. Mark `reported` when a safe fix would alter a public contract, intent is ambiguous, |
| 62 | or verification is unavailable. Do not add speculative features, broad refactors, or cosmetic churn. |
| 63 | |
| 64 | On long runs, post updates only after coherent slices settle, using the ledger summary's exact bar and counts. The bar |
| 65 | means path accounting, not depth of inspection. |
| 66 | |
| 67 | ## Verify and Report |
| 68 | |
| 69 | Run the narrowest check proving each fix, then aggregate checks scoped to changed files. Reinspect affected paths and |
| 70 | repeat until a pass finds no new evidenced issue. Audit coverage, fixes, and checks against tool output before claiming |
| 71 | completion. |
| 72 | |
| 73 | Lead with |
| 74 | `### ✅ Sweep ledger complete — <accounted>/<mapped> files accounted (<inspected> inspected, <excluded> excluded)` only |
| 75 | when helper `complete` is true; otherwise use `### ⛔ Sweep incomplete`. Summarize fixed, reported, excluded, and check |
| 76 | counts, then include fixed artifacts, verification, unresolved findings, and residual risk only when non-empty. Do not |
| 77 | expose the scratch ledger, pre-existing changes, or private/bulk data. |
| 78 | |
| 79 | Completion requires every mapped path accounted for, every finding fixed and verified or reported with evidence, and |
| 80 | every relevant check passing or its failure attributed. |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
