Repository Audit & Cleanup

Systematically audits the repository for organizational issues, unused files, and stale content.

When to Use

Trigger /repo-audit when:

• Repository feels cluttered or disorganized

• Before major milestones or releases

• Monthly/quarterly maintenance

• After completing large features

• Onboarding new team members (clean house first)

What This Audits

1. Root-Level Files (Should Be Minimal)

Check: Files at repository root that might belong elsewhere

Common issues:

• Screenshots/images → Should be in docs/images/ or deleted

• Audit/analysis docs → Should be in docs/audit/ or docs/analysis/

• Temporary test files → Should be deleted

• Old config files → Should be in appropriate directory or deleted

Process:

List non-standard root files

ls -1 | grep -v -E '(^\.|README|LICENSE|CLAUDE|package|pyproject|tsconfig|Dockerfile|cloudbuild|.gitignore|node_modules|.venv)'

Categorize each file:

• ✅ Keep at root (essential config/docs)

• 📁 Relocate (move to appropriate directory)

• 🗑️ Delete (temporary/outdated)

2. Documentation Structure

Check: Documentation is organized and current

Expected structure:

docs/ architecture/ # How systems work troubleshooting/ # When things break audit/ # Investigation records plans/ # Implementation plans prompts/ # Legacy/reference prompts database/ # Schema docs images/ # Screenshots, diagrams

Audit each docs/ file:

• Current? Still relevant to current codebase?

• Accurate? Information is correct?

• Organized? In right directory?

• Referenced? Linked from CLAUDE.md or README?

Flag for review:

• Files >6 months old with no updates

• Files referencing deleted/renamed code

• Orphaned files (not linked anywhere)

3. Scripts & Tools

Check: Scripts are used, working, and documented

List all scripts

find scripts/ -type f -executable

For each script, verify:

• ✅ Purpose documented (comment at top or README)

• ✅ Recently used (check git log for last modification)

• ✅ Dependencies exist (imports/requires are installed)

• ✅ Executable (chmod +x if needed)

Common issues:

• One-off migration scripts no longer needed

• Duplicate functionality (consolidate)

• Hardcoded paths/credentials (parameterize)

• No error handling (improve)

4. Test Files & Test Data

Check: Test files are current and valuable

Find test files

find tests/ -name ".py" -o -name ".ts"

Audit:

• Tests for deleted features (remove)

• Skipped tests (fix or delete)

• Outdated fixtures/mocks (update or delete)

• Test data files no longer used (remove)

5. Code Imports & Dependencies

Check: No unused imports or dependencies

TypeScript/JavaScript:

Find potentially unused dependencies

npx depcheck dashboard/

Python:

Find unused imports (requires pip-autoremove or similar)

cd src && python -m autoflake --check --remove-all-unused-imports -r .

Review:

• Packages in package.json/pyproject.toml but not imported

• Large dependencies used minimally (consider alternatives)

• Duplicate dependencies (consolidate)

6. Prompt Files & Templates

Check: Prompt files are current and organized

Expected:

• Active prompts in docs/prompts/

• Legacy/reference prompts clearly marked

• Continuation prompts in .claude/prompts/ or .claude/checkpoints/

Audit:

• Outdated prompt files (mark as legacy or delete)

• Duplicate prompts (consolidate)

• Prompts referencing old architecture (update or delete)

7. Images & Media Files

Check: Images are used and organized

Find all images

find . -type f \( -name ".png" -o -name ".jpg" -o -name ".gif" -o -name ".svg" \) | grep -v node_modules | grep -v .venv

For each image:

• Referenced? Grep codebase for filename

• Purpose clear? Filename is descriptive

• Location appropriate? In docs/images/ or asset directory

Common issues:

• Test screenshots at root (move to docs/images/ or delete)

• Unused mockup images (delete)

• Duplicate images (deduplicate)

8. Configuration Files

Check: Config files are necessary and current

Audit:

• .env.example up to date with actual env vars?

• Multiple similar configs (tsconfig, eslint) - can consolidate?

• Old/deprecated config files (remove)

• Config overrides in multiple places (consolidate)

Execution Flow

Phase 1: Quick Scan

Run automated checks:

Root-level non-standard files

echo "=== Root-Level Files ===" ls -1 | grep -v -E '(^\.|README|LICENSE|CLAUDE|package|pyproject|tsconfig|Dockerfile|cloudbuild|\.gitignore)'

Large files

echo -e "\n=== Large Files (>1MB) ===" find . -type f -size +1M | grep -v node_modules | grep -v .venv | grep -v .git

Old files (>6 months, not modified)

echo -e "\n=== Old Files (>6 months since modification) ===" find . -type f -mtime +180 | grep -v node_modules | grep -v .venv | grep -v .git | head -20

Potentially unused scripts

echo -e "\n=== Scripts Not Modified in >3 Months ===" find scripts/ -type f -mtime +90 2>/dev/null || echo "No old scripts found"

Phase 2: Categorize Findings

For each flagged file, determine:

• Essential (keep as-is)

• Relocate (move to proper location)

• Archive (move to archive/ directory with date)

• Delete (no longer needed)

• Update (content is stale)

Phase 3: Create Action Plan

Generate cleanup plan:

Repository Cleanup Plan

Generated: [date] Files Audited: [N] Issues Found: [N]

High Priority (Do Now)

• Delete: [file] - [reason]
• Relocate: [file] → [new-location] - [reason]
• Update: [file] - [what needs updating]

Medium Priority (Do This Week)

• Consolidate: [files] → [single location]
• Document: [file] - [add purpose/usage]
• Archive: [file] → archive/YYYY-MM/ - [reason]

Low Priority (Do Eventually)

• Review: [file] - [needs manual review]
• Consider: [file] - [potential improvement]

Statistics

• Root-level clutter: [N files]
• Orphaned docs: [N files]
• Unused scripts: [N files]
• Old test files: [N files]
• Unreferenced images: [N files]

Phase 4: Execute Cleanup (With Approval)

Present plan to user for approval, then execute:

Create archive directory

mkdir -p archive/$(date +%Y-%m)

Execute approved actions

(move, delete, update files as approved)

Phase 5: Update Organization Standards

After cleanup, document standards in new file: docs/ORGANIZATION.md

Organization Standards Document

Create docs/ORGANIZATION.md :

Repository Organization Standards

Last Updated: [date]

Directory Structure

Allied-FeedOps/ ├── .claude/ # Claude Code configuration │ ├── hooks/ # Automatic enforcement │ ├── skills/ # Triggered workflows │ ├── templates/ # Reusable patterns │ ├── prompts/ # Continuation prompts │ └── checkpoints/ # Session state saves ├── dashboard/ # Next.js frontend │ ├── src/ │ │ ├── app/ # App router pages │ │ ├── components/ # React components │ │ └── lib/ # Utilities, integrations │ └── public/ # Static assets ├── src/ # Python pipeline │ └── feedops/ │ ├── api/ # FastAPI endpoints │ ├── pipeline/ # Core pipeline logic │ └── integrations/ # External services ├── tests/ # All test files │ ├── api/ # API tests │ └── [module]_test.py # Unit tests ├── scripts/ # Maintenance scripts │ └── README.md # Script documentation ├── docs/ # All documentation │ ├── architecture/ # System design │ ├── troubleshooting/ # Debug guides │ ├── audit/ # Investigations │ ├── plans/ # Implementation plans │ ├── database/ # Schema docs │ └── images/ # Screenshots, diagrams ├── supabase/ # Database migrations └── archive/ # Archived files by date └── YYYY-MM/ # Monthly archives

File Placement Rules

Root Directory

ALLOWED:

• Essential docs: README.md, LICENSE, CLAUDE.md
• Build configs: package.json, pyproject.toml, Dockerfile
• Tool configs: .gitignore, .env.example, tsconfig.json
• CI/CD: cloudbuild.yaml, vercel.json

NOT ALLOWED:

• Screenshots (→ docs/images/)
• Analysis docs (→ docs/audit/ or docs/analysis/)
• Temporary files (→ delete)
• Archived content (→ archive/YYYY-MM/)

Documentation (docs/)

MUST have:

• Clear filename: problem-solution-date.md
• Date in filename or front matter
• Purpose stated in first paragraph
• Linked from CLAUDE.md or README if important

Archive if:

• 1 year old AND not referenced

• References deleted/renamed code
• Superseded by newer doc

Scripts (scripts/)

MUST have:

• Purpose comment at top
• Usage example in scripts/README.md
• Parameterized (no hardcoded paths/creds)
• Listed in scripts/README.md

Delete if:

• One-off migration >6 months old
• Duplicate functionality
• Dependencies no longer available

Images & Media

Location:

• Product screenshots → docs/images/product/
• Architecture diagrams → docs/images/architecture/
• UI mockups → docs/images/design/
• Test screenshots → docs/images/tests/ OR delete after testing

Naming: descriptive-purpose-date.png

Temporary Files

Never commit:

• Local test outputs
• Debug screenshots (unless documenting a bug)
• Personal notes
• .DS_Store, Thumbs.db, etc.

Add to .gitignore if needed.

Monthly Maintenance

First Monday of each month:

1. Run /repo-audit
2. Review and execute cleanup plan
3. Archive files >1 year old not recently accessed
4. Update docs/ORGANIZATION.md if structure changed

Automated Cleanup

See .claude/templates/repo-cleanup-hook.json for automated checks.

Automation: Monthly Audit Reminder

Add to .claude/hooks/config.json :

{ "sessionStart": { "command": "bash -c 'LAST_AUDIT=$(find .claude/ -name "repo-audit" -type f -mtime -30 | wc -l); if [ "$LAST_AUDIT" -eq 0 ]; then echo "💡 Repository audit overdue. Consider running /repo-audit"; fi'" } }

Integration with /wrapup

Add to /wrapup skill:

Step X: Check for Repository Clutter

If files were added/created in this session:

• Are they in the right location?
• Do they follow naming conventions?
• Should any be temporary (deleted)?

Output Format

Repository Audit Results

Date: [timestamp] Files Scanned: [N] Issues Found: [N]

Summary

• 🗑️ [N] files recommended for deletion
• 📁 [N] files should be relocated
• 📝 [N] files need updates
• 📦 [N] files should be archived

Detailed Findings

Root-Level Clutter

• sticky-tabs-test.png → 🗑️ Delete (test screenshot, no longer needed)
• prompt-scoring-audit-FINAL.md → 📁 Move to docs/audit/
• package-lock.json (root) → 🗑️ Delete (duplicate, dashboard has own)

Documentation Issues

• docs/prompts/old-prompt.md → 📦 Archive (references deleted features)
• docs/architecture/outdated.md → 📝 Update (describes old architecture)

Unused Scripts

• scripts/one_time_migration.py → 📦 Archive (migration complete, >6 months old)

[Continue for each category...]

Recommended Actions

Immediate (Do Now):

# Delete temporary/test files
rm sticky-tabs-test.png sticky-tabs-scrolled.png

# Move misplaced files
mv prompt-scoring-audit-FINAL.md docs/audit/prompt-scoring-audit-2026-02.md

# Delete root package-lock.json (dashboard has own)
rm package-lock.json

This Week:

# Archive old migrations
mkdir -p archive/2026-02
mv scripts/one_time_migration.py archive/2026-02/

Eventually:

- Review and update docs/architecture/outdated.md

- Consolidate duplicate test fixtures

Total cleanup impact: [N] files, [Size] space

Proceed with cleanup?