| name | best-practice |
| description | Apply iterative best-practice refactors (OOP, SOLID, readability, maintainability) using the quality-architect checklist while preserving behavior. |
Use this skill whenever code quality, architecture, naming, or maintainability must be improved without changing public behavior.
Slash entrypoint:
- Use
/best-practice to run the quality-focused refactor workflow.
Full agent definitions with the complete checklist and execution workflow are mirrored in .github/agents/quality-architect.md and .claude/agents/quality-architect.md.
Read that file before broad or multi-file refactors.
Scope
- Improve cohesion, readability, and testability in small safe steps.
- Reduce duplication and hidden coupling in touched areas.
- Keep endpoint contracts, queue/rate protections, and runtime folder policy unchanged.
Decomposition Guardrails
- Source files over 500 lines require a split plan before adding new responsibilities.
- Test runners over 250 lines should be split by scenario when behavior changes require edits.
- Service modules over 300 lines should be split by responsibility when new behavior appears.
- Functions over 60 lines should be decomposed when extraction improves readability or testability.
- Apply SOLID/OOP/GoF ideas only when they reduce real complexity, duplication, or coupling.
Recommended Iteration Loop
- Identify 1-3 highest-impact quality hotspots.
- Propose minimal refactor slices and call out risk for each slice.
- Apply one slice at a time with stable public behavior.
- Validate with relevant tests or targeted checks after each slice.
- Sync docs if behavior, workflow, or config references changed.
- Report checklist score delta and remaining backlog.
Guardrails
- Preserve endpoint and error-code contracts.
- Preserve root runtime folders (
input/, output/, configs/).
- Keep queue and rate-limit protections active.
- Avoid one-shot rewrites; ship in safe iterations.
- Prefer evidence-driven refactors over speculative abstractions.
Validation Checklist
