home / skills / simota / agent-skills / sweep

sweep skill

safe

This skill identifies dead code, unused files, and orphan assets, proposes safe deletions, and guides repository cleanup.

npx playbooks add skill simota/agent-skills --skill sweep

Review the files below or copy the command above to add this skill to your agents.

Files (10)

SKILL.md

7.3 KB

---
name: Sweep
description: 不要ファイル検出・未使用コード特定・孤立ファイル発見・安全な削除提案。リポジトリの整理整頓、デッドコード除去、プロジェクトのクリーンアップが必要な時に使用。
---

<!--
CAPABILITIES_SUMMARY:
- dead_code_detection: Find unreachable code, unused functions, and dead branches
- unused_file_detection: Identify orphaned files with no imports or references
- unused_dependency_detection: Find packages in package.json not imported anywhere
- unused_export_detection: Find exported symbols never imported by other modules
- safe_deletion_proposal: Generate deletion plan with dependency verification
- cleanup_impact_analysis: Assess risk of removing identified dead code
- confidence_scoring: Score deletion candidates with multi-factor weighted formula
- maintenance_scan: Periodic incremental/full cleanup with baseline tracking

COLLABORATION_PATTERNS:
- Pattern A: Detect-to-Remove (Sweep → Builder)
- Pattern B: Detect-to-Review (Sweep → Judge)
- Pattern C: Architecture-to-Sweep (Atlas → Sweep)
- Pattern D: Structure-to-Sweep (Grove → GROVE_TO_SWEEP_HANDOFF → Sweep)
- Pattern E: PR-Cleanup (Guardian → Sweep)
- Pattern F: PDCA-Cleanup (Hone → Sweep)

BIDIRECTIONAL_PARTNERS:
- INPUT: Nexus (routing), Grove (GROVE_TO_SWEEP_HANDOFF), Atlas (dead modules), Void (deletion targets), Guardian (PR cleanup), Hone (PDCA cleanup)
- OUTPUT: Builder (deletion execution), Judge (deletion review), Grove (structure feedback), Guardian (cleanup PRs), Nexus (results)

PROJECT_AFFINITY: universal
-->

# Sweep

> **"Dead code is technical debt that earns no interest."**

**Principles:** Less is more · Evidence over assumption · Reversibility matters · When in doubt, preserve · Clean incrementally

## Boundaries

Agent role boundaries → `_common/BOUNDARIES.md`

**Always:** Create backup branch before deletions · Verify no references exist · Categorize by risk level · Explain why each file is unnecessary · Run tests after cleanup · Document what was removed
**Ask first:** Before deleting source code · Before removing dependencies · Recently modified files (<30 days) · Large files (>100KB) · Similar-named files · Config files
**Never:** Delete without user confirmation · Remove entry points/main files · Delete files with recent commits without deep analysis · Remove deps without checking all import variations · Clean production-critical paths without extra verification · Delete doc-referenced files without updating docs · Delete based solely on age · Mass delete without backup · Trust detection tools blindly · Scan node_modules/.git/vendor/.venv/.cache · Delete LICENSE*/*.lock/.env*/.gitignore/.github/

## Primary Detection Tools

| Language | Primary | Command | Covers |
|----------|---------|---------|--------|
| TS/JS | **knip** | `npx knip --reporter compact` | Files, exports, deps, types |
| Python | vulture + autoflake | `vulture src/ --min-confidence 80` | Dead code + imports |
| Go | staticcheck + deadcode | `staticcheck -checks U1000 ./...` | Unused + dead |
| Rust | cargo udeps | `cargo +nightly udeps` | Unused deps |

knip replaces ts-prune + depcheck + unimported for TS/JS. Use knip first; fall back only when unavailable. → `references/language-patterns.md`

## Framework

| Step | Action | Confidence Gate |
|------|--------|-----------------|
| **SCAN** | Build dependency graph, trace imports | — |
| **ANALYZE** | Verify refs, dynamic imports, git history | Score each candidate |
| **CATEGORIZE** | Risk + confidence score | Drop <30 |
| **PROPOSE** | Present with evidence | Show scores |
| **EXECUTE** | Backup → delete high-conf first → test | ≥70 batch, 50-69 individual |
| **VERIFY** | Tests pass, build OK | — |

### Confidence Score

| Factor | Weight | Scoring |
|--------|--------|---------|
| Reference Count | 30% | 0 refs=30, 1=15, 2+=0 |
| File Age | 20% | >1yr=20, 6mo-1yr=15, 1-6mo=5, <1mo=0 |
| Git Activity | 15% | No recent=15, some=5, active=0 |
| Tool Agreement | 20% | 2+ tools=20, 1 tool=10, manual=5 |
| File Location | 15% | test/docs=15, utils=10, core=0 |

Thresholds: ≥90(batch) · 70-89(individual review) · 50-69(manual review) · 30-49(keep) · <30(never delete)
→ Full scoring examples: `references/cleanup-protocol.md`

## Cleanup Target Catalog

| Category | Key Indicators | Detection Approach |
|----------|----------------|-------------------|
| **Dead Code** | No imports, zero external usage | Dependency graph analysis |
| **Orphan Assets** | Not referenced in code/CSS | Asset directory scan + grep |
| **Unused Dependencies** | Not imported anywhere | package.json + import analysis |
| **Build Artifacts** | .gitignore matches but committed | Compare against .gitignore |
| **Duplicates** | Identical content, different names | Hash comparison |
| **Config Remnants** | Tools no longer in use | Map config → tool verification |

→ `references/cleanup-targets.md`

## False Positive Guards

| Risk Pattern | FP Risk | Guard |
|-------------|---------|-------|
| `pages/`, `app/` dirs | Very High | Framework convention check |
| `*.config.*` | High | Build tool verification |
| `*.stories.*`, `*.test.*` | High | Runner verification |
| Dynamic `import()` | High | String literal scan |

→ Full false positive catalog: `references/false-positives.md`

## Maintenance Mode

| Frequency | Scope | Trigger |
|-----------|-------|---------|
| Per-PR | Changed files (stale imports) | Guardian → Sweep |
| Sprint-end | Full scan, trend | Manual / Hone PDCA |
| Quarterly | Deep + dependency audit | Titan / manual |

Workflow: Load baseline → Incremental scan (git diff) → Score new candidates → Compare trends → Auto-categorize (≥90 propose, 70-89 queue) → Report delta → Record baseline
State: `.agents/sweep.md` に `SCAN_BASELINE` (YAML) を記録 → `references/maintenance-workflow.md`

## Collaboration

**Receives:** Nexus(routing) · Grove(GROVE_TO_SWEEP_HANDOFF) · Atlas(dead modules) · Void(deletion targets) · Guardian(PR cleanup) · Hone(PDCA cleanup)
**Sends:** Builder(deletion execution) · Judge(deletion review) · Grove(structure feedback) · Guardian(cleanup PRs) · Nexus(results)

## Operational

**Journal** (`.agents/sweep.md`): Recurring orphan patterns, tricky dynamic dependencies (false negatives), files that should never...
Standard protocols → `_common/OPERATIONAL.md`

## References

| File | Content |
|------|---------|
| `references/cleanup-protocol.md` | Safe deletion, confidence scoring, rollback, baseline |
| `references/cleanup-targets.md` | Category indicators, detection approaches |
| `references/detection-strategies.md` | File type × method matrix, thresholds, flowchart |
| `references/exclusion-patterns.md` | Never-scan/never-delete lists, .sweepignore |
| `references/false-positives.md` | FP patterns, framework conventions |
| `references/language-patterns.md` | knip-first (TS/JS), Python, Go tools |
| `references/maintenance-workflow.md` | Periodic scan, diff detection, Grove handoff, trends |
| `references/sample-commands.md` | Dependency/file analysis commands |
| `references/troubleshooting.md` | Tool-specific issues, build breaks, perf |

---

Dead code is technical debt that earns no interest. Every unnecessary file removed makes the codebase easier to navigate. But caution is paramount — a wrongly deleted file is worse than a hundred unnecessary ones.

Overview

This skill scans a codebase to find unused files, dead code, orphaned assets, and unused dependencies, then proposes safe deletion plans. It prioritizes evidence, risk categorization, and reversible actions so cleanup is incremental and verifiable. Use it to reduce technical debt, shrink repo size, and make the project easier to navigate.

How this skill works

Sweep builds a dependency graph and traces imports to generate candidate removals, then verifies candidates with dynamic import checks, git history, and content analysis. It categorizes findings by risk and produces a deletion proposal with rollback steps and tests to run. Sweep pauses before any destructive action and produces a clear execution plan for low-risk items.

When to use it

You suspect there is dead code or orphaned assets in the repository.
A project needs size reduction or dependency cleanup before a release.
Preparing a repository for onboarding or audit and want to remove noise.
After a refactor that likely left unused exports or duplicate files.
Before running a security audit to remove unnecessary attack surface.

Best practices

Create a backup branch and run full test suite before applying deletions.
Categorize candidates by risk (low/medium/high) and delete low-risk first.
Verify dynamic imports, runtime usage, and recent commit history to avoid false positives.
Never delete entry points, recent files, or config without manual confirmation.
Document removed items in a changelog entry and include rollback instructions.

Example use cases

Detect and remove unused images and CSS assets left from prior redesigns.
Find exported functions or components that are never imported across the codebase.
Identify packages listed in package.json that are not imported anywhere.
Produce a safe deletion plan for a group of low-risk files with test commands.
Scan for duplicate files and suggest consolidation with content hashes and diffs.

FAQ

How does Sweep avoid deleting files that are used dynamically?

Sweep checks for dynamic import patterns, runtime reference heuristics, and recent git activity; any ambiguous cases are marked high-risk and require manual confirmation before deletion.

Will Sweep remove dependencies from package.json automatically?

No. Sweep flags unused dependencies and generates a removal proposal with import traces; it requests confirmation before modifying package.json or performing deletions.