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](references/coding-standards.md) **Checking naming?** → Go to [Naming Conventions](references/naming-conventions.md) **Building a CLI?** → Go to [CLI Development](references/cli-development.md) **Fixing linter errors?** → Go to [Linter Rules](references/linter-rules.md) **Writing tests?** → Go to [Testing](references/testing.md) **Debugging a bug?** → Go to [Debugging](references/debugging.md) **Refactoring?** → Go to [Refactoring](references/refactoring.md) **Reviewing code?** → Go to [Code Review](references/code-review.md) **Auditing codebase?** → Go to [Auditing](references/auditing.md) **Documenting?** → Go to [Documentation](references/documentation.md) **Planning a feature?** → Go to [Planning](references/planning.md) **Running Python?** → Go to [uv Execution](references/uv.md) **Standalone script?** → Go to [uv Scripts](references/uv-scripts.md) **Project workflow?** → Go to [uv Projects](references/uv-projects.md) **Bulk operations?** → Go to [Refactoring](references/refactoring.md) (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: ```text 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](SKILL.md) ______________________________________________________________________ ### 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](SKILL.md) ______________________________________________________________________ ### 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](SKILL.md) ______________________________________________________________________ ### 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](SKILL.md) ______________________________________________________________________ ### 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](SKILL.md) ______________________________________________________________________ ### 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](SKILL.md) ______________________________________________________________________ ### 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](SKILL.md) ______________________________________________________________________ ### 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