Menu
How to create and use our alembic database migration tool. Use when making changes to models.py.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when the user asks to update, sync, or refresh the Hawk docs (quickstart, configuration reference, infrastructure description and diagrams) to reflect changes since the last documentation sync. Triggers on "update the docs", "sync docs", "docs are stale", "refresh quickstart", "update the architecture diagram", or after merging infra/config/CLI changes that affect user-visible setup.
Debug stuck Hawk/Inspect AI evaluations. Use when user mentions "stuck eval", "eval not progressing", "eval hanging", "samples not completing", "eval set frozen", "runner stuck", "500 errors in eval", "retry loop", "eval timeout", or asks why an evaluation isn't finishing.
How to develop the frontend and backend together. When you want to make changes to the UI, use this.
Monitor Hawk job status, view logs, and diagnose issues. Use when the user wants to check job progress, view error logs, debug a failing job, or generate a monitoring report for a Hawk evaluation run.
Run smoke tests on a deployed environment to ensure basic functionality.
View and analyze Hawk evaluation results. Use when the user wants to see eval-set results, check evaluation status, list samples, view transcripts, or analyze agent behavior from a completed evaluation run.
| name | database-migrations |
| description | How to create and use our alembic database migration tool. Use when making changes to models.py. |
Do not write out alembic migrations yourself. Use the alembic tool to generate and apply migrations. You do not need to give alembic the path to alembic.ini. Do not manually drop any tables or columns in the DB. Always use alembic migrations to make schema changes.
Alembic depends on having a valid DATABASE_URL set (the alembic env reads it from the environment). The username should be inspect_admin. The password is generated automatically via RDS IAM.
Get the admin URL from the stack's Pulumi output database_url_admin:
export DATABASE_URL=$(AWS_PROFILE=staging pulumi stack output database_url_admin -s <stack>)
(This is the same URL scripts/dev/generate-env.py <stack> --api writes as HAWK_API_DATABASE_URL.) Keep AWS_PROFILE=staging set for RDS IAM auth and Pulumi.
Run alembic from hawk/core/db (where the alembic config lives) — you don't need to pass it the path to alembic.ini.
To create a new migration, run:
alembic revision --autogenerate -m "description of changes"
Run ruff check --fix && ruff format to silence any formatting issues in the generated migration file.
You may need to ensure the DB is up to date before generating a new migration. Run:
alembic upgrade head
If we want to regenerate a migration file (in a branch we're working on after making schema changes since the last migration), we can delete the previous migration file and run the revision command again.
alembic downgrade -1 to revert the last migration.alembic upgrade head to ensure the DB is up to date.Run the tests in tests/core/db/test_alembic_migrations.py