Menú
Run comprehensive project health checks including code quality, documentation, git status, and project structure
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Conduct thorough code reviews for pull requests and pre-commit changes
Check CI/CD workflow status and troubleshoot failing checks in GitHub Actions
Initialize .docent/ directory structure and configuration for a new project
Comprehensive guide for AI agents on proactive documentation capture using /docent:tell
Migrate a docent v0.9 project to v1.0 skills-based architecture
Review journal entries and extract valuable knowledge into formal documentation
| name | health-check |
| description | Run comprehensive project health checks including code quality, documentation, git status, and project structure |
| group | development |
| keywords | ["health","quality","validation","pre-release","check","health check","validate"] |
| version | 1.0.0 |
| author | docent |
This runbook performs comprehensive project health checks, validating code quality, documentation completeness, git status, and overall project hygiene. Especially useful before releases or major commits.
Identify potential issues across multiple dimensions:
Purpose: Find console.log, debugger statements, and debug comments that shouldn't be in production
Actions:
# Search for common debug patterns in source files
rg "console\.(log|debug|info|warn|error)" --type js --type ts --type jsx --type tsx src/
# Search for debugger statements
rg "debugger" --type js --type ts --type jsx --type tsx src/
# Search for TODO/FIXME comments that should be issues
rg "TODO.*remove|FIXME.*before.*release|XXX" src/
Red Flags:
console.log() in production codedebugger statementsTODO: remove before releaseFIXME: before shippingXXX markersSeverity: WARNING (may be intentional logging) → ERROR (if found in critical paths)
Fix: Remove debug code or convert TODO comments to GitHub issues
Purpose: Find .only() and .skip() calls that prevent full test suite from running
Actions:
# Find test files with .only()
rg "\.only\(" --type js --type ts test/ src/
# Find test files with .skip()
rg "\.skip\(" --type js --type ts test/ src/
# Find xdescribe, xit (Jasmine/Jest)
rg "xdescribe|xit\(" --type js --type ts test/ src/
Red Flags:
.only() - Runs only that test, skips others.skip() - Skips test entirelyxdescribe, xit - Disabled testsSeverity: ERROR (prevents full test coverage validation)
Fix: Remove .only()/.skip() or document why test is disabled
Purpose: Find broken internal links in markdown documentation
Actions:
# Find all markdown files
find .docent/ docs/ -name "*.md" -type f 2>/dev/null
# For each markdown file:
# - Extract markdown links: [text](path)
# - Extract relative file paths
# - Verify each referenced file exists
# Example pattern for link extraction:
rg '\[.*?\]\((.*?)\)' --only-matching --no-filename .docent/ docs/ 2>/dev/null | sort -u
Check:
Severity: WARNING (broken docs links)
Fix: Update links to correct paths or remove broken references
Purpose: Assess if documentation is complete and current
Dimensions:
Actions:
# Check for documented features that exist
ls -1 .docent/ docs/ 2>/dev/null
# Look for common documentation patterns
find .docent/ docs/ -name "*.md" -type f -exec wc -l {} + 2>/dev/null
# Check for empty or stub documentation
find .docent/ docs/ -name "*.md" -type f -size -100c 2>/dev/null
Indicators of issues:
Severity: WARNING (incomplete docs) → INFO (documentation suggestions)
Fix: Create missing documentation, update outdated content
Purpose: Ensure working directory is clean before releases
Actions:
# Check git status
git status --porcelain
# Check for staged but uncommitted
git diff --cached --stat
# Check for unstaged changes
git diff --stat
# Check for untracked files (excluding .gitignore patterns)
git ls-files --others --exclude-standard
Red Flags:
Severity: ERROR (before release) → WARNING (during development)
Fix: Commit changes, add to .gitignore, or document why files are uncommitted
Purpose: Find temporary, backup, or generated files that shouldn't be committed
Actions:
# Find common temporary file patterns
find . -name "*.tmp" -o -name "*.bak" -o -name "*~" -o -name ".DS_Store" 2>/dev/null
# Find editor backup files
find . -name "*.swp" -o -name "*.swo" -o -name "*~" 2>/dev/null
# Find common cache directories not in .gitignore
find . -type d -name "__pycache__" -o -name ".pytest_cache" -o -name "node_modules" 2>/dev/null | head -5
Red Flags:
.tmp, .bak, ~ backup files.swp, .swo).DS_Store)Severity: WARNING (cleanup recommended)
Fix: Remove temporary files, add patterns to .gitignore
Purpose: Verify that documented project structure matches actual structure
Actions:
# Compare documented structure with actual
# 1. Look for ARCHITECTURE.md or similar docs describing structure
find .docent/ docs/ -name "*ARCHITECTURE*" -o -name "*STRUCTURE*" -type f 2>/dev/null
# 2. List actual directory structure
find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
# 3. Identify discrepancies (requires semantic analysis)
Check:
Severity: INFO (documentation update suggestion)
Fix: Update documentation to reflect current structure
Calculate overall health score (0-100):
Base score: 100
Deductions:
- ERROR findings: -10 points each
- WARNING findings: -5 points each
- INFO findings: -1 point each
Minimum score: 0
Maximum score: 100
Interpretation:
Show only issues found:
🏥 Project Health Check
❌ 2 errors found
⚠️ 3 warnings found
ℹ️ 1 info
Errors:
- [debug-code] console.log found in src/api/handler.ts:45
- [test-markers] .only() found in test/api.test.ts:12
Warnings:
- [broken-links] Link to missing file in docs/guide.md:23
- [uncommitted] 3 modified files not committed
- [temp-files] 2 .tmp files found in src/
Info:
- [structure] New directory src/utils/ not documented
Health Score: 65/100 (Fair)
Run with --verbose for detailed output and fixes.
Show detailed information with context and fix suggestions:
🏥 Project Health Check (Verbose)
## Check: Debug Code
❌ ERROR: console.log statements found
Found in src/api/handler.ts:
Line 45: console.log('Processing request:', req)
Line 67: console.log('Response:', response)
Fix: Remove console.log or use proper logging library:
import {logger} from './logger'
logger.debug('Processing request:', req)
## Check: Test Markers
❌ ERROR: .only() restricts test execution
Found in test/api.test.ts:
Line 12: describe.only('API tests', () => {
Fix: Remove .only() to run full test suite:
describe('API tests', () => {
[... detailed output for all checks ...]
Health Score: 65/100 (Fair)
Total Checks: 7
Passed: 4
Failed: 3
Run only fast mechanical checks, skip semantic analysis:
Completes in < 5 seconds
If: Cannot read certain files/directories Action: Report skipped checks, continue with accessible files
If: Git commands fail (not a git repo) Action: Skip git-related checks, note in output
If: Searches take too long (> 30 seconds) Action: Use --quick mode or limit search scope to specific directories
After completion, health check should report:
Fix: Address ERROR findings first, then WARNINGs, then INFOs
Fix: Configure check exceptions in .docent/config.yaml:
health-check:
ignore-patterns:
debug-code:
- src/debug-utils.ts # Intentional debug utilities
test-markers:
- test/manual/ # Manual test suite
Fix: Use --quick mode or specify --checks to run only specific checks