<!-- Generated by mstack from Misbah's Build Like This workflow. Regenerate instead of editing. -->

safe-refactoring

This skill is part of Misbah Khursheed's Build Like This workflow. Thinking, evidence, and explicit trade-offs come before generated output.

Project identity and sources of truth

The repository where this skill is installed is the host project being built. Build Like This is the method used to build it; mstack only installs and reconciles method resources. Do not assume mstack or Build Like This is the product unless project-owned sources explicitly identify this repository as mstack itself.

Use project-owned docs/, decisions, executable code, and tests as sources of truth. .mstack/templates/ are reference scaffolds to copy and adapt into project-owned documents, not product requirements and not a replacement for docs/.

Purpose

Make a concrete future change safer or cheaper by improving cohesion, ownership, and dependency direction without mixing in new behavior.

Required inputs

• Specific maintenance pain or upcoming change, affected code/callers, and desired structural outcome.
• Observable behavior and public contracts that must remain stable.
• Existing tests, performance constraints, rollout risk, and allowed change scope.

If a missing input would materially change the result, state the gap and obtain or discover it before proceeding. Otherwise label the assumption and continue.

Process

1. State the structural smell in terms of change cost, coupling, responsibility, or testability.
2. Map callers, dependencies, side effects, public surface, and the invariants to preserve.
3. Add focused characterization tests where important behavior lacks evidence.
4. Design a sequence of small transformations, each compiling and independently verifiable.
5. Move behavior toward the owning module, remove obsolete paths, and avoid premature generalization.
6. Compare before/after structure and run focused plus broader regression checks.

Output contract

• Problem statement, preserved invariants, target boundary, and staged transformation plan.
• Behavior-preserving change with strengthened tests and no unrelated feature work.
• Before/after dependency explanation, verification, and intentionally deferred cleanup.

Guardrails

• Do not combine refactoring with semantic behavior changes unless inseparable and explicitly reviewed.
• Do not introduce a shared abstraction until stable common behavior and variation are demonstrated.
• Do not optimize for fewer files or lines at the expense of clear ownership.

Delegation and parallel safety

• Material lifecycle work must delegate at least one bounded specialist lane when subagents are available. Prefer two or more concurrent lanes only for independent evidence gathering, analysis, or non-overlapping file ownership.
• The active lead owns integration and acceptance. Supporting agents do not recursively delegate unless explicitly promoted to lead a named lane.
• Assign distinct outputs and ownership. Serialize shared docs, contracts, schemas, migrations, deployments, external writes, and overlapping file edits.
• When subagents are unavailable, perform the same named specialist passes sequentially and state that constraint instead of implying parallel verification.
• Delegation never grants permission for outreach, consequential external actions, destructive changes, paid resources, or production operations.

End with the evidence gathered, verification performed, and any residual risk or unresolved decision.