Skip to content

tvproductions/gzkit / .claude/skills/gz-pythonic-pattern-detect

gz-pythonic-pattern-detect

Verified

Use when gates are green but code still looks Java-flavored, to surface Pythonic refactor candidates.

gz-pythonic-pattern-detect

Purpose

Run the pythonic-design-pattern-detection chore to surface structural refactor candidates that mechanical metric chores (pythonic-refactoring, complexity-reduction-xenon, module-sloc-cap-radon) cannot catch. The chore's scanner walks src/ AST-by-AST and flags class shapes whose Pythonic equivalent is cleaner — paired with the Python examples of a local Refactoring Guru archive (DESIGN_PATTERNS_ARCHIVE) as the absorption surface.

Inputs

  • root: source tree to scan (default src)
  • out: markdown candidates report path. The scanner requires --out and has no default; the convention is .gzkit/chores/pythonic-design-pattern-detection/proofs/candidates-YYYY-MM-DD.md
  • hotspot_ceiling (optional): cyclomatic complexity above which a function is a hotspot to cross-reference, default 10
  • DESIGN_PATTERNS_ARCHIVE (optional): path to your own copy of the local Refactoring Guru archive. No default — it is a third-party asset gzkit does not ship, and a hardcoded default resolves only on the machine that authored it (GHI #900). Unset, the corpus step is skipped and the chore records the disposition as provisional.

Outputs

  • Candidates report at the out path enumerating every match with file:line, class name, AST signal, Pythonic refactor target, local Python example path, output path, role map, and Pythonic collapse
  • Optional complexity-hotspots-YYYY-MM-DD.txt cross-reference under the same proofs/
  • CHORE-LOG.md entry recording the chore execution

Procedure

  1. Confirm chore is registered:

    uv run gz chores show pythonic-design-pattern-detection
    
  2. Run scanner self-test before scanning real source — proves the detector set still recognises its own fixtures:

    uv run python .gzkit/chores/pythonic-design-pattern-detection/scan.py --self-test
    
  3. Run the scanner against src:

    uv run python .gzkit/chores/pythonic-design-pattern-detection/scan.py \
        --root src \
        --out .gzkit/chores/pythonic-design-pattern-detection/proofs/candidates-$(date +%Y-%m-%d).md
    
  4. Cross-reference complexity hotspots:

    uv run ruff check src --select C901 --config 'lint.mccabe.max-complexity = 10' --output-format concise \
        > .gzkit/chores/pythonic-design-pattern-detection/proofs/complexity-hotspots-$(date +%Y-%m-%d).txt 2>&1 || true
    
  5. Open the candidates report. For each candidate:

    • Read the matching local archive example (Python/src/<Pattern>/Conceptual/main.py plus Output.txt when present) as the role-map witness. With DESIGN_PATTERNS_ARCHIVE unset, record that the corpus was unavailable and mark the disposition provisional
    • Record Example, Output, Role map, and Pythonic collapse in the candidate row before deciding disposition
    • Decide one disposition: applied, deferred, or not-pythonic-rewrite
    • For applied: route to gz-pythonic-pattern-apply to capture evidence
    • For deferred: file or cite a tracking GHI, paste the issue number into the row
    • For not-pythonic-rewrite: name the concrete reason inline (the class shape genuinely fits — e.g. State machine with many transitions)
  6. For reference-mode patterns (Bridge, Flyweight, Factory Method) — open the matching archive example side-by-side with any module holding a hotspot. Add an inline ## Reference-mode candidates section to the report.

  7. Run the chore's acceptance criteria. gz chores run executes acceptance.json — the full uv run gz test suite and the scanner self-test — and appends the result to proofs/CHORE-LOG.md:

    uv run gz chores run pythonic-design-pattern-detection
    

Failure Modes

  • Scanner self-test fails: detector set has drifted from its fixtures. Read scan.py and the failing fixture; either fix the detector or update the fixture if the rewrite was intentional.
  • --out omitted: the scanner exits 2 with a usage error; pass the report path. It creates the parent directory itself.
  • gz chores show cannot find the chore: the project copy is missing or damaged. Run uv run gz chores doctor --dry-run first and sync any unsynced .gzkit/chores/ edits, because repairing a damaged slug rewrites its surviving definition files (.gzkit/rules/chores.md § Two-Surface Layout); then uv run gz chores doctor restores it and keeps proofs/.
  • Empty report (NO_CANDIDATES_DETECTED): AST signals returned zero hits. Switch to reference-mode review against local Python examples; do not assume the codebase is Pythonic everywhere — Bridge, Flyweight, Factory Method are not detected mechanically.
  • Many candidates without hotspot overlap: the structural drift exists but is metric-invisible. Do not skip those — that is exactly the post-post-implementation gap this skill is designed to catch.

Acceptance Rules

  • Uses uv run python .gzkit/chores/pythonic-design-pattern-detection/scan.py — never a shadow scanner
  • Self-test runs before any real scan
  • Every flagged candidate gets a disposition (applied/deferred/not-pythonic-rewrite) before the chore is considered done for this period
  • Every disposition row cites the local Python example path and records a role map
  • Report path is under .gzkit/chores/pythonic-design-pattern-detection/proofs/ — never elsewhere
  • applied dispositions route to gz-pythonic-pattern-apply for evidence capture; orphan applications (no detection-report row) are a defect

Common Rationalizations

These thoughts mean STOP — you are about to ship a detection pass that broke its own discipline:

ThoughtReality
"I'll skip the self-test, the scanner worked yesterday"Detector drift is silent. Self-test is a 1-second guard against authoring fake reports.
"I'll mark all candidates not-pythonic-rewrite to clear the queue"The disposition is a per-candidate judgment, not a queue-clearer. False not-pythonic-rewrite is dishonest triage.
"The reference-mode patterns aren't detected, so I'll skip them"Reference-mode exists because AST detection misses them. Skipping reference-mode collapses the chore to mechanical-only.
"AST said zero candidates, the codebase must be clean"Bridge, Flyweight, Factory Method need eye-review against the local examples. Trust the examples, not the absence of AST hits.
"I know the pattern already"The local Python example is the observed role-map witness. Skipping it turns the chore back into memory-driven pattern matching.
"I'll run gz chores run before completing dispositions, log first"The CHORE-LOG records execution, not completeness. Disposition triage must precede the run, or the log is a lie.

Red Flags

  • Authoring an applied entry without routing to gz-pythonic-pattern-apply
  • Mass-marking candidates without per-entry rationale
  • Skipping --self-test before a real scan
  • Writing the candidates file outside .gzkit/chores/pythonic-design-pattern-detection/proofs/
  • Treating zero-AST-hits as evidence the codebase is Pythonic shape-wise (example-corpus eye-review still required)
  • Candidate rows without Python/src/<Pattern>/Conceptual/main.py evidence
  • Running the scanner over tests/ or features/ (excluded by default — do not override without reason)

Reference

  • Chore canon: .gzkit/chores/pythonic-design-pattern-detection/CHORE.md
  • Scanner: .gzkit/chores/pythonic-design-pattern-detection/scan.py
  • Local example corpus: Python/src/<Pattern>/Conceptual/main.py inside the archive DESIGN_PATTERNS_ARCHIVE points at (not shipped; GHI #900)
  • Pair skill: gz-pythonic-pattern-apply (evidence capture for applied refactors)
  • Related chores: pythonic-refactoring (idiom-level), complexity-reduction-xenon (metric-level)
  • Doctrine: CHORE.md § Pythonic-first absorption stance, .gzkit/rules/tests.md § Tests assert semantics, not strings
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexVerifiedInstall