repo-hygiene — Repository Health Check

A structured, periodic health check for repositories. Run anytime to detect drift, accumulation of tech debt, and configuration issues before they become problems.

Not a release gate. For pre-release checks, use the pre-release skill instead. This skill is for ongoing maintenance — run it weekly, after major refactors, when onboarding to a repo, or whenever things feel "off".

When to Use

• Onboarding to a new (or forgotten) repo — "what shape is this in?"
• Weekly/monthly maintenance sweep
• After a large refactor or dependency upgrade
• Before starting a new feature sprint
• When CI starts failing mysteriously
• After a team member leaves and you inherit their repo

Supported Stacks

Detect the stack from the project root. Multiple stacks in one repo is fine — run applicable checks for each. If the stack isn't listed, skip stack-specific checks and run the universal ones (git, CI, docs, security).

The Workflow

Step 0: Detect Project

# What are we working with?
ls package.json pyproject.toml go.mod 2>/dev/null
git rev-parse --show-toplevel

Determine: stack(s), git remote, default branch, CI system (GitHub Actions, GitLab CI, etc.).

Step 1: Dependency Health

#### Node.js / npm

D5 — Lockfile freshness check:

# package.json changed more recently than lockfile?
LOCK_DATE=$(git log -1 --format=%ct -- package-lock.json 2>/dev/null || echo 0)
PKG_DATE=$(git log -1 --format=%ct -- package.json 2>/dev/null || echo 0)
if [ "$PKG_DATE" -gt "$LOCK_DATE" ]; then
  echo "⚠️ package.json modified after lockfile — run npm install"
fi

How to fix:

• D1: npm audit fix for compatible fixes; npm audit fix --force for breaking (review changes). For stubborn advisories: check if the vuln is reachable, or override in package.json overrides.
• D2: npm update for minor/patch; npm install <pkg>@latest for major (check changelogs).
• D3: npm uninstall <pkg> for each unused dep.
• D4: npm install <pkg> for each missing dep.
• D5: npm install to regenerate lockfile, commit it.
• D6: npm dedupe then verify tests pass.

#### Python (uv / pip)

How to fix:

• D1: uv pip install --upgrade <pkg> for each vulnerable package. Check advisories for minimum safe version.
• D2: uv pip install --upgrade <pkg> per package, or uv lock --upgrade for all.
• D3: Remove from [project.dependencies] in pyproject.toml, then uv sync.
• D5: uv lock && uv sync.

#### Go

How to fix:

• D1: go get <module>@latest for vulnerable deps, then go mod tidy.
• D2: go get -u ./... for all, or go get <module>@latest selectively.
• D3: go mod tidy removes unused; commit go.mod and go.sum.

Step 2: Git Hygiene

G3 — Large files check:

# Top 10 largest tracked files
git ls-files -z | xargs -0 -I{} git log --diff-filter=A --format='%H' -1 -- '{}' | head -20
# Simpler: just check current tree
git ls-files -z | xargs -0 du -sh 2>/dev/null | sort -rh | head -10

G4 — .gitignore completeness:

Must include (per stack):

• Universal: .env, .env.*, *.local, .DS_Store, Thumbs.db, *.swp, .idea/, .vscode/ (or be deliberate about tracking it)
• Node: node_modules/, dist/, build/, coverage/, .turbo/, .next/
• Python: __pycache__/, *.pyc, .venv/, venv/, .mypy_cache/, .pytest_cache/, *.egg-info/
• Go: binary name (check go build -o), vendor/ (if not vendoring)

How to fix:

• G1: git branch -d <branch> for each merged local branch.
• G2: git push origin --delete <branch> for each merged remote branch. Be careful — confirm with team.
• G3: For files that shouldn't be tracked: add to .gitignore, git rm --cached <file>. For files already in history: git filter-repo or BFG Repo-Cleaner (destructive — confirm first).
• G4: Add missing patterns to .gitignore. Use a generator like gitignore.io as a starting point.
• G5: Either add to .gitignore or git add if they should be tracked.

Step 3: CI/CD Health

Skip if no CI configuration found.

How to fix:

• C2: Replace uses: actions/checkout@v4 with uses: actions/checkout@<full-sha>. Find SHA: gh api repos/actions/checkout/git/ref/tags/v4 --jq .object.sha or check the releases page.
• C3: Add explicit permissions: at job level. Start with contents: read and add only what's needed.
• C4: Remove secret interpolation. Use environment: blocks or write to files with masking.
• C5: Replace deprecated actions with current equivalents. set-output → $GITHUB_OUTPUT file.
• C6: Align versions. Use .nvmrc or engines as the source of truth.

Step 4: Code Quality Drift

How to fix:

• Q1: Triage each TODO — either do it, create an issue/task for it, or remove it if obsolete.
• Q2: Replace with a proper logger, or remove debug logging. grep -rn 'console.log' src/ to find them.
• Q3: Either fix the underlying issue and un-skip, or delete the test if the feature was removed.
• Q4–Q7: Fix the errors. Run the tool, address each issue.
• Q8: Remove unused exports, or add // ts-prune-ignore-next if they're part of the public API.

Step 5: Documentation Freshness

F4 — Broken link check:

# Find markdown links and verify targets exist
grep -roE '\[([^]]+)\]\(([^)]+)\)' *.md docs/**/*.md 2>/dev/null | \
  grep -v 'http' | \
  while IFS= read -r line; do
    # Extract path from markdown link
    path=$(echo "$line" | sed 's/.*](\([^)]*\)).*/\1/' | sed 's/#.*//')
    if [ -n "$path" ] && [ ! -e "$path" ]; then
      echo "BROKEN: $line"
    fi
  done

How to fix:

• F1: Write a README with: what it does, how to install, how to use, prerequisites, license.
• F2: Review README against current code — update examples, API docs, feature lists.
• F3: Add a CHANGELOG.md. Consider @changesets/cli for automated generation (see pre-release skill).
• F4: Update or remove broken links.
• F5: Add a LICENSE file. Use choosealicense.com if unsure.
• F6: Make LICENSE file and metadata agree.
• F7: Update AGENTS.md to reflect current project structure.

Step 6: Configuration Consistency

How to fix:

• X1: Add .editorconfig. Minimal: root = true, [*] block with indent_style, indent_size, end_of_line, insert_final_newline.
• X2: Set "strict": true in tsconfig.json. Fix resulting type errors (usually worth it).
• X3–X4: Add config files. Use the project's existing style as a baseline.
• X5–X6: Pick one source of truth (recommend engines / requires-python) and align everything else.

Step 7: Security Posture

Lightweight security checks for ongoing hygiene. For the full pre-release security audit (gitleaks, trufflehog, workflow audit), use the pre-release skill.

How to fix:

• S1: git rm --cached <file>, add to .gitignore, commit. If the file contained real secrets, rotate them immediately — they're in git history.
• S2: Create .env.example with placeholder values (<REPLACE_ME>) for every var in .env.
• S3: Move secrets to env vars or a secrets manager. Replace in code with process.env.VAR / os.environ["VAR"].
• S4: Add .gitleaks.toml (even a minimal one enables CI scanning). Or add gitleaks to pre-commit hooks.
• S5: Use least-privilege permissions (644 for files, 755 for executables).

Step 8: Project Metadata

How to fix:

• M1–M3: Add the missing fields to package.json or pyproject.toml.
• M4: Create .github/FUNDING.yml with github: <username>.
• M5: See pi package docs for required fields.

Baseline Tracking

Save a baseline after each run to detect drift over time. Store at .pi/hygiene-baseline.json:

{
  "timestamp": "2026-02-14T23:00:00Z",
  "stack": ["node"],
  "scores": {
    "dependencies": { "status": "healthy", "vulns": 0, "outdated": 3, "unused": 0 },
    "git": { "status": "healthy", "stale_branches": 0, "large_files": 0 },
    "ci": { "status": "warning", "unpinned_actions": 2, "permission_issues": 0 },
    "quality": { "status": "healthy", "todos": 5, "skipped_tests": 0, "lint_clean": true },
    "docs": { "status": "warning", "readme_stale_days": 45, "broken_links": 1 },
    "config": { "status": "healthy", "strict_ts": true, "formatter": true, "linter": true },
    "security": { "status": "healthy", "tracked_env": 0, "hardcoded_secrets": 0 },
    "metadata": { "status": "healthy", "complete": true }
  },
  "overall": "7/10"
}

On subsequent runs, compare with baseline and flag regressions:

📉 Dependencies: 0 → 3 vulnerabilities (regression since last check)
📈 Quality: 15 → 5 TODOs (improvement!)
→  CI: unchanged — 2 unpinned actions remain

When the user approves the report, offer to update the baseline.

Report Format

Present the final report as a health scorecard:

# Repo Health: <project-name>
## Score: 7/10 — GOOD
## Stack: Node.js + TypeScript
## Last check: 2026-01-15 (30 days ago) | Baseline: 6/10 📈

### 🔴 Fix Now (2)
| # | Category | Issue | Fix |
|---|----------|-------|-----|
| S1 | Security | `.env.local` tracked in git | `git rm --cached .env.local` |
| D1 | Deps | 2 high-severity npm audit findings | `npm audit fix` |

### 🟡 Fix Soon (4)
| # | Category | Issue | Fix |
|---|----------|-------|-----|
| D2 | Deps | 8 outdated packages (2 major) | `npm outdated` → upgrade |
| C2 | CI | 3 actions not pinned by SHA | Pin to commit SHA |
| F2 | Docs | README 45 days behind source | Review and update |
| Q3 | Quality | 2 skipped tests | Fix or remove |

### 🟢 Healthy (12)
- ✅ Dependencies: no unused, no phantom, lockfile fresh
- ✅ Git: clean tree, no stale branches, no large files
- ✅ Code: lint clean, build passes, tests pass, strict TS
- ✅ Config: EditorConfig, Prettier, ESLint all configured
- ✅ Security: no tracked secrets, .env.example present
- ✅ Metadata: all fields present, license matches

### 📊 Trends (vs. baseline 2026-01-15)
| Category | Then | Now | Trend |
|----------|------|-----|-------|
| Vulnerabilities | 0 | 2 | 📉 |
| Outdated deps | 5 | 8 | 📉 |
| TODOs | 15 | 8 | 📈 |
| Skipped tests | 0 | 2 | 📉 |

### Recommendations
1. **Immediate**: Fix the 2 security/vulnerability items above
2. **This week**: Pin CI actions and update stale README
3. **Ongoing**: Address skipped tests and outdated deps in next sprint

Use your project's task tracking to schedule these items.

Scoring

Calculate the score from check results:

Start at 10, apply deductions, floor at 0. Round to nearest integer.

Auto-Fix Offers

After presenting the report, offer to fix issues that are safe and mechanical. Always present what will be done and get confirmation before executing.

Safe to offer (low risk, reversible)

• Delete merged local branches (git branch -d)
• Run npm audit fix (compatible fixes only, not --force)
• Run npm dedupe / go mod tidy
• Add missing .gitignore patterns
• Add .editorconfig from template
• Remove console.log from source files
• Create .env.example from .env (with values replaced by <REPLACE_ME>)
• Add missing package.json fields (description, repository, keywords)
• Create .github/FUNDING.yml

Offer with warning (confirm carefully)

• Delete merged remote branches (git push origin --delete)
• Run npm audit fix --force (may have breaking changes)
• Major dependency upgrades
• Enable TypeScript strict mode (may produce many errors)
• Update CI action pinning (must verify correct SHAs)

Never auto-fix (explain, let user decide)

• Removing tracked .env files (may need secret rotation)
• Rewriting git history (BFG / filter-repo)
• Changing license files
• Modifying CI permissions model
• Removing hardcoded secrets (need to determine replacement strategy)

Tips

• Run early, run often. A monthly cadence catches drift before it compounds.
• Don't try to fix everything at once. Focus on 🔴 items first, batch 🟡 items into a maintenance sprint.
• Baseline tracking is your friend. Even if the score isn't perfect, trending upward means you're winning.
• Pair with pre-release. Run repo-hygiene for ongoing health, pre-release when you're ready to ship. They complement each other — hygiene keeps the baseline high so pre-release has fewer surprises.
• New repos start clean. Run this right after git init to establish a perfect baseline. It's easier to maintain 10/10 than to recover from 4/10.