python-ultimate

Python Ultimate

Single Python reference with quick routes for standards, tooling, workflows, and best practices.

Quick Start

Writing code? → Start with Coding Standards Checking naming? → Go to Naming Conventions Building a CLI? → Go to CLI Development Fixing linter errors? → Go to Linter Rules Writing tests? → Go to Testing Debugging a bug? → Go to Debugging Refactoring? → Go to Refactoring Reviewing code? → Go to Code Review Auditing codebase? → Go to Auditing Documenting? → Go to Documentation Planning a feature? → Go to Planning Running Python? → Go to uv Execution Standalone script? → Go to uv Scripts Project workflow? → Go to uv Projects Bulk operations? → Go to Refactoring (10+ files)

Slash Commands

The /python-ultimate command accepts an optional sub-command argument to run a targeted guideline review. When invoked without a sub-command (e.g., just /python-ultimate), run a general antipattern check using the Antipatterns / Forbidden Styles Index section below.

Routing

Match the sub-command argument to one of the sections below and follow its workflow. If the argument does not match any known sub-command, explain the available options (you can output the table from python-ultimate help).

python-ultimate help

When the sub-command is help (or when the user asks for available commands), render the following table so the user sees all available options:

Sub-Command                    │ What It Reviews                                        │ Reference
───────────────────────────────┼────────────────────────────────────────────────────────┼──────────────────────────────────
python-ultimate naming         │ File/dir variable naming (_file/_dir/_path suffixes)  │ references/naming-conventions.md
python-ultimate type-checking  │ TYPE_CHECKING guards and Optional[T] usage             │ references/type-checking.md
python-ultimate imports        │ Required-vs-optional import patterns                    │ references/imports-optional-dependencies.md
python-ultimate coding-standards│ Type hints, f-strings, pathlib, docstrings, comments, data modeling │ references/coding-standards.md
python-ultimate linter-rules   │ Ruff violations (E402, B007, B008, S108, etc.)         │ references/linter-rules.md
python-ultimate debugging      │ Systematic 4-phase debugging process                   │ references/debugging.md
python-ultimate testing        │ Test organization, fixtures, mocking, TDD, coverage    │ references/testing.md
python-ultimate audit          │ 6-dimension codebase audit                             │ references/auditing.md
python-ultimate verification   │ Evidence-based completion claims                       │ references/verification.md
python-ultimate code-review    │ Code review feedback evaluation                        │ references/code-review.md
python-ultimate uv             │ Always `uv run`, never bare `python`                   │ references/uv.md
python-ultimate uv-scripts     │ PEP 723 standalone scripts via `uv init --script`      │ references/uv-scripts.md
python-ultimate uv-projects    │ Project workflow: init, add, sync, lock, groups        │ references/uv-projects.md

python-ultimate naming

Reviews file and directory variable naming conventions (_file / _dir / _path suffixes).

Workflow:

Open references/naming-conventions.md and load the "1. Files and Directories" section
Scan the codebase for bare path names (path, file, dir, output, source, target) used as Path variables
Check for prefix patterns (dir_output → should be output_dir)
Find generic path variable names missing suffixes (results → ambiguous)
Report findings using the standard antipattern response format

python-ultimate type-checking

Scans for TYPE_CHECKING guards and Optional[T] usage.

Workflow:

