// Run CodeQL security/quality analysis and fix findings. Use when the user asks to run CodeQL, security scan, static analysis, or fix CodeQL findings.
Build the project and automatically fix packaging or build errors (for example Hatch failures) and related breakage. Use when the project fails to build, shows "broken" states, or after making significant changes.
Interactive deep research and decision support: frame the real problem (XY-aware), ask exactly 10 multiple-choice questions one at a time, then produce a rigorous comparative evaluation (default 5 approaches, 0–100 scores) and recommendation. Use when the user wants structured discovery before committing to a solution, a scored comparison of approaches, or to avoid jumping straight to an answer—especially for architecture, strategy, or high-stakes trade-offs.
Run linters and fix violations, formatting errors, or style mismatches using Trunk. Use when code quality checks fail, before submitting PRs, or to repair "broken" linting states.
Manage Architecture Decision Records (ADRs). Use this to initialize, create, list, and link ADRs to document architectural evolution. Requires 'adr-tools' to be installed.
At the end of a coding agent session (Cursor, Claude Code, Codex, Gemini CLI, or similar), summarize outcomes, failures, inefficiencies, and root causes, then output a concise postmortem with ranked Must/Should/Consider improvements. Chat-only output; do not edit project files unless the user explicitly asks. Skip nit-picks and one-off mistakes.
Broadly and deeply analyze user intent (avoiding XY problems) and evaluate multiple solution approaches (default 5) with scores from 0 to 100.
| name | codeql-fix |
| description | Run CodeQL security/quality analysis and fix findings. Use when the user asks to run CodeQL, security scan, static analysis, or fix CodeQL findings. |
| compatibility | Requires [CodeQL CLI](https://github.com/github/codeql-cli-binaries/releases) on PATH (e.g. brew install codeql). Python and [uv](https://github.com/astral-sh/uv) aligned with [`.python-version`](../../../.python-version) and [`pyproject.toml`](../../../pyproject.toml). Run `uv sync` or `make setup` before analysis when findings should reflect installed dependencies (matches [`.github/workflows/codeql.yml`](../../../.github/workflows/codeql.yml)). |
Use when the user asks to run CodeQL or static analysis, or to fix CodeQL findings (see frontmatter description).
PATH (e.g. brew install codeql).uv sync, make setup, or CI-style uv sync --frozen) so results match installed dependencies.All commands below assume cd "$(git rev-parse --show-toplevel)".
Do not commit CodeQL databases or SARIF outputs (large, machine-specific). They belong in .gitignore (for example .codeql_db/, codeql-results.sarif).
dev/codeql.sh)make codeql
This creates .codeql_db, analyzes with codeql/python-queries:codeql-suites/python-security-and-quality.qls, writes codeql-results.sarif, and passes --download to resolve query packs.
Create the database (Python needs no build command for extraction):
codeql database create .codeql_db --language=python --source-root . --overwrite
Analyze and emit SARIF:
codeql database analyze .codeql_db \
"codeql/python-queries:codeql-suites/python-security-and-quality.qls" \
--format=sarif-latest \
--output=codeql-results.sarif \
--download
codeql/python-queries:codeql-suites/python-code-scanning.qls instead.--download, run codeql pack download codeql/python-queries once.View SARIF in the VS Code SARIF extension (or upload where your org uses code scanning).
paths-ignore)Use the renderer when you want paths-ignore for large or generated trees, hand-edited query blocks, or parity with GitHub code scanning YAML.
REPO="$(git rev-parse --show-toplevel)"
"$REPO/.claude/skills/codeql-fix/scripts/render-code-scanning-config.sh" "$REPO" /tmp/codeql-config.yml
codeql database create .codeql_db --language=python --source-root . --codescanning-config=/tmp/codeql-config.yml --overwrite
Then run codeql database analyze as in section 2. See references/code-scanning-config.md.
If the relevant SARIF has an empty runs[].results array, there are no CodeQL alerts to fix for that suite; stop unless the user wants a broader suite or diagnostic queries.
When SARIF findings remain:
make test, then make lint (see AGENTS.md and the Makefile; make lint runs trunk check -a).make codeql or repeat the manual create + analyze steps until clean or up to 3 iterations to avoid unbounded loops.See references/code-scanning-config.md and the official code scanning configuration reference.