Refactor brief
Workflow
- Clarify the pain, affected users/maintainers and desired outcome. Inspect the code,
callers, tests and domain vocabulary. Ask only targeted questions the repository
cannot answer. Distinguish current evidence from assumptions.
- Identify invariants, public contracts, data behavior and boundaries that must remain
stable. Compare plausible approaches; use design-twice when a substantial interface
decision is still open. Preserve settled decisions.
- Write an RFC with Problem, Proposed solution, Scope/non-goals, Commit sequence,
Decision record, Testing decisions, Risks/rollback, and Further notes.
The decision record covers modules/interfaces and any schema/API compatibility.
- Make the sequence small and working after every commit: characterization first,
introduce a seam, migrate callers incrementally, remove obsolete code, verify.
Tie tests to preserved behavior and likely regression, not implementation structure.
- Keep the issue's problem and sequence portable at the domain/behavior level.
Put source-path evidence in an investigation appendix when it helps reviewers.
- If the user requested a GitHub RFC issue, run gh-readiness, check duplicates and
create it using the available connection/CLI. Otherwise return or save the brief
as requested. Hand off to execute-prd only when implementation is requested.
Example
"Write a refactor RFC for these duplicated pricing rules" → caller/behavior evidence,
characterization cases, incremental migration and an explicitly unchanged price contract.
Closed decisions and open decisions
Record selected interfaces and authority. Expose unresolved compatibility decisions;
do not hide behavior changes inside a refactor.
Do not
Do not edit production code during planning, invent a big-bang rewrite, or file an
issue when the request only asks for a draft.
Codex integration
Use $refactor-brief explicitly or let its description match the request. Resolve sibling
skills inside this plugin. Read AGENTS.md before repository edits; honor the current
host's tool access and delegation rules. Do not require another platform's runtime.
1---2name: refactor-brief-43description: Investigate a refactoring problem and produce an RFC with preserved behavior, interface decisions, characterization tests and small working commits. Use for refactor planning or an issue brief, not for applying a refactor that is already specified.4---56# Refactor brief78## Workflow91. Clarify the pain, affected users/maintainers and desired outcome. Inspect the code,10 callers, tests and domain vocabulary. Ask only targeted questions the repository11 cannot answer. Distinguish current evidence from assumptions.122. Identify invariants, public contracts, data behavior and boundaries that must remain13 stable. Compare plausible approaches; use design-twice when a substantial interface14 decision is still open. Preserve settled decisions.153. Write an RFC with Problem, Proposed solution, Scope/non-goals, Commit sequence,16 Decision record, Testing decisions, Risks/rollback, and Further notes.17 The decision record covers modules/interfaces and any schema/API compatibility.184. Make the sequence small and working after every commit: characterization first,19 introduce a seam, migrate callers incrementally, remove obsolete code, verify.20 Tie tests to preserved behavior and likely regression, not implementation structure.215. Keep the issue's problem and sequence portable at the domain/behavior level.22 Put source-path evidence in an investigation appendix when it helps reviewers.236. If the user requested a GitHub RFC issue, run gh-readiness, check duplicates and24 create it using the available connection/CLI. Otherwise return or save the brief25 as requested. Hand off to execute-prd only when implementation is requested.2627## Example28"Write a refactor RFC for these duplicated pricing rules" → caller/behavior evidence,29characterization cases, incremental migration and an explicitly unchanged price contract.3031## Closed decisions and open decisions32Record selected interfaces and authority. Expose unresolved compatibility decisions;33do not hide behavior changes inside a refactor.3435## Do not36Do not edit production code during planning, invent a big-bang rewrite, or file an37issue when the request only asks for a draft.3839## Codex integration40Use `$refactor-brief` explicitly or let its description match the request. Resolve sibling41skills inside this plugin. Read AGENTS.md before repository edits; honor the current42host's tool access and delegation rules. Do not require another platform's runtime.
garyld1962