Skip to content

joedaws/agent-techniques / .claude/skills/maintain

maintain

Verified

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.

FileKindSize
SKILL.mdskill md5.4 KB
---
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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall