majiayu000 Stack Health Audit
Comprehensive codebase and infrastructure health monitoring to prevent accumulated issues from causing development "time loops".
When to Use This Skill
- Routinely: At session start and before major changes
- Before commits: Quick validation before committing
- After deployments: Verify stack health post-deploy
- Debugging: When something feels off but you can't pinpoint it
- CI/CD integration: As part of automated health checks
How to Run
Quick Mode (Skip Build)
python3 scripts/ops/stack_audit.py --quick
Full Audit
python3 scripts/ops/stack_audit.py
JSON Output (for parsing)
python3 scripts/ops/stack_audit.py --json
Dry Run (no report file)
python3 scripts/ops/stack_audit.py --no-report
10 Health Checks
| Check | What It Validates |
|---|---|
| Frontend Type Check | TypeScript strict mode errors |
| Frontend Lint | ESLint warnings and errors |
| Frontend Build | Next.js build success (skipped in --quick) |
| Backend Lint (Ruff) | Python linting |
| Backend Type Check (mypy) | Python type checking |
| Migration State | Alembic migration consistency |
| Alembic Head Sync | DB is at latest migration head |
| Docker Containers | Container health status |
| API Health | Endpoint availability, CORS, pagination, schema |
| Sacred Backups | Backup existence and freshness |
Status Levels
| Status | Meaning | Exit Code |
|---|---|---|
| GREEN | All checks pass | 0 |
| YELLOW | Warnings only | 1 |
| RED | Errors detected | 2 |
Report Location
Reports are written to:
.claude/dontreadme/stack-health/YYYY-MM-DD_HHMMSS.md
Trend analysis compares current run to previous runs for pattern detection.
Integration with Celery
The audit runs automatically via Celery every 4 hours:
# backend/app/tasks/stack_health_tasks.py
@celery.task(name="stack.health_check")
def stack_health_check():
"""Run comprehensive stack health audit."""
Antigravity Recommendations
The following checks were added based on antigravity session recommendations:
- API Pagination - Verify APIs handle limit/offset correctly
- Schema Validation - Check activity_type enum values match expected
- Alembic Head Sync - Ensure DB migrations are current
- Block Dates API - Verify blocks endpoint returns valid data
- CORS Headers - Check CORS configuration
- Sacred Backups - Verify backups exist before major changes
Example Output
Running stack health audit...
[1/10] Frontend type-check...
[2/10] Frontend lint...
[3/10] Frontend build...
[4/10] Backend lint (Ruff)...
[5/10] Backend type-check (mypy)...
[6/10] Migration state...
[7/10] Alembic head sync...
[8/10] Docker containers...
[9/10] API health & data integrity...
[10/10] Sacred backups...
======================================================================
Stack Health: GREEN
======================================================================
Frontend Type Check: PASS (0 issues)
Frontend Lint: PASS (0 issues)
...
When Issues Are Found
RED Status Actions
- Review the generated report in
.claude/dontreadme/stack-health/ - Address blocking issues first (FAIL status)
- Re-run after fixes to confirm resolution
- Check trend analysis for recurring patterns
Common Fixes
| Issue | Fix |
|---|---|
| Frontend Type Errors | npm run type-check then fix errors |
| Alembic Out of Sync | alembic upgrade head |
| Missing Backups | ./scripts/backup_db.sh before schema changes |
| Docker Unhealthy | docker-compose restart <service> |
| API Errors | Check backend logs: docker-compose logs -f backend |
Related Skills
/lint-monorepo- Focus on linting only/qa-party- Comprehensive QA validation/deployment-validator- Pre-deploy validation/systematic-debugger- When issues need investigation
Script location: scripts/ops/stack_audit.py
Celery task: backend/app/tasks/stack_health_tasks.py