Open references/type-checking.md and load the "Rule: Never Use TYPE_CHECKING Guards" section
Search for TYPE_CHECKING imports: rg "TYPE_CHECKING" src/
Search for Optional[ usage: rg "Optional\[" src/
For each finding, identify the root cause (circular imports, type-only imports)
Recommend the appropriate alternative (shared types module, protocols, forward refs, local imports)
Report findings using the standard antipattern response format

python-ultimate imports

Reviews import patterns — distinguishes required vs optional dependencies.

Workflow:

Open references/imports-optional-dependencies.md and load the hard rule
Check pyproject.toml to determine which packages are required vs optional
Search for try/except ImportError patterns guarding required deps: rg "except ImportError" src/
For each match, classify: required dep → normal top-level import; optional dep → localized handling
Report findings using the standard antipattern response format

python-ultimate coding-standards

Reviews compliance with coding standards: type hints, f-strings, pathlib, docstrings, comments, prohibited patterns, vague input/output types.

Workflow:

Open references/coding-standards.md and load relevant sections
For each prohibited pattern, search with targeted grep patterns:
- Optional\[ → must be T | None
- \.format\( or % formatting → must be f-strings
- os\.path\. → must be pathlib.Path
- # noqa → fix root issue
Check for vague input/output types with multiple isinstance checks
Scan for vague type annotations:
- rg ": object$" or rg "-> object" → bare object as type
- rg "\bAny\b" src/ --include "*.py" → typing.Any usage (flag each occurrence for review)
Scan for None misuse in dataclass fields and function signatures:
- rg "= None$" → potential sentinel/absent patterns
- Check dataclass fields with list | None = None, dict | None = None → should be field(default_factory=...)
- Check functions returning T | None as error signal → should raise instead
Report findings using the standard antipattern response format

python-ultimate linter-rules

Reviews and fixes specific Ruff linter violations using context-aware patterns.

Workflow:

Open references/linter-rules.md and load the relevant rule section
Run ruff check src/ to identify violations
For each violated rule, apply the context-specific fix pattern from the reference:
- E402 → Move import to top of module
- B007 → Prefix unused loop variable with _
- B008 → Use None sentinel (except Typer Annotated parameters)
- S108 → Use tempfile or tmp_path fixture
- PLC0415 → Move import to module level
- NPY002 → Use default_rng()
- S311 → Use secrets for security contexts
Re-run ruff check src/ to confirm fixes
Report findings using the standard antipattern response format

python-ultimate debugging

Initiates the systematic 4-phase debugging process.

Workflow:

Open references/debugging.md and load the full 4-phase process
Phase 1 — Root Cause: Reproduce the issue, read error messages, trace data flow from symptom to origin
Phase 2 — Pattern: Find working examples, compare against broken code, list every difference
Phase 3 — Hypothesis: Form a single testable hypothesis, make the smallest possible change to test it
Phase 4 — Implementation: Write a failing test first, implement the fix, verify all tests pass
Remember the iron law: No fixes without root cause investigation first.
If 3+ fixes have failed, stop and reassess architecture rather than continuing to guess

python-ultimate testing

Reviews test organization, coverage, fixtures, mocking, and TDD compliance.

Workflow:

Open references/testing.md for patterns and standards
Check test file naming: test_<module>.py convention
Check test class naming: Test<Name> PascalCase
Check test method naming: test_<description> snake_case
Run coverage: uv run pytest --cov=src --cov-report=term-missing
Review fixture quality (descriptive names, proper scope, teardown)
Report findings using the standard antipattern response format

python-ultimate audit

Runs a 6-dimension codebase audit.

Workflow:

Open references/auditing.md and load all six dimensions
For each dimension (Architecture, Quality, Security, Performance, Testing, Maintainability):
- Scan with grep/glob for relevant red flags
- Rate findings by severity (Critical, High, Medium, Low)
Synthesize into an audit report using the format from references/auditing.md
Include an executive summary with health score and top recommendation
Include an action plan with immediate/short-term/medium-term/backlog items

python-ultimate verification

Verifies that completion claims are backed by fresh evidence.

Workflow:

Open references/verification.md and load the iron law and gate function
For each claim, determine what command proves it
Run the full command, read the output, check the exit code
Only then state the result — with evidence, not assumptions
Forbidden words: should, probably, might, likely
Report results using the standard antipattern response format

python-ultimate code-review

Evaluates code review feedback and responds with technical rigor.

Workflow:

Open references/code-review.md and load the full workflow
Follow the READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT sequence
For each feedback item: verify against codebase reality, evaluate technical soundness
No performative agreement — respond with technical reasoning or push back with evidence
Push back when: suggestion breaks existing functionality, violates YAGNI, lacks full context

python-ultimate uv

Enforces execution discipline: every Python invocation goes through uv.

Workflow:

Open references/uv.md and load the Iron Rule and Execution Patterns
Treat bare python / python3 calls as violations — translate them to uv run ...
In sandboxed environments, confirm UV_CACHE_DIR is set to a writable directory
Report findings using the standard antipattern response format

python-ultimate uv-scripts

Reviews PEP 723 standalone scripts for the "never hand-edit metadata" rule and agentic script-design rules.

Workflow:

Open references/uv-scripts.md and load the Iron Rule and the Core Workflow
Search for PEP 723 blocks and check whether they were created/maintained via uv init --script / uv add --script / uv remove --script
Search for hand-edited metadata markers: rg "# /// script", rg "# dependencies =" — each occurrence must be backed by a uv-managed workflow
Check interactive prompts (input(), missing --help, free-form stdout, and unbounded output against the agentic script-design rules
Report findings using the standard antipattern response format

python-ultimate uv-projects

Reviews uv-managed projects: locking, syncing, groups, and common mistakes.

Workflow:

Open references/uv-projects.md and load the Common Mistakes table
Check for pip install inside a project that has pyproject.toml + uv.lock
Check uv sync usage — missing --locked where reproducibility matters
Check .venv/ is gitignored and uv.lock is committed
Check workspaces and dependency groups for consistency
Report findings using the standard antipattern response format

Expected `/python-ultimate` Response Format

For consistency across agents, format all sub-command responses as:

Summary — total findings by severity and category
Findings — one item per finding: file:line, matched pattern class, short rationale
Fix Guidance — preferred replacement pattern with one concrete before/after example
References — direct links to the relevant section in references/*.md
Verification — exact command(s) run and observed result

Use concise, technical language. Avoid performative agreement and avoid speculative wording.

Antipatterns / Forbidden Styles Index

Canonical quick-reference for common bad or forbidden patterns. Detailed rationale and examples stay in reference files.

Category	Forbidden pattern	Preferred pattern	Source
Type checking	`TYPE_CHECKING` import guards	Refactor module boundaries, use forward refs/protocols	references/type-checking.md
Type hints	`Optional[T]`	`T \| None`	references/coding-standards.md
String formatting	`.format()` and `%` formatting	f-strings	references/coding-standards.md
Paths	`os.path` usage	`pathlib.Path`	references/coding-standards.md
Lint suppression	`# noqa` to hide issues	Fix root issue	references/coding-standards.md
Import policy	Defensive `try/except ImportError` for required deps	Normal top-level imports for required deps	references/imports-optional-dependencies.md
Path variable naming	Bare names like `path`, `file`, `output` for paths	Use `_file` / `_dir` suffixes	references/naming-conventions.md
Path variable naming	Prefix forms `dir_x`, `file_x`	Suffix forms `x_dir`, `x_file`	references/naming-conventions.md
Comments	Restating obvious code intent	Explain why/constraints only	references/coding-standards.md
Debugging workflow	Guess-and-check fixes before RCA	Follow 4-phase process	references/debugging.md
Debugging behavior	Repeated "one more try" after multiple failures	Stop and reassess architecture	references/debugging.md
Code review behavior	Performative agreement phrases	Technical response and evidence	references/code-review.md
Data modeling	Using `pydantic` for lightweight internal structs, or `dataclass` at trust boundaries	`dataclass` for internal DTOs; `pydantic` for validation/API boundaries	references/coding-standards.md
Python execution	Bare `python` / `python3` invocations	`uv run ...` (uv selects interpreter, syncs env, resolves deps)	references/uv.md
Script metadata	Hand-written or hand-edited PEP 723 `# /// script` blocks	`uv init --script` / `uv add --script` / `uv remove --script`	references/uv-scripts.md
Project deps	`pip install` inside a `uv`-managed project	`uv add` (managed by `pyproject.toml`)	references/uv-projects.md
Lockfiles	`uv sync` without `--locked` where reproducibility matters	`uv sync --locked` (or `--frozen` when the lockfile is trusted)	references/uv-projects.md
VCS hygiene	Committing `.venv/`; omitting `uv.lock`	Gitignore `.venv/`; commit `uv.lock`	references/uv-projects.md
Architecture	Assuming `uv python install` can provide 32-bit Python	Point `uv run --python <path>` at a system 32-bit interpreter	references/uv-python-versions.md
Type hints	`object` or `typing.Any` as type annotation without justification	Precise union types (`str \| int`), `typing.Protocol` for structural types	references/coding-standards.md
Default values	`None` as default for collections or as silent error signal	`field(default_factory=...)` for mutable defaults, exceptions for error states	references/coding-standards.md

Coding Standards

Core Python coding rules. See references/coding-standards.md for full details.

Type Hints

Mandatory everywhere. Use pipe syntax (T | None), never Optional[T]. Python 3.10+ required.

def process(data: str, limit: int | None = None) -> list[str]: ...

Never use TYPE_CHECKING guards. See references/type-checking.md for alternatives.

String Formatting

Use f-strings only. No .format() or % formatting.

Code Size Limits

Target	Limit
Module	< 250 lines
Function	< 75 lines
Class	< 200 lines

Docstrings

Google style. Required for public functions and classes.

Prohibited Patterns

TYPE_CHECKING guards
os.path (use pathlib.Path)
Optional[T] (use T | None)
# noqa comments
sys.path manipulation
Defensive try/except ImportError for required dependencies (see references/imports-optional-dependencies.md)
Vague or wide parameter/return types with hidden isinstance/hasattr checks and None-as-error returns (see references/coding-standards.md)
Using pydantic for lightweight internal structs, or dataclass for untrusted/API data (see references/coding-standards.md)
object or typing.Any as type annotations without justification (use precise union types, typing.Protocol, or narrowest possible type; see references/coding-standards.md)
None as default for mutable collections (use field(default_factory=...) in dataclasses; see references/coding-standards.md)
None as silent error return — prefer exceptions or result types (see references/coding-standards.md)

Naming Conventions

Variable naming standards for clarity and consistency. See references/naming-conventions.md for full details.

Files and Directories

Pattern	Suffix	Example
Files	`_file`	`output_file`, `config_file`
Directories	`_dir`	`cache_dir`, `output_dir`
Unknown type	`_path`	`data_path` (exceptional only)

Anti-patterns (always invalid for path variables):

Bare generic names: path, file, folder, dir, directory, output, input, source, target, dest
Prefix instead of suffix: dir_output, file_config
Missing suffix: results, data, config (ambiguous)

See references/naming-conventions.md for the complete anti-pattern list.

Test Naming

Files: test_<module>.py
Classes: Test<DataProcessor> (PascalCase with Test prefix)
Methods: test_<description> (snake_case with test_ prefix)

Automated Validation

# Check a variable name
uv run assets/check_path_naming.py output_file
# Output: is_file

# Scan for violations
uv run assets/check_path_naming.py --check-files src/

# Scan for core forbidden patterns
uv run assets/check_path_naming.py --check-forbidden src/

# Repro fixture scan (see assets/examples)
uv run assets/check_path_naming.py --check-forbidden assets/examples/

Reference fixture files and expected output: assets/examples/forbidden-scan-expected.md

CLI Development

Building Python CLIs with Typer or Click. See references/cli-development.md.

Framework Selection

Use Typer for new projects (type-hint driven, less boilerplate). Use Click for complex parameter handling.

Key Patterns

Parameter validation with type hints
Rich output formatting
Environment variable integration
Exit codes for error states

Linter Rules

Context-aware fixes for Ruff linter rules. See references/linter-rules.md.

Covered Rules

Rule	Description	Quick Fix
E402	Module-level import not at top	Move imports to top
B007	Unused loop variable	Prefix with `_`
B008	Function call in default arg	Use `None` sentinel
S108	Hardcoded temp file path	Use `tempfile`
PLC0415	Import not at top-level	Move to module level
NPY002	Legacy numpy random	Use `numpy.random`
S311	Standard random	Use `secrets` for security

Typer Exception

B008 is allowed for Typer Annotated parameters. See references/linter-rules.md.

Testing

Test organization, fixtures, mocking, and TDD. See references/testing.md.

Quick Commands

uv run pytest -v --tb=short
uv run pytest --cov=src --cov-report=term-missing

Key Practices

Co-located tests: <module>_test.py alongside implementation
90%+ coverage target
Fixtures in conftest.py
Parameterized testing for multiple inputs
unittest.mock for external dependencies

TDD Cycle

Red → Green → Refactor. No production code without a failing test first. See references/testing.md.

Debugging

Systematic 4-phase debugging process. See references/debugging.md.

Iron Law

No fixes without root cause investigation first.

4-Phase Process

Root Cause — Reproduce, isolate, trace data flow
Pattern Analysis — Identify state changes, timing issues
Hypothesis — Form testable prediction
Implementation — Minimal fix, verify with test

Red Flags

"Let me just try changing X"
Fixing symptoms without understanding cause
Multiple failed fix attempts

Refactoring

Find → Replace → Verify workflow. See references/refactoring.md.

Workflow

Find — Grep for target pattern
Replace — Edit with replace_all for bulk changes
Verify — Run tests, check for regressions

Code Transfer

Line-based code movement between files. See references/refactoring.md.

Code Review

Receiving and evaluating code review feedback. See references/code-review.md.

Workflow

Read → Understand → Verify → Evaluate → Respond → Implement

Key Principles

No performative agreement
Push back with technical reasoning
Verify feedback before implementing
Evaluate: is the suggestion correct?

Auditing

6-dimension codebase analysis. See references/auditing.md.

Dimensions

Architecture — Structure, modularity, dependencies
Quality — Readability, complexity, duplication
Security — Input validation, secrets, injection
Performance — Bottlenecks, memory, I/O
Testing — Coverage, quality, edge cases
Maintainability — Documentation, technical debt

Severity Ratings

Critical → High → Medium → Low

Documentation

10-section documentation structure. See references/documentation.md.

Workflow

Explore → Map → Read → Synthesize

Sections

Project Overview, Architecture, Key Components, Data Flow, API Reference, Configuration, Setup Guide, Development Guide, Testing, Deployment

Mermaid Diagrams

Use for architecture, sequence, and flowchart visualizations.

Planning

PLAN.md living document for feature implementation. See references/planning.md.

When to Use

Features spanning 3-15 prompts. Self-contained for fresh sessions.

Structure

Goal → Context → Phases → Validation → Progress → Decisions → Notes

Project Setup

Project structure, dependencies, and imports. See references/project-setup.md and references/uv-projects.md.

Key Tools

uv for dependency management
src layout for packages
pyproject.toml for configuration

Import Order

Standard library
Third-party
Local (absolute imports)

uv Workflow

Running, scripting, and project management through uv. See references/uv.md, references/uv-scripts.md, references/uv-projects.md, and references/uv-python-versions.md.

Iron Rule

Always uv run. Never bare python / python3.

# BAD
python script.py

# GOOD
uv run script.py

Standalone Scripts (PEP 723)

Manage metadata exclusively through uv — never hand-edit the # /// script block.

uv init --script path/to/script.py
uv add --script path/to/script.py "requests>=2.32,<3"
uv run path/to/script.py

Projects

uv init my-project
uv add requests --dev pytest
uv sync --locked
uv run pytest

Python Versions & Architectures

uv python install 3.12
uv python pin 3.12
uv run --python 3.12 script.py

uv ships x86_64 interpreters only — for 32-bit Python, point --python at a system-installed interpreter. See references/uv-python-versions.md.

Scope Boundary

Installing uv itself and running MCP servers with uvx belong to the standalone uv skill — not this skill.

File Analysis

Non-destructive file and codebase analysis. See references/file-analysis.md.

Tools

stat for metadata
wc for line counts
Grep for pattern searching
Glob for file discovery

Type Checking Alternatives

Never use TYPE_CHECKING guards. See references/type-checking.md.

Alternatives

Extract shared types to dedicated modules
Use protocols for structural typing
Forward references (string literals)
Local imports (last resort)

Bulk Operations

High-efficiency Python execution for 10+ file operations. 90-99% token savings vs. iterative approaches.

When to use:

Bulk operations (10+ files)
Complex multi-step workflows
Iterative processing across many files
User mentions efficiency/performance

Workflow pattern:

Analyze locally — Use metadata operations (file counts, grep patterns)
Process locally — Execute all transformations in Python
Return summary — Report counts, not full data

Example patterns:

# Bulk refactor across 50 files
from pathlib import Path
import re

files = list(Path(".").glob("**/*.py"))
modified = 0

for f in files:
    content = f.read_text()
    new_content = re.sub(r"old_pattern", "new_pattern", content)
    if new_content != content:
        f.write_text(new_content)
        modified += 1

result = {"files_scanned": len(files), "files_modified": modified}

# Code audit metadata extraction
from pathlib import Path
import ast

files = list(Path("src").glob("**/*.py"))
complexity_issues = []

for f in files:
    tree = ast.parse(f.read_text())
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            # Calculate simple complexity metric
            nested = sum(
                1 for n in ast.walk(node) if isinstance(n, (ast.If, ast.For, ast.While))
            )
            if nested > 10:
                complexity_issues.append(
                    {"file": str(f), "function": node.name, "complexity": nested}
                )

result = {"files_audited": len(files), "high_complexity": len(complexity_issues)}

Best practices:

✅ Return summaries, not full data
✅ Batch operations where possible
✅ Use pathlib.Path for file operations
✅ Handle errors gracefully, return error counts
❌ Don't read full source into context when metadata suffices
❌ Don't process files one-by-one interactively

Token savings scale with file count:

Files	Interactive	Bulk Operation	Savings
10	~5K tokens	~500 tokens	90%
50	~25K tokens	~600 tokens	97.6%
100	~150K tokens	~1K tokens	99.3%

Reference Files

All detailed content lives in references/. Load only what you need:

File	Content
`coding-standards.md`	Type hints, formatting, size limits, docstrings, comments, data modeling
`cli-development.md`	Typer/Click, parameters, Rich output, env vars
`linter-rules.md`	Ruff rules E402, B007, B008, S108, PLC0415, NPY002, S311
`testing.md`	Fixtures, parameterized, mocking, TDD, coverage
`type-checking.md`	TYPE_CHECKING alternatives, protocols, forward refs
`debugging.md`	4-phase process, red flags, rationalizations
`refactoring.md`	Bulk operations, code transfer, safety checks
`code-review.md`	Receiving feedback, push back, evaluation
`auditing.md`	6-dimension analysis, severity ratings
`documentation.md`	10-section structure, Mermaid diagrams
`planning.md`	PLAN.md template and example
`file-analysis.md`	Metadata, line counting, pattern searching
`project-setup.md`	Project structure, uv, imports
`verification.md`	Pre-commit hooks, tox, Makefile targets
`imports-optional-dependencies.md`	Required vs optional dependency import patterns
`uv.md`	Execution discipline: always `uv run`, never bare `python`, `UV_CACHE_DIR`
`uv-scripts.md`	PEP 723 standalone scripts, `uv init --script`, agentic design
`uv-projects.md`	Project workflow, lock/sync, `--locked` vs `--frozen`, groups, workspaces
`uv-python-versions.md`	Version pinning, `--python` flag, 32-bit / free-threaded builds

About this skill

Quick Start

Slash Commands

Routing

python-ultimate help

python-ultimate naming

python-ultimate type-checking

python-ultimate imports

python-ultimate coding-standards

python-ultimate linter-rules

python-ultimate debugging

python-ultimate testing

python-ultimate audit

python-ultimate verification

python-ultimate code-review

python-ultimate uv

python-ultimate uv-scripts

python-ultimate uv-projects

Expected /python-ultimate Response Format

Antipatterns / Forbidden Styles Index

Coding Standards

Type Hints

String Formatting

Code Size Limits

Docstrings

Prohibited Patterns

Naming Conventions

Files and Directories

Test Naming

Automated Validation

CLI Development

Framework Selection

Key Patterns

Linter Rules

Covered Rules

Typer Exception

Testing

Quick Commands

Key Practices

TDD Cycle

Debugging

Iron Law

4-Phase Process

Red Flags

Refactoring

Workflow

Code Transfer

Code Review

Workflow

Key Principles

Auditing

Dimensions

Severity Ratings

Documentation

Workflow

Sections

Mermaid Diagrams

Planning

When to Use

Structure

Project Setup

Key Tools

Import Order

uv Workflow

Iron Rule

Standalone Scripts (PEP 723)

Projects

Python Versions & Architectures

Scope Boundary

File Analysis

Tools

Type Checking Alternatives

Alternatives

Bulk Operations

Reference Files

Expected `/python-ultimate` Response Format