---
name: format-lint-assistant
description: Run the project's formatter, linters, and mypy checks in the required order, fixing issues and managing any needed stub dependencies via uv.
---

# Format and Lint Assistant

## Quick start
- Run `make format` before linting to apply project formatting.
- Run `make lint`; fix linter errors first, rerun `make lint`, then address any remaining mypy issues.
- If mypy needs missing stubs/libs, add them with `uv add --dev <package>` so they land in `pyproject.toml`; never use mypy's install-missing-libraries command.
- Keep rerunning `make lint` until it passes cleanly; share any unresolved issues.
- See `references/linting_rules.md` for the exact workflow.

## Workflow
1) **Prepare and format**  
   - Review the scope of files to format/lint.  
   - Run `make format` to apply formatting before linting.  

2) **Lint and iterate**  
   - Run `make lint`.  
   - If linters fail, fix those issues first and rerun `make lint` to confirm the lint portion is clean.  
   - After lint fixes, address mypy errors reported by the same command, then rerun `make lint` to verify.  

3) **Manage dependencies**  
   - When mypy reports missing libraries or type stubs, add the needed package with `uv add --dev <package>` so it updates the dev dependencies in `pyproject.toml`.  
   - Do **not** use mypy's automatic install-missing-libraries flag.  

4) **Validate and report**  
   - Run `make lint` once more after all fixes to ensure a clean result.  
   - Summarize what was run, what was fixed, and call out any remaining issues.