Repo Hygiene

Comprehensive repository housekeeping: pre-work validation, documentation updates, writing style, and cleanup.

Pre-Work Checks

MANDATORY before adding files or making structural changes.

Before Adding Files

1. Find existing examples of similar files
2. State the correct location based on those examples
3. Tell the user your plan and wait for confirmation
4. Send updates during work

If you skip any step: BLOCKED

Finding Patterns

# For skills
ls -la .claude/skills/ | head -10
find . -name "SKILL.md" -type f | head -10

# For any file type
find . -name "*.ts" -type f | head -10

Self-Check Before File Creation

1. Did I check existing patterns?
2. Did I tell the user my plan?
3. Did I wait for confirmation?
4. Did I send updates during work?

If any answer is "no": STOP and fix it.

Documentation Updates

Automatically update project documentation after task completion.

Trigger Conditions

Invoke after:

• Completing any task
• Adding a new feature
• Fixing a bug
• Refactoring code

PLAN.md Updates

All plan updates go to root PLAN.md. This is the single source of truth.

Mark completed items:

## Current Sprint
- [x] Implement user authentication  # Was [ ]

Add discovered work:

## Backlog
- [ ] (discovered) New task from implementation

Move completed items with timestamp:

## Completed
- [x] Task description (2026-01-30)

README.md Updates

Update when:

• New user-facing feature added
• API changed
• New command available
• Installation steps changed

Alphabetical Ordering

All skill lists and tables in documentation (README.md, CLAUDE.md) must be sorted alphabetically by skill name. Within categorized sections, sort alphabetically within each category.

Check after any skill addition or rename:

# Verify alphabetical order in markdown tables
grep '^\| \[' README.md  # Visual check: names should be A-Z within each section
grep '^\|' CLAUDE.md     # Visual check: names should be A-Z

If out of order: fix before committing.

Link Validation

Verify all markdown links resolve before committing:

# Find all markdown links and check they exist
grep -oE '\[.*?\]\(\.?/?[^)]+\)' README.md | \
  sed -E 's/.*\(([^)]+)\)/\1/' | \
  while read link; do
    [ -e "$link" ] || echo "BROKEN: $link"
  done

Check for:

• Relative links (./path/to/file.md): Must resolve from README location
• Anchor links (#section): Must match a heading in the target file
• External links: Verify with curl if critical

Run validation after any documentation update.

Pre-Merge Cleanup

When preparing to merge:

# 1. Sync CLAUDE.md with installed skills
skills claudemd sync

# 2. Scan for test artifacts and slop
skills hygiene scan

# 3. If slop found, clean it
skills hygiene clean --confirm

# 4. Update PLAN.md with completed work

# 5. Commit and push
git add -A && git commit -m "chore: pre-merge cleanup" && git push

Writing Style

Use for all markdown files: README.md, PLAN.md, documentation.

Voice

• Write like speaking to an intelligent friend
• Short sentences. Direct claims. No hedging.
• Active voice, not passive
• State claims confidently

Punctuation Rules

• Never use em dashes (—)
• Use periods and new sentences for separate thoughts
• Use commas for simple asides
• Use parentheses for clarifying information
• Use colons for lists or elaboration

Structure

• Start with the point, not background
• One idea per paragraph
• Headers should be claims, not topics
• End sections when the point is made

Quality Checklist

• No em dashes in content
• Sentences are short and direct
• Opens with the main point
• Code examples are minimal
• Tables used for structured data

Slop Cleanup

Detect and clean AI-generated slop from your project.

Quick Start

# Scan for slop
skills hygiene scan

# Preview what would be deleted
skills hygiene clean --dry-run

# Actually delete slop
skills hygiene clean --confirm

What is Slop?

CLAUDE.md Cleanup

Check for:

• Stale references: Skills listed but not installed
• Duplicate references: Same skill listed multiple times

Run skills claudemd sync to fix.

Decision Tree

Found test-skill-*?
├─ YES → Delete (safe)
└─ NO
   ├─ Found _temp_* with good content?
   │  └─ Rename to proper name, delete _temp_ version
   ├─ Found placeholder content?
   │  └─ Delete or rewrite
   └─ Found stale CLAUDE.md refs?
      └─ Run: skills claudemd sync

Related Commands

• skills validate - Check skill quality
• skills claudemd sync - Sync CLAUDE.md with installed skills
• skills list - Show installed skills

Rationalizations (Do Not Skip)

Reference Files

For README writing guidelines, see:

• references/readme-structure.md - Section ordering
• references/readme-badges.md - Badge patterns
• references/readme-cli-docs.md - CLI documentation
• references/readme-checklist.md - Full checklist

For prose quality and markdown rewriting support, use:

• ../paul-graham/SKILL.md - Direct, high-signal writing and editing workflow