tomevault-io Project Auditor Skill
Overview
A healthy project is one where developers can ship confidently. This skill guides systematic assessment of project health—configuration, dependencies, CI/CD, and technical debt.
Core principle: Audit to enable, not to blame. Find issues that slow the team down and prioritize fixes by impact.
The Audit Process
Phase 1: Quick Health Check
Get a baseline in 5 minutes:
Check the Basics
- README exists and is useful?
- Can you run the project in < 10 minutes?
- Are there tests? Do they pass?
Check Dependencies
npm outdated && npm audit # Node pip list --outdated # Python go list -m -u all # GoCheck CI/CD
- Pipeline exists?
- Tests run on PR?
- Main branch protected?
Phase 2: Deep Assessment
Systematic evaluation:
Configuration Completeness
- All required files present?
- Linting configured and enforced?
- Secrets properly managed?
Dependency Health
- How many outdated?
- Any with known vulnerabilities?
- Any abandoned/unmaintained?
Code Quality Indicators
- Test coverage?
- Consistent code style?
- Documentation coverage?
Phase 3: Prioritized Report
Findings that drive action:
Categorize by Impact
- Critical: Security, can't build/deploy
- High: Slows development significantly
- Medium: Causes friction
- Low: Nice to fix
Recommend Next Steps
- What to fix first?
- Quick wins vs. larger efforts
- Dependencies between fixes
Red Flags - Critical Issues
Security Critical
- Secrets in code or git history
- Dependencies with known CVEs
- No security scanning in CI
- Missing authentication on endpoints
- .env files committed
Operational Critical
- Can't build from clean checkout
- No CI/CD pipeline
- Main branch accepts direct pushes
- No automated tests
- Missing LICENSE file
Maintainability Critical
- No README or it's useless
- Dependencies 2+ major versions behind
- No linting or formatting rules
- Mix of conflicting patterns
- Circular dependencies
Audit Checklist
Configuration Files
| File | Status | Notes |
|---|---|---|
| README.md | ☐ | Useful quick start? |
| LICENSE | ☐ | Appropriate license? |
| .gitignore | ☐ | Covers all artifacts? |
| CI config | ☐ | Tests, lint, security? |
| Linter config | ☐ | Enforced in CI? |
| .env.example | ☐ | Documents all vars? |
Dependency Health
| Check | Status | Notes |
|---|---|---|
| Outdated count | ☐ | How many? |
| Vulnerable count | ☐ | npm audit / pip-audit |
| Lock file | ☐ | Committed? |
| Unused deps | ☐ | depcheck / pipdeptree |
CI/CD Pipeline
| Check | Status | Notes |
|---|---|---|
| Pipeline exists | ☐ | GH Actions, etc? |
| Tests run | ☐ | On every PR? |
| Linting | ☐ | Enforced? |
| Security scan | ☐ | Dependabot, etc? |
| Branch protection | ☐ | Reviews required? |
Code Quality
| Check | Status | Notes |
|---|---|---|
| Test coverage | ☐ | % covered? |
| Code style | ☐ | Consistent? |
| Documentation | ☐ | API docs? |
| Type coverage | ☐ | Types used? |
Common Rationalizations - Don't Accept These
| Excuse | Reality |
|---|---|
| "We'll fix it after launch" | Post-launch is harder. Fix now. |
| "It's technical debt we know about" | Known debt still costs. Quantify it. |
| "Dependencies work fine" | Until they have a CVE. Update regularly. |
| "CI is too slow" | Slow CI > no CI. Then make it faster. |
| "Tests are flaky" | Flaky tests are worse than no tests. Fix or delete. |
Audit Report Template
# Project Audit: [Name]
Date: [Date]
## Executive Summary
- Overall Health: [Good/Fair/Poor]
- Critical Issues: [Count]
- Recommended Priority: [What to fix first]
## Findings
### Critical
1. [Issue]: [Impact] → [Recommendation]
### High
1. [Issue]: [Impact] → [Recommendation]
### Medium
1. [Issue]: [Impact] → [Recommendation]
## Metrics
- Dependencies: [X] total, [Y] outdated, [Z] vulnerable
- Test Coverage: [X]%
- CI Status: [Passing/Failing/None]
## Recommended Actions
1. [First priority - why it's first]
2. [Second priority]
3. [Third priority]
Quick Audit Commands
# Node.js
npm outdated
npm audit
npx depcheck
# Python
pip list --outdated
pip-audit
pipdeptree
# Go
go list -m -u all
govulncheck ./...
# General
git log --oneline -20 # Recent activity
git shortlog -sn # Contributors
wc -l **/*.ts # Lines of code
References
Detailed patterns and examples in references/:
project-checklist.md- Comprehensive setup checklistdependency-management.md- Keeping deps healthycicd-patterns.md- Pipeline best practices
Converted and distributed by TomeVault — claim your Tome and manage your conversions.