Declutter

Declutter Skill

Purpose: Create a clean, welcoming project structure where every file has its proper place, following open-source conventions and the project's established patterns.

Philosophy: A well-organized project should produce a hand-sized, predictable tree that immediately communicates what the project does and how it's structured. The root should be clean and inviting, not overwhelming.

Core Principles

1. Clean Root, Clear Intent

The project root is the first impression. It should contain only:

• Essential entry files (README, LICENSE, main config)
• Standard directories that communicate purpose
• No orphaned files, experiments, or ambiguous content

2. Correlation Preservation

Files that belong together stay together:

• Module-related files remain in module context
• Development stage files stay with their stage
• App-specific files stay with their app
• Build artifacts stay with build configuration

3. Skill Delegation

Declutter identifies and recommends but does not refactor alone:

• For code restructuring → delegate to refactor skill
• For documentation moves → delegate to technical-writer agent
• For build pipeline changes → delegate to devops skill
• If skill doesn't exist → recommend installation/configuration

4. Query Before Move

When placement is ambiguous:

1. First, check for relevant specialized skills/agents
2. Consult with appropriate skill for research
3. Only ask user when no skill can help
4. Always explain the reasoning

When to Use This Skill

Trigger Phrases:

• "Declutter this project"
• "Organize the file structure"
• "Clean up the root directory"
• "This project is messy, help me organize it"
• "Where should this file go?"

Automatic Contexts:

• After initial project setup
• Before open-sourcing a project
• When onboarding feels overwhelming
• After feature sprawl or rapid prototyping

The Declutter Workflow

Phase 1: Assessment (Survey)
   ↓
Phase 2: Classification (Categorize)
   ↓
Phase 3: Research (Consult Skills)
   ↓
Phase 4: Proposal (Plan Moves)
   ↓
Phase 5: Execution (Delegate Actions)

Phase 1: Assessment (Survey the Landscape)

Goal: Understand current state without judgment.

Actions:

1. Capture the current tree:

   tree -L 2 -a --dirsfirst -I '.git|node_modules|target|__pycache__|.venv'
   

2. Identify technology stack:

   • Check for package.json, Cargo.toml, pyproject.toml, go.mod, etc.
   • Note frameworks (React, Astro, Django, etc.)
   • Identify build systems (webpack, vite, cargo, etc.)

3. Count root-level items:

   ls -la | wc -l
   

   Healthy root: 10-20 items (dirs + essential files) Needs attention: 20-30 items Critical: 30+ items

4. Identify outliers:

   • Files that don't match project type
   • Duplicate or similar-named files
   • Dated/versioned files (backup.old, file_v2.txt)
   • Orphaned configuration files

Output:

• Tree captured
• Tech stack identified
• Root item count logged
• Outliers list created

Phase 2: Classification (Categorize Everything)

Goal: Assign each item to a category for action.

File Categories:

Classification Rules:

For Markdown Files:

README.md, CONTRIBUTING.md, CHANGELOG.md → Root (OSS standard)
CODE_OF_CONDUCT.md, SECURITY.md → Root (GitHub special files)
*.md (other) → /docs

For Configuration:

Single dotfile → Root acceptable
Multiple similar configs → /config directory
Build tool config → Usually root (webpack.config.js, etc.)
Editor config → Root (.editorconfig, .prettierrc)

For Scripts:

1-2 scripts → /scripts or root acceptable
3+ scripts → Must move to /scripts
Shell scripts → /scripts
Build scripts → /scripts/build or npm scripts

Output:

• Each file/directory categorized
• Action type assigned (keep/move/delete/ask)
• Ambiguous items flagged for consultation

Phase 3: Research (Consult Specialized Skills)

Goal: Get expert guidance before making moves.

Skill Consultation Matrix:

Consultation Protocol:

1. Check if skill exists:

   Glob: .claude/skills/*/SKILL.md
   

2. Check if agent can help:

   • Review Task tool agent descriptions
   • Match to categorization need

3. If skill/agent available:

   Task: [appropriate-agent]
   Prompt: "I'm decluttering this project and need guidance on
   [specific question]. What's the best practice for [specific situation]?"
   

4. If skill/agent not available:

   Report to user:
   "I'd like to consult a [skill-type] skill for [reason], but it's
   not installed. Would you like to:
   a) Configure/install the skill
   b) Proceed with my best judgment
   c) Skip this category for now"
   

OSS Convention Research:

When framework-specific guidance isn't available, research:

• GitHub trending repos in same tech stack
• Official framework documentation
• Community-accepted patterns

Use the Explore agent:

Task: Explore
Prompt: "Find the standard directory structure for [technology] projects.
Focus on: root organization, docs placement, scripts location, config handling."

Output:

• Skills/agents consulted
• Best practices documented
• User decisions recorded (if any)

Phase 4: Proposal (Create the Move Plan)

Goal: Present a clear, actionable reorganization plan.

Proposal Format:

## Declutter Proposal - [Project Name]

### Current State
- Root items: 42 (Critical - needs attention)
- Tech stack: Rust CLI with Astro website
- Primary issues: Documentation scattered, scripts mixed

### Proposed Structure

project-root/ ├── .claude/ # Claude configuration (keep) ├── .github/ # GitHub workflows (keep) ├── docs/ # Documentation (create) │ ├── architecture/ # ADRs and design docs │ ├── guides/ # User guides │ └── api/ # API documentation ├── scripts/ # Automation (organize) │ ├── build/ # Build scripts │ ├── dev/ # Development helpers │ └── release/ # Release automation ├── src/ # Source code (keep) ├── tests/ # Test files (keep) ├── website/ # Astro site (keep) ├── Cargo.toml # Main config (keep) ├── README.md # Entry point (keep) ├── LICENSE # Legal (keep) └── CHANGELOG.md # History (keep)

### Proposed Moves

| File | From | To | Reason |
|------|------|-----|--------|
| ARCHITECTURE.md | / | /docs/architecture/ | Standard docs location |
| setup.sh | / | /scripts/ | OSS convention |
| dev-notes.md | / | /docs/guides/ | Internal documentation |

### Files to Delete
| File | Reason |
|------|--------|
| backup.old | Obsolete backup |
| test_experiment.rs | Superseded by /tests |

### Files Requiring Decision
| File | Options |
|------|---------|
| random_script.py | A) Delete B) Move to /scripts C) Keep |

### Skills to Engage

1. `technical-writer` - Restructure /docs hierarchy
2. `refactor` - Update import paths after moves (NOT AVAILABLE - recommend install)

Output:

• Proposal document created
• All moves justified
• User decisions requested
• Skills identified for delegation

Phase 5: Execution (Delegate and Move)

Goal: Execute the plan with proper delegation.

Execution Rules:

1. Never refactor code directly - delegate to refactor skill
2. Never update imports alone - delegate to appropriate skill
3. Document all moves in commit message
4. Preserve git history where possible (git mv)

Move Protocol:

# Always use git mv for tracked files
git mv old/path new/path

# Create directories first
mkdir -p new/directory

# Batch related moves
git mv docs/*.md docs/guides/

Post-Move Validation:

1. Check for broken links:

   grep -rn "old/path" --include="*.md" --include="*.rs"
   

2. Verify imports still work:

   cargo check  # For Rust
   npm run build  # For JS
   

3. Update any absolute references

Commit Strategy:

# Single logical commit for declutter
git add -A
git commit -m "$(cat <<'EOF'
refactor: Declutter project structure

Moves:
- ARCHITECTURE.md → docs/architecture/
- setup.sh → scripts/
- dev-notes.md → docs/guides/

Deletes:
- backup.old (obsolete)
- test_experiment.rs (superseded)

Created:
- docs/architecture/ directory
- scripts/build/ directory

Consulted: technical-writer agent, OSS conventions
EOF
)"

Output:

• All moves executed
• Broken references fixed
• Commit created
• Post-move validation passed

Mono-Repo Strategy

For mono-repos, declutter level by level:

Level 1: Root

• Focus on top-level organization
• Ensure clear separation between projects
• Shared configs at root or /config

Level 2: Individual Projects

• Apply same principles to each sub-project
• Respect sub-project conventions
• Don't cross-contaminate

Level 3: Scripts/DevOps

• Centralize shared scripts
• Per-project scripts stay in project
• CI/CD in .github/ or /ci

Mono-Repo Structure Template:

monorepo/
├── .github/               # Shared CI/CD
├── docs/                  # Shared documentation
├── packages/              # Sub-projects
│   ├── app-a/
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   └── app-b/
├── scripts/               # Shared automation
├── config/                # Shared configuration
├── package.json           # Root workspace
└── README.md

Technology-Specific Conventions

Rust Projects

project/
├── src/
│   ├── lib.rs             # Library entry
│   └── main.rs            # Binary entry
├── tests/                 # Integration tests
├── benches/               # Benchmarks
├── examples/              # Example usage
├── Cargo.toml
└── README.md

JavaScript/Node Projects

project/
├── src/                   # Source code
├── dist/                  # Build output (gitignored)
├── tests/ or __tests__/   # Tests
├── scripts/               # Build/dev scripts
├── package.json
└── README.md

Python Projects

project/
├── src/project_name/      # Package code
├── tests/                 # Tests
├── docs/                  # Documentation
├── scripts/               # Automation
├── pyproject.toml
└── README.md

See references/oss-conventions.md for comprehensive patterns.

Quick Reference Checklist

┌─────────────────────────────────────────────────────────┐
│  DECLUTTER CHECKLIST                                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Assessment:                                            │
│  ☐ Tree captured (depth 2)                             │
│  ☐ Tech stack identified                               │
│  ☐ Root item count: _____ (target: <20)               │
│  ☐ Outliers identified                                 │
│                                                         │
│  Classification:                                        │
│  ☐ Each item categorized                               │
│  ☐ Actions assigned (keep/move/delete/ask)            │
│                                                         │
│  Research:                                              │
│  ☐ Relevant skills consulted                           │
│  ☐ Missing skills reported                             │
│  ☐ OSS conventions checked                             │
│                                                         │
│  Proposal:                                              │
│  ☐ Target structure documented                         │
│  ☐ Move plan created                                   │
│  ☐ User decisions collected                            │
│                                                         │
│  Execution:                                             │
│  ☐ Moves delegated to skills where needed              │
│  ☐ git mv used for tracked files                       │
│  ☐ Broken references fixed                             │
│  ☐ Commit created with full context                    │
│                                                         │
└─────────────────────────────────────────────────────────┘

What Declutter Does NOT Do

• Does not refactor code - delegates to refactor skill
• Does not update imports - delegates to appropriate skill
• Does not delete without confirmation - always asks
• Does not override project conventions - respects existing patterns
• Does not move without explanation - documents all decisions

Skill Dependencies

Required:

• None (can run standalone with manual moves)

Recommended:

• refactor - For updating imports after moves
• technical-writer - For documentation restructuring
• Explore agent - For OSS convention research

Optional:

• devops - For pipeline reorganization
• validate-constitution - For checking project rules

Example Invocation

Using the Task tool:

Task: general-purpose
Prompt: "Run the declutter skill on this project.

Follow the workflow in .claude/skills/declutter/SKILL.md:
1. Assess the current structure
2. Classify all files/directories
3. Consult relevant skills for guidance
4. Create a proposal document
5. Present it for user approval before execution

Focus on making the root clean and welcoming.
Respect existing conventions and correlations.
Delegate refactoring to appropriate skills."

Success Criteria

Declutter is complete when:

• ✅ Root contains ≤20 items
• ✅ All files are in logical locations
• ✅ Structure follows tech-stack conventions
• ✅ Orphaned files addressed
• ✅ Proposal approved by user
• ✅ All moves executed or delegated
• ✅ No broken references remain
• ✅ Commit documents all changes

A decluttered project is a welcoming project. Every file in its place, every place with purpose.