tvproductions/gzkit / .claude/skills/gz-pythonic-pattern-detect
gz-pythonic-pattern-detect
VerifiedUse 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 (defaultsrc)out: markdown candidates report path. The scanner requires--outand has no default; the convention is.gzkit/chores/pythonic-design-pattern-detection/proofs/candidates-YYYY-MM-DD.mdhotspot_ceiling(optional): cyclomatic complexity above which a function is a hotspot to cross-reference, default10DESIGN_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
outpath 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.txtcross-reference under the sameproofs/ CHORE-LOG.mdentry recording the chore execution
Procedure
-
Confirm chore is registered:
uv run gz chores show pythonic-design-pattern-detection -
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 -
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 -
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 -
Open the candidates report. For each candidate:
- Read the matching local archive example (
Python/src/<Pattern>/Conceptual/main.pyplusOutput.txtwhen present) as the role-map witness. WithDESIGN_PATTERNS_ARCHIVEunset, record that the corpus was unavailable and mark the disposition provisional - Record
Example,Output,Role map, andPythonic collapsein the candidate row before deciding disposition - Decide one disposition:
applied,deferred, ornot-pythonic-rewrite - For
applied: route togz-pythonic-pattern-applyto 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)
- Read the matching local archive example (
-
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 candidatessection to the report. -
Run the chore's acceptance criteria.
gz chores runexecutesacceptance.json— the fulluv run gz testsuite and the scanner self-test — and appends the result toproofs/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.pyand the failing fixture; either fix the detector or update the fixture if the rewrite was intentional. --outomitted: the scanner exits 2 with a usage error; pass the report path. It creates the parent directory itself.gz chores showcannot find the chore: the project copy is missing or damaged. Runuv run gz chores doctor --dry-runfirst and sync any unsynced.gzkit/chores/edits, because repairing a damaged slug rewrites its surviving definition files (.gzkit/rules/chores.md§ Two-Surface Layout); thenuv run gz chores doctorrestores it and keepsproofs/.- 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 applieddispositions route togz-pythonic-pattern-applyfor 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:
| Thought | Reality |
|---|---|
| "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-testbefore 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.pyevidence - Running the scanner over
tests/orfeatures/(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.pyinside the archiveDESIGN_PATTERNS_ARCHIVEpoints 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |