ReddRadar
Agent skill
stack-audit
Comprehensive stack health audit for codebase and infrastructure. Runs 10 health checks covering frontend, backend, migrations, Docker, API integrity, and backup status. Use routinely to prevent "time loops" from accumulated issues.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/stack-audit
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?