name: run-all-checks description: Run all linting, type checking, tests, Markdown lint, and documentation build for the project. Check for errors and warnings, then fix any problems found. Use when the user asks to run checks, verify the build, run CI locally, or fix lint/type/test errors.

Run All Checks

Execute all project checks (lint, typecheck, test, Markdown lint, docs) and fix any errors found. This skill aligns with the scripts/run-all-checks.sh script and a standard Python package layout (e.g. src/, tests/, docs/).

Quick Start

1. Run all checks (optionally in parallel via the script).
2. Review output for errors and warnings.
3. Fix any issues found.
4. Re-run checks to verify fixes.

Check Commands

Run from project root with the project virtual environment activated (e.g. source venv/bin/activate or create a new venv and then pip install -e ".[dev]").

Code (ruff, mypy, pytest)

# Lint (ruff)
python -m ruff check src tests examples
python -m ruff format --check src tests examples

# Type check (mypy)
python -m mypy src tests examples

# Tests (pytest; use -n auto for parallel when tests are independent)
python -m pytest tests -q

Omit examples if the project has no examples/ directory. The run-all-checks script runs these in sequence; use the script’s -c option to run only code checks.

Markdown (PyMarkdown)

python -m pymarkdown scan docs/ .cursor/ README.md CONTRIBUTING.md

Use the script’s -m option to run only Markdown lint.

Documentation (Sphinx)

cd docs && make clean && make html SPHINXOPTS="-W"

Warnings are treated as errors (-W). The script’s -d option runs docs build plus Markdown lint.

Using the Script

From project root:

./scripts/run-all-checks.sh

Options:

• Default: Run code checks and docs (Sphinx + PyMarkdown) in parallel.
• -c, --code: Only ruff, mypy, pytest.
• -d, --docs: Only Sphinx build and PyMarkdown scan.
• -m, --markdown: Only PyMarkdown scan.
• -s, --sequential: Run code and docs sequentially (easier to read output).
• -p, --parallel: Run code and docs in parallel (the default).
• -h, --help: Show usage.

Set VENV or VENV_PATH to point to the virtual environment if it is not at ./venv.

Execution Workflow

Check Progress:
- [ ] Ruff check (src, tests, examples)
- [ ] Ruff format --check
- [ ] Mypy (src, tests, examples)
- [ ] Pytest (tests)
- [ ] PyMarkdown scan (docs/, .cursor/, README, CONTRIBUTING)
- [ ] Sphinx build (docs/) with SPHINXOPTS="-W"
- [ ] All errors fixed
- [ ] Re-verify all checks pass

Step 1: Run Checks

Use the script (recommended) or run the commands above manually. Fix any non-zero exit codes.

Step 2: Analyze Results

• Errors: Must be fixed (non-zero exit).
• Warnings: Sphinx is run with -W, so docs warnings fail the check; fix them so the build passes.

Common error types:

Step 3: Fix Issues

For each error: read the message, open the file and line, apply the fix. Re-run the failing check to confirm.

Step 4: Re-verify

Run the full script again; all checks should pass (exit code 0).

Common Fixes Reference

Ruff unused argument (ARG001)

For fixtures that are dependencies but not directly used:

def my_fixture(other_fixture: None) -> None:  # noqa: ARG001
    ...

Sphinx duplicate object warning

Add :no-index: to the automodule directive where appropriate:

.. automodule:: mypackage.module
   :members:
   :no-index:

Coverage threshold

If coverage is below the project target (e.g. 80%): add tests or, temporarily, adjust [tool.coverage.report] / threshold in config. Prefer adding tests.

Type annotation issues

For forward reference or union syntax issues:

from __future__ import annotations  # at top of file

Success Criteria

All checks pass when:

• ruff check → All checks passed
• ruff format --check → Would reformat 0 files (or run ruff format and re-check)
• mypy → Success: no issues found
• pytest → All tests pass; coverage meets target if configured
• pymarkdown scan → No violations
• make html SPHINXOPTS="-W" (in docs/) → Build completes with exit 0