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.
Copilot integration
This skill is the durable entrypoint for Copilot hosts that load agent skills.
The matching prompt file is an optional VS Code shortcut. Read repository instructions
before edits; use the tools actually exposed by the host, including connected GitHub
access when available. A prompt or skill does not itself grant additional permissions.
1---2name: refactor-brief-33description: 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## Copilot integration40This skill is the durable entrypoint for Copilot hosts that load agent skills.41The matching prompt file is an optional VS Code shortcut. Read repository instructions42before edits; use the tools actually exposed by the host, including connected GitHub43access when available. A prompt or skill does not itself grant additional permissions.
garyld1962