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:

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

python-ultimate type-checking

Scans for TYPE_CHECKING guards and Optional[T] usage.

Workflow:

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

python-ultimate imports

Reviews import patterns — distinguishes required vs optional dependencies.

Workflow:

1. Open references/imports-optional-dependencies.md and load the hard rule
2. Check pyproject.toml to determine which packages are required vs optional
3. Search for try/except ImportError patterns guarding required deps: rg "except ImportError" src/
4. For each match, classify: required dep → normal top-level import; optional dep → localized handling
5. 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:

1. Open references/coding-standards.md and load relevant sections
2. 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
3. Check for vague input/output types with multiple isinstance checks
4. 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)
5. 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
6. Report findings using the standard antipattern response format

python-ultimate linter-rules

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

Workflow:

1. Open references/linter-rules.md and load the relevant rule section
2. Run ruff check src/ to identify violations
3. 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
4. Re-run ruff check src/ to confirm fixes
5. Report findings using the standard antipattern response format

python-ultimate debugging

Initiates the systematic 4-phase debugging process.

Workflow:

1. Open references/debugging.md and load the full 4-phase process
2. Phase 1 — Root Cause: Reproduce the issue, read error messages, trace data flow from symptom to origin
3. Phase 2 — Pattern: Find working examples, compare against broken code, list every difference
4. Phase 3 — Hypothesis: Form a single testable hypothesis, make the smallest possible change to test it
5. Phase 4 — Implementation: Write a failing test first, implement the fix, verify all tests pass
6. Remember the iron law: No fixes without root cause investigation first.
7. 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:

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

python-ultimate audit

Runs a 6-dimension codebase audit.

Workflow:

1. Open references/auditing.md and load all six dimensions
2. 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)
3. Synthesize into an audit report using the format from references/auditing.md
4. Include an executive summary with health score and top recommendation
5. 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:

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

python-ultimate code-review

Evaluates code review feedback and responds with technical rigor.

Workflow:

1. Open references/code-review.md and load the full workflow
2. Follow the READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT sequence
3. For each feedback item: verify against codebase reality, evaluate technical soundness
4. No performative agreement — respond with technical reasoning or push back with evidence
5. 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:

1. Open references/uv.md and load the Iron Rule and Execution Patterns
2. Treat bare python / python3 calls as violations — translate them to uv run ...
3. In sandboxed environments, confirm UV_CACHE_DIR is set to a writable directory
4. 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:

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

python-ultimate uv-projects

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

Workflow:

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

Expected /python-ultimate Response Format

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

1. Summary — total findings by severity and category
2. Findings — one item per finding: file:line, matched pattern class, short rationale
3. Fix Guidance — preferred replacement pattern with one concrete before/after example
4. References — direct links to the relevant section in references/*.md
5. 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.

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

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

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

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

1. Root Cause — Reproduce, isolate, trace data flow
2. Pattern Analysis — Identify state changes, timing issues
3. Hypothesis — Form testable prediction
4. 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

1. Find — Grep for target pattern
2. Replace — Edit with replace_all for bulk changes
3. 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

1. Architecture — Structure, modularity, dependencies
2. Quality — Readability, complexity, duplication
3. Security — Input validation, secrets, injection
4. Performance — Bottlenecks, memory, I/O
5. Testing — Coverage, quality, edge cases
6. 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

1. Standard library
2. Third-party
3. 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

1. Extract shared types to dedicated modules
2. Use protocols for structural typing
3. Forward references (string literals)
4. 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:

1. Analyze locally — Use metadata operations (file counts, grep patterns)
2. Process locally — Execute all transformations in Python
3. 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:

Reference Files

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