Code Quality

Code Quality Check

This skill runs code quality tools (ruff, mypy, pytest) and optionally simplifies code.

Usage

/code-quality [options]

Options

• --all or -a: Run on all synapse/ files (default: recently modified files only)
• --no-simplify: Skip code-simplifier agent (by default, code-simplifier runs after checks pass)
• --fix or -f: Auto-fix ruff issues with --fix flag
• --test or -t: Run pytest after linting passes
• --full: Run all checks including tests (equivalent to --fix --test)

Workflow

Step 1: Identify Target Files

If --all flag is provided:

• Target all files in synapse/ directory

Otherwise:

• Run git diff --name-only HEAD~1 to get recently modified files
• Filter to only .py files in synapse/ or tests/

Step 2: Run Ruff Linter

ruff check [files]

If --fix flag is provided:

ruff check --fix [files]

Report any errors found. If errors remain after fix, stop and report.

Step 3: Run Mypy Type Checker

uv run mypy [files]

Report any type errors found. If errors exist, stop and report.

Step 4: Run Tests (if --test or --full)

If --test or --full flag is provided AND ruff/mypy passed:

pytest

For running specific tests related to modified files:

pytest tests/ -v

Report any test failures.

Step 5: Run Code Simplifier (Default)

By default, run code-simplifier after all checks pass. Skip with --no-simplify flag.

Use the code-simplifier:code-simplifier agent to simplify the recently modified code:

Task tool with subagent_type: code-simplifier:code-simplifier
Prompt: Simplify and refine the recently modified code in [files].
Look for opportunities to reduce duplication, simplify conditionals,
and improve readability while maintaining all functionality.

Step 6: Report Results

Summarize:

• Number of files checked
• Ruff status (pass/fail, errors fixed if --fix)
• Mypy status (pass/fail)
• Pytest status (pass/fail, skipped if not run)
• Code simplifier status (run by default, skipped if --no-simplify)

Error Handling

When errors are found:

1. Ruff errors: If --fix is provided, attempt auto-fix first. Report remaining errors with file:line format.
2. Mypy errors: Report type errors with file:line format. Suggest fixes based on error messages.
3. Test failures: Report failed test names and assertion errors. Do NOT proceed to simplification if tests fail.

Examples

Basic check on recent changes

/code-quality

Check all files with auto-fix

/code-quality --all --fix

Full quality check with tests

/code-quality --full

Run with tests only

/code-quality --test

Skip code simplification

/code-quality --no-simplify

Shorthand

/lint          # Same as /code-quality (includes simplification)
/check         # Same as /code-quality
/lint -a -f    # All files with auto-fix
/lint -t       # With tests
/lint --full   # Full check (--fix --test)
/lint --no-simplify  # Skip simplification

Tool Configuration

This project uses the following configurations (from pyproject.toml):

Ruff

• Target: Python 3.10
• Line length: 88
• Rules: E, F, I, UP, B, SIM
• Ignored: E501, B008
• Excluded: synapse/proto/a2a_pb2*.py

Mypy

• Strict mode with disallow_untyped_defs
• Tests have relaxed rules (ignore_errors)
• Proto files excluded

Pytest

• asyncio_mode: auto
• Run with: pytest or pytest tests/ -v