skill-refactor

Skill Refactor

End-to-end token-efficiency and reliability pass on a DSO skill: review → approved plan → code/doc/test changes → ticket reconciliation → tessl review → committed result.

When to use

User signals: "review the X skill", "audit X", "can we optimize X?", "clean up X", "X is bloated", "X isn't reliable", or any request that implies critiquing a specific skill file and improving it.

Inputs

• Skill name (bare, no dso: prefix) — e.g., architect-foundation, brainstorm.
• The skill's SKILL.md at plugins/dso/skills/<name>/SKILL.md.
• Any co-located phase files under plugins/dso/skills/<name>/phases/ or equivalent.

Workflow

The workflow is nine sequential phases. Do not skip. Phases A and B are synchronous with the user; Phases C–I execute autonomously once the plan is approved.

PA Critical review            → present findings
PB Remediation plan           → await explicit approval
PC Script relocation          → move skill-scoped scripts to shared sub-dir
PD Reference updates          → skill body, tests, docs
PE Change-detector test sweep → remove prose-grepping tests
PF Ticket reconciliation      → comment on open tickets affected
PG Renumbering                → renumber phases (A,B,C…) and steps (1,2,3…); update cross-skill refs
PH Tessl skill review         → run tessl skill review; act on valid+actionable findings
PI Commit                     → via COMMIT-WORKFLOW.md; surface review findings

---

White elephants: phrasings to remove

A white elephant in a skill file is a phrasing that is intended to enforce a rule but instead creates the very temptation it forbids. The phrase names a bypass shape (cost-pressure, urgency-pressure, perceptual judgment) and then tells the agent to ignore it. The naming makes the bypass salient. White elephants are the symmetric counterpart to the "Hard gates: compress, do not remove" rule below: hard gates are load-bearing enforcement that must be preserved (compress only); white elephants are bypass-narration that should be removed entirely (the rule's positive form already does the enforcement work).