Workarounds over root fixes, test tampering, unnecessary additions
Plugin-Specific Patterns
Detection patterns for plugin and skill codebases where
standard code quality heuristics miss structural issues.
Delegation Stub Bodies
A skill that declares "delegates to X" but still carries the
full template body is doing double duty. The delegating skill
should be a thin wrapper (under 30 lines) that routes to the
target. Flag any delegating skill whose body exceeds 50 lines.
Module Explosion
Flag skills with 10+ module files where 40% or more of content
overlaps. Signal: two modules covering the same API surface
from different angles (e.g., both describing the same config
options or the same CLI flags).
Oversized Single Modules
Flag individual module files exceeding 500 lines as candidates
for splitting or trimming. Large modules defeat progressive
loading by forcing full-file reads for partial information.
Dead Python References
Skills referencing Python commands (python -m module.name or
python -c "from module import ...") where the referenced
module does not exist in the plugin's src/ directory. These
are stale references to renamed or removed code.
Progressive Loading
Load modules based on refinement focus:
modules/duplication-analysis.md (~400 tokens): Duplication detection and consolidation
modules/algorithm-efficiency.md (~400 tokens): Complexity analysis and optimization
refine:scan-complete: Findings across all dimensions
refine:prioritized: Findings ranked by impact and effort
refine:plan-generated: Concrete refactoring plan with before/after
refine:evidence-captured: Evidence appendix per imbue:proof-of-work
refine:findings-verified: Citations confirmed by citation_verifier.py
refine:execution-complete: All wave-listed candidates closed-or-rationale'd (only required when invocation includes "execute findings" or stronger; see Step 6)
Load relevant modules and execute analysis per tier level.
For dimension 7 (Additive Bias), run Skill(imbue:justify)
to compute the bias score, check Iron Law compliance,
and flag unnecessary additions or workarounds.
Step 3: Prioritize (refine:prioritized)
Rank findings by:
Impact: How much quality improves (HIGH/MEDIUM/LOW)
Steps 1-5 produce a plan. Steps 6 produces closures. Both are part of the skill. Execution does not stop at planning unless the user explicitly says "plan only".
Execution mode detection
Match the user's invocation phrasing against this table to determine execution scope:
User said
Mode
Stop when
/code-refinement (no qualifier)
Plan only
After Step 5
--dry-run or "just plan"
Plan only
After Step 5
"execute findings" / "apply fixes"
Plan, execute Wave 1
After all SMALL-effort, and LOW-risk findings closed
"execute all findings" / "all phases" / "all waves"
Plan and execute every wave
After every finding (or every wave-listed candidate) is either closed by commit or has explicit per-item rationale in the synthesis
"ignore scope guard"
Override branch-size limits
Branch metrics do not gate execution. Continue past RED zone.
"do not stop until complete" / "until ALL ... complete"
No mid-task summaries
Only declare done when synthesis has every wave-listed candidate closed-or-rationale'd
The triggers compose: --tier 3 --execute all findings --ignore-scope-guard means run every Wave 2 and Wave 3 candidate to closure regardless of branch size.
Completion gate (when execution mode is active)
The task is not complete until ALL of the following hold:
Wave 2 candidates (medium-effort, listed in synthesis "Wave 2 Candidates" section): every entry has either a closure commit or an explicit per-item line in the synthesis stating why it is not viable.
Wave 3 candidates (large-effort, listed in synthesis "Wave 3 Candidates" section): same gate. Do not pre-emptively defer LARGE-effort items with generic "needs dedicated PR" rationale when the user said "execute all". Execute the mechanical ones (split-by-class, mixin-package, module-merge) and reserve "deferred" only for items requiring architecture-level decisions (schema changes, new dependency declarations, new venv layouts).
Synthesis updated: docs/refinement/<date>/00-synthesis.md records every closure with its commit SHA and every deferral with one-sentence rationale.
Anti-pattern detector for the agent itself
If the model finds itself doing any of the following during execution, this is a stop-hook leak. Go back to executing findings:
Anti-pattern
Recognise as
"Wave 2 closed. Moving to Wave 3." (mid-run summary)
Premature turn-completion signal: keep working
"Documenting deferred items with rationale" before all mechanical items are done
Skipping execution under a paper trail
Writing a completion summary while >0 listed candidates lack closure-or-rationale
Violation of completion gate
Re-asking user "should I continue?" when invocation included "do not stop"
Ignoring the explicit no-mid-task-summary contract
If the harness fires a stop signal mid-execution and the completion gate is not met, immediately resume with the next finding.
Verify Findings Are Grounded (refine:findings-verified)
Every finding must cite a real location and a verbatim anchor. Write
findings to .review/findings.json and confirm each citation resolves:
Drop or label UNVERIFIED any finding the verifier fails (exit 1); only
verified findings enter the report. See Skill(imbue:review-core) Step 5
and Skill(imbue:structured-output) for the schema.
Exit Criteria
All six analysis dimensions have a verdict (finding or "no issue
detected") for the target scope.
Each finding includes a file path, line range, and verbatim
Anchor (the exact source text at that line).
Every reported finding carries a Location + verbatim Anchor
confirmed by citation_verifier.py (exit 0), or unverified
findings were dropped or labeled UNVERIFIED.
