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
• xenon_band (optional): xenon hot-spot band to cross-reference, default B
• 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 xenon-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 xenon --max-absolute B src/ \
       > .gzkit/chores/pythonic-design-pattern-detection/proofs/xenon-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 ranked B-or-worse by xenon. 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 xenon 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:

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-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