refine
Installation
SKILL.md
Refine
The scope is whatever the user asks to refine; without one, use the current staged and unstaged diff, including untracked source files. If there is no code to refine, say so and stop. A scope that names changes — pending changes, a branch, a pull request — is refined as the diff it names; everything else is an area.
Load the refinements skill and hold every change to its rules and its three lenses: constraints, simplicity, and parametricity. If it is not installed, install it with:
npx skills add https://github.com/alexandru/skills --skill refinements
Workflow
- Establish scope, contracts, and verification. Read the project's agent instructions, conventions, and relevant specifications. Identify the behavior and APIs to preserve, the scope's hot paths, and the required verification. Where a specification leaves behavior undefined, investigate existing contracts and callers; report unresolved ambiguity rather than inventing a requirement.
- Identify and apply justified refinements. Review through the three lenses and trace callers to check behavior claims. Each change must name the complexity it removes and preserve the contracts below. Verify edits with the relevant tests; add characterization tests where observable behavior is uncovered. Report existing bugs that require behavior changes for approval; when a fix is authorized, demonstrate it with a failing test before fixing it.
- Repeat until no worthwhile improvement remains. Reassess the changed code and its core model for further justified refinements within scope. Look beyond local cleanups: a different representation can eliminate invalid states, a pass, or an entire module.
- Review, verify, and report. Review the aggregate diff for regressions and interactions between changes. Fix or revert regressions, run the project's required verification across supported configurations, and rerun after fixes. Check performance when hot paths change. Report the complexity removed, authorized bug fixes and their tests, verification results and limitations, and decisions left to the user.