菜单
Run ruff lint, ruff format, ty type-check, shared/API tests, start the API, smoke test endpoints, then kill the API. Use after editing Python files to catch errors before commit.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Undo local submissions for DevOps and Verify Journal API Implementation so you can re-test verification flows. Also supports custom requirement slugs and user scoping. Use when user says "reset local submissions", "undo local verification", "reset phase X locally", or "let me re-test verification".
Reset verification submissions for a user in production. Use when user says "reset prod submissions", "reset phase X in prod", "undo prod verification", or "reset prod for <username>".
Check Azure production health: app status, errors, latency, database, dependencies. Use when user says "check prod", "how's prod", "hows prod doing", "is prod up", "prod status", "health check", "any errors?", "how's the app doing?", or "check Azure".
Debug GitHub Actions workflow failures and Terraform errors. Use when deployment failed, Terraform state lock, CI/CD pipeline errors, or troubleshooting deploy.yml.
Query production PostgreSQL with Entra ID auth, for investigating users, debugging duplicates, or ad-hoc queries. Use when user says "query prod db", "check prod database", "look up a user in prod", "run a query against production", or "investigate prod data".
Review comments on an active pull request and decide whether to accept, iterate, or reject the changes suggested in each comment. Use when user says "review PR comments", "address review comments", "go through the PR feedback", or "handle the comments on my PR".
| name | validate |
| description | Run ruff lint, ruff format, ty type-check, shared/API tests, start the API, smoke test endpoints, then kill the API. Use after editing Python files to catch errors before commit. |
Run linting, formatting, type checking, shared/API tests, start the API, smoke test endpoints, then clean up.
All steps are mandatory. Do not skip API startup and smoke tests.
Skipping API startup means import errors, circular imports, and route registration bugs won't be caught until production.
Always start fresh.
lsof -ti:8000 | xargs kill -9 2>/dev/null || true
Run the workspace static checks, which cover ruff lint, ruff format, and ty type checking across every project at once:
cd <workspace>
uv run poe static
This is the same command the Quality Gates section of
.github/copilot-instructions.md and CI use, so there is a single source of
truth for the command.
If lint errors are found: show them and offer to auto-fix with uv run ruff check --fix <file>.
If formatting is needed: offer to fix with uv run ruff format <file>.
Static checks pass before moving on to starting the API.
This step catches errors that static analysis misses:
cd <workspace>/api
uv run python -m uvicorn learn_to_cloud.main:app --host 127.0.0.1 --port 8000 &
echo $! > .api-pid
sleep 3
curl -s --max-time 5 http://localhost:8000/health
Expected: {"status":"healthy",...}
If health check fails, check terminal output for startup errors.
curl -s http://localhost:8000/health
curl -s http://localhost:8000/ready
curl -s http://localhost:8000/openapi.json | head -c 200
| Endpoint | Expected |
|---|---|
/health | {"status":"healthy",...} |
/ready | {"status":"ready",...} (200) or 503 if starting |
/openapi.json | Valid JSON starting with {"openapi":"3.1.0"... |
Why /openapi.json is critical: It forces FastAPI to introspect ALL routes and schemas, catching import errors and schema validation issues.
Always kill the API at the end of validation.
if [ -f <workspace>/api/.api-pid ]; then
kill $(cat <workspace>/api/.api-pid) 2>/dev/null
rm <workspace>/api/.api-pid
fi
lsof -ti:8000 | xargs kill -9 2>/dev/null || true
If the changes affect logic (not just formatting/docs), run the test suites.
The poe test task runs every project's tests with coverage plus the
verification import smoke test:
cd <workspace> && uv run poe test
For faster, focused feedback on a single project while iterating, you can run that project's tests directly and stop on the first failure:
cd <workspace>/api && uv run pytest tests/ -x
cd <workspace>/packages/learn-to-cloud-shared && uv run pytest tests/ -x
When mandatory: Changes to repositories, services, routes, models, schemas, shared verification, or Functions code.
Mandatory when this change adds or modifies a .github/workflows/deploy.yml step that runs a Python script or command.
CI runs scripts with a minimal env (just DATABASE__URL is set in the ci job). Local dev shells almost always have more env vars set (devcontainer, .env files, shell history). Scripts that work locally can blow up in CI because they touch settings/config that demand env vars CI doesn't have.
This step caught a real production failure (issue #469: validate_content.py instantiated WebSettings which required OAUTH__CLIENT_ID/OAUTH__CLIENT_SECRET, both unset in CI).
Strip your shell to bare essentials, then re-run the new CI step's command exactly as it appears in the workflow:
env -i HOME=$HOME PATH=$PATH \
DATABASE__URL="postgresql+asyncpg://postgres:postgres@db:5432/learntocloud" \
uv run python <path/to/new_script.py>
env -i clears all env vars. HOME and PATH are kept so uv and Python work. DATABASE__URL matches the value in deploy.yml's ci job env block.
If the new CI step uses additional env vars in the workflow, add them here too, only the ones the workflow sets.
pydantic_core.ValidationError, KeyError, or EnvironmentError for missing configThe script depends on something CI doesn't provide. Options in order of preference:
__file__ instead of reading Settings.content_dir_path).configure_settings(WorkerSettings) or configure_settings(DatabaseSettings) at script top before importing modules that touch the settings tree. Suppress E402 on the late import with # noqa: E402 and a comment explaining why.env: block. Last resort -- expands CI's env surface and risks hiding similar issues in future scripts.Only when the workflow change is purely YAML restructuring with no new Python invocation -- e.g., reordering steps, renaming, changing concurrency keys.
| Task | Command |
|---|---|
| Kill API | lsof -ti:8000 | xargs kill -9 2>/dev/null || true |
| Static checks (lint / format / type-check) | uv run poe static (single source of truth) |
| Lint + fix | uv run ruff check --fix <file> |
| Format fix | uv run ruff format <file> |
| Health check | curl -s http://localhost:8000/health |
When user says "validate changes" after editing <file>:
## Validation: <filename>
### 0. Kill Existing API
✅ Cleaned up / ⚠️ No process running
### 1. Ruff Lint
✅ No issues / ❌ X issues found (list them)
### 2. Ruff Format
✅ Formatted correctly / ❌ Needs formatting (offer to fix)
### 3. ty Type Check
✅ No type errors / ❌ X errors (list them)
### 4. API Startup
✅ "Application startup complete" / ❌ Failed to start (show error)
### 5. Endpoint Smoke Tests
| Endpoint | Status | Response |
|----------|--------|----------|
| /health | ✅ 200 | healthy |
| /ready | ✅ 200 | ready |
| /openapi.json | ✅ 200 | Valid JSON |
### 6. Cleanup
✅ API process killed
### 7. Run Tests (Optional)
✅ All passed / ❌ X failures (list them)
### 8. CI Env Parity (only if new CI step added)
✅ Passed in stripped env / ❌ Failed -- fix script or workflow / N/A -- no CI step added
Cause: Previous API process wasn't cleaned up.
Solution: Run Step 0 cleanup, or: lsof -ti:8000 | xargs kill -9