Python Lint and Type-Check (Ruff & Mypy)

Executes and resolves Python static analysis diagnostics using ruff and mypy. Enforces type annotations and forbids # noqa or # type: ignore.

1. Purpose

Catch bugs, unused code, and type incompatibilities statically in Python. "Type Annotations" declare function signatures using typing (or native Python 3.10+ types int | None).

2. When to Use

Use this skill when:

• Checking Python code before committing.
• Resolving Mypy errors (arg-type, return-value, assignment).
• Formatting code per PEP 8 using ruff format.

3. When Not to Use

• Do not use for JavaScript/TypeScript; use ts-lint-and-typecheck.
• Do not use for running tests; use py-testing.

4. Required Inputs

• target_file: Path to Python file or directory.

5. Missing-Input Behavior

1. If no file is specified: run ruff check . and mypy . to locate issues across the repository.
2. Absolute Ban: Never add # noqa or # type: ignore comments.

6. Procedure

Follow these numbered actions:

1. Action 1: Run Mypy Type Checker
   • Execute: mypy --show-error-codes <target_file>
2. Action 2: Fix Type Mismatches at Root Cause
   • Add proper Optional[T], Union, or return type hints.
3. Action 3: Run Ruff Linter
   • Execute: ruff check <target_file>
   • Auto-fix safe issues: ruff check <target_file> --fix
4. Action 4: Format Code
   • Execute: ruff format <target_file>
5. Action 5: Verify Clean Exit
   • Confirm exit code 0 on both mypy and ruff check.

7. Decision Rules

• If a function returns None on failure: type return as Optional[ReturnType] or ReturnType | None.
• If an import is unused (F401): delete the import line.

8. Output Format

Emit the report using this template:

### Python Lint & Type-Check Report: [File]

- **Type Checker**: `mypy [file]` -> PASS
- **Linter**: `ruff check [file]` -> PASS
- **Issues Resolved**: [Count]

#### Resolved Diagnostics
| Line | Tool | Code | Root Cause Fix |
| :--- | :--- | :--- | :--- |
| `[Line]` | Mypy | `arg-type` | Corrected argument type from str to int |

#### Verification Status
- Clean exit code 0 confirmed with zero `# noqa` comments.

9. Verification Checklist

• mypy exits with code 0.
• ruff check exits with code 0.
• Zero # noqa or # type: ignore added.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Mypy configuration requires whole-codebase architecture migration.

12. Examples

Example 1: Successful Execution

Input:

File: src/utils.py
Error: F401 'sys' imported but unused

Output:

### Python Lint & Type-Check Report: src/utils.py

- **Type Checker**: `mypy src/utils.py` -> PASS
- **Linter**: `ruff check src/utils.py` -> PASS
- **Issues Resolved**: 1

#### Resolved Diagnostics
| Line | Tool | Code | Root Cause Fix |
| :--- | :--- | :--- | :--- |
| 3 | Ruff | `F401` | Removed unused `import sys` |

#### Verification Status
- Clean exit code 0 confirmed with zero `# noqa` comments.

Example 2: Ambiguous or Missing Input

Input:

Lint python.

Output:

### Python Lint & Type-Check Report: Halted - No Target

- **Status**: Halted

Please specify the Python file or directory to lint.

Example 3: Expected Final Output

Output:

### Python Lint & Type-Check Report: src/models.py

- **Type Checker**: `mypy src/models.py` -> PASS
- **Linter**: `ruff check src/models.py` -> PASS
- **Issues Resolved**: 2