joedaws/agent-techniques / .claude/skills/maintain
maintain
VerifiedUse to run a periodic codebase-health pass — dependency audit, lint, test suite, dead code / TODO scan, doc freshness, task hygiene, and build artifacts. Conservative by default (small fixes inline, larger work files a maintenance task). Trigger when the user says "maintenance", "health check", "audit dependencies", "/maintain", or asks for a periodic project tidy-up.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.4 KB |
SKILL.md
View on GitHub---
name: maintain
description: Use to run a periodic codebase-health pass — dependency audit, lint, test suite, dead code / TODO scan, doc freshness, task hygiene, and build artifacts. Conservative by default (small fixes inline, larger work files a maintenance task). Trigger when the user says "maintenance", "health check", "audit dependencies", "/maintain", or asks for a periodic project tidy-up.
---
# Maintain — codebase maintenance pass
Run a structured codebase maintenance pass. This is a periodic health check — not a pre-commit review. Check each section, report findings, and fix what you can.
## 1. Dependency health
Detect the project's toolchain and audit dependencies:
**Rust** (if `Cargo.toml` exists):
```bash
cargo update --dry-run 2>&1 | head -30
```
Check for outdated or yanked crates. If `cargo-audit` is available:
```bash
cargo audit 2>/dev/null || echo "cargo-audit not installed — skip"
```
**Node** (if `package.json` exists):
```bash
npm outdated 2>/dev/null || echo "npm outdated not available"
npm audit --audit-level=moderate 2>/dev/null || echo "npm audit not available"
```
**Python** (if `pyproject.toml` or `requirements.txt` exists):
```bash
uv pip list --outdated 2>/dev/null || pip list --outdated 2>/dev/null || echo "skip"
```
**Elixir** (if `mix.exs` exists):
```bash
mix hex.outdated 2>/dev/null || echo "mix hex.outdated not available"
mix deps.audit 2>/dev/null || echo "mix deps.audit not available"
```
Report: list any dependencies with known vulnerabilities or major version bumps available.
## 2. Lint and format check
Run the full lint suite without fixing — report-only mode:
**Rust**:
```bash
cargo clippy -- -D warnings 2>&1
cargo fmt --check 2>&1
```
**Node/TypeScript**:
```bash
npx eslint . 2>/dev/null || npm run lint 2>/dev/null
```
**Python**:
```bash
ruff check . 2>/dev/null || uv run ruff check . 2>/dev/null
```
**Go**:
```bash
go vet ./... 2>/dev/null
gofmt -l . 2>/dev/null
```
**Elixir**:
```bash
mix format --check-formatted 2>&1
mix credo --strict 2>&1
```
Count warnings and errors. If any are found, fix them.
## 3. Test suite health
Run the full test suite and assess health:
**Rust**: `cargo test 2>&1`
**Node**: `npm test 2>&1`
**Python**: `uv run pytest 2>/dev/null || pytest 2>/dev/null`
**Go**: `go test ./... 2>/dev/null`
**Elixir**: `mix test 2>&1`
Report:
- Total tests, passed, failed, skipped
- Any flaky tests (if visible from output)
- Tests that are unusually slow
## 4. Dead code and stale patterns
Search the codebase for patterns that indicate maintenance debt:
```
TODO, FIXME, HACK, XXX, DEPRECATED
```
Also search for:
- `#[allow(dead_code)]` or `#[allow(unused)]` in Rust
- `// eslint-disable` or `// @ts-ignore` in TypeScript/JavaScript
- Unused imports (from lint output in step 2)
- Empty `catch` blocks or swallowed errors
For each finding, decide:
- **Fix now** if it's a quick cleanup (remove unused import, delete dead code)
- **File a task** if it requires more work: `task add "<description>" project:<repo> +maintenance`
## 5. Documentation freshness
Check that key documentation files exist and aren't stale:
- `README.md` — exists?
- `CHANGELOG.md` — has entries for recent work?
- `CLAUDE.md` — exists and reflects current project structure?
Read the first 20 lines of each to assess whether they're current. Flag any that reference features or structures that no longer exist.
## 6. Task hygiene
Scan stale or blocked tasks:
```bash
task status:pending list
```
Check for:
- **Stale tasks**: pending tasks that haven't been touched recently and may be obsolete
- **Duplicate tasks**: multiple tasks describing the same work
- **Missing project/tags**: tasks without a `project:` or category tag
- **Blocked tasks**: tasks waiting on a dependency that's already done
For larger findings, file a task instead of fixing inline: `task add "<title>" project:<repo> +maintenance`. For each finding, suggest an action (delete, merge, tag, etc.) but do not delete tasks without user confirmation.
## 7. Build artifact cleanup
Check for build artifacts or temp files that shouldn't be tracked:
```bash
git status --ignored --short 2>/dev/null | head -20
```
Verify `.gitignore` covers common patterns for the detected languages.
## 8. Print maintenance report
Print a summary using this format:
```
Maintenance Report
==================
Dependencies: [OK | N outdated | N vulnerable]
Lint: [OK | N warnings | N errors]
Format: [OK | N files need formatting]
Tests: [N passed, N failed, N skipped]
Dead code/TODOs: [OK | N items found]
Documentation: [OK | N files stale]
Task hygiene: [OK | N tasks need attention]
Build artifacts: [OK | N items to clean]
Actions taken:
- Fixed N lint warnings
- Removed N dead code items
- Created N maintenance tasks
Recommended follow-ups:
- <list of items that need human attention>
```
## Constraints
- Do not make breaking changes. Maintenance is conservative — fix warnings, remove dead code, update docs.
- Do not update dependency versions without checking for breaking changes first. Report outdated deps; only update patch versions automatically.
- Do not delete tasks without user confirmation — only suggest closures.
- Do not modify test behavior — only fix test infrastructure issues (imports, configs).
- If a fix would touch more than 10 lines, create a task for it instead of fixing inline.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |