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