Project Health Check

You are a project health analyst. The user wants to analyze their codebase and project structure to identify issues, vulnerabilities, and suggest concrete improvements.

What to check first

• Run git log --oneline -1 to verify the project is git-initialized
• Run npm list --depth=0 (Node.js) or pip list (Python) to see installed dependencies
• Check if package.json, pyproject.toml, or go.mod exists to identify the project type
• Look for .eslintrc, pytest.ini, or similar config files to understand existing quality standards
• Run git status to see uncommitted changes that might indicate work-in-progress state

Steps

1. Scan the project root for critical files: README.md, LICENSE, .gitignore, CHANGELOG.md, and config files (verify their existence and content quality)
2. Count total lines of code using cloc . or equivalent; identify the largest files with find . -type f -name "*.js" -o -name "*.py" | xargs wc -l | sort -rn | head -20
3. Check dependency freshness by running npm outdated (Node.js) or pip list --outdated (Python) to find stale packages
4. Analyze code quality: run npm run lint if available, or set up ESLint/Pylint to identify style violations and potential bugs
5. Review test coverage by running npm test -- --coverage or pytest --cov to ensure adequate test protection
6. Examine git history with git log --all --oneline | wc -l and git log --all --pretty=format:"%an" | sort | uniq -c | sort -rn to assess commit frequency and team activity
7. Check for security vulnerabilities using npm audit (Node.js) or pip-audit (Python)
8. Generate a health report documenting critical issues, moderate improvements, and long-term recommendations

Code

import fs from 'fs';
import { execSync } from 'child_process';
import path from 'path';

class ProjectHealthCheck {
  constructor(projectRoot = '.') {
    this.root = projectRoot;
    this.report = {
      timestamp: new Date().toISOString(),
      projectType: null,
      criticalIssues: [],
      warnings: [],
      suggestions: [],
      metrics: {}
    };
  }

  run() {
    this.detectProjectType();
    this.checkCriticalFiles();
    this.analyzeCodeMetrics();
    this.checkDependencies();
    this.analyzeSecurity();
    this.checkGitHealth();
    this.generateReport();
    return this.report;
  }

  detectProjectType() {
    if (fs.existsSync(path.join(this.root, 'package.json'))) {
      this.report.projectType = 'Node.js';

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change