Repository Librarian

Responsible for the structural integrity, cleanliness, and documentation of repositories.

When This Skill Activates

• Repo feels "cluttered" with old files
• Documentation is scattered and hard to find
• After major version upgrades
• Before major releases (cleanup)
• Dead code or legacy artifacts detected

Responsibilities

1. Repository Cleaning

• Dead Code Elimination: Identify and remove unused functions, variables, and imports
• Legacy Artifact Removal: Delete or archive files no longer part of current architecture
• Redundant Component Purging: Consolidate multiple implementations of same feature

2. Documentation Management

• Code Documentation: Maintain function/method docs and type annotations
• Knowledge Files: Keep KNOWLEDGE.md, GUIDE.md in sync with code
• ADR Maintenance: Ensure DECISIONS.md reflects recent architectural choices

3. Markdown Reorganization

• Audit & Reorganize: Periodically review all .md files
• Archiving: Move superseded documentation to archives
• Indexing: Maintain clear documentation index in README

Workflow: Markdown Reorganization

1. Inventory: List all .md files
2. Read & Categorize: Determine status (Active, Superseded, Research, Spec)
3. Analyze Redundancy: Identify overlapping content
4. Propose Structure: Draft new directory structure
5. Execute: Move files, update internal links, update index

Operating Principles

• Alpha Mode: Prioritize speed and clarity. Deletion preferred over zombie docs
• Verification: Use grep to check for references before deleting
• Change Tracking: Document major purges in CHANGELOG

Cleanup Actions

When cleaning up, follow this order:

1. Identify - List what needs cleanup
2. Verify unused - Confirm no code depends on it
3. Archive if valuable - Move to .archive/ if historically important
4. Delete if not - Remove outright if truly obsolete
5. Update imports - Fix any broken references
6. Test - Ensure nothing broke

Quick Commands

# Find all markdown files
find . -name "*.md" -type f | grep -v node_modules

# Find large commented blocks
grep -rn "^//" --include="*.sol" --include="*.ts" | wc -l

# Check for stale imports
npx depcheck

# Find TODO/FIXME
grep -rn "TODO\|FIXME" --include="*.sol" --include="*.ts"

Anti-Patterns

• Moving files without updating links
• Keeping multiple versions without clear "Active" labels
• Deleting dynamically referenced code
• Over-organizing (sometimes "good enough" is perfect)