safe-refactor-code

Safe Refactor Code

Refactor code in small verified slices, then update the repo's continuity files so future agents can resume without rereading the whole session.

Core Rules

Treat AGENTS.md at repo root as the main long-term repo memory. Preserve existing content and update it carefully instead of rewriting blindly.
Keep agent-local MEMORY.md short. It is a working summary for the repo, not a replacement for any shared or tool-managed memory system.
Keep safe-refactor-code.md focused on the repo's refactor rules, guardrails, and recurring cleanup workflow.
.safe-code/CHANGELOG.md: under safe-code, only releasable changes, in safe-code's Keep-a-Changelog template (## [Unreleased] + typed subsections; the file is created on the first releasable change). Standalone, use today's dated section (## [YYYY-MM-DD], below).
Prefer additive or scoped edits to docs. Do not wipe user-written history unless the user explicitly asks.
After refactors, scan for obvious dead code, unused imports, stale helpers, and outdated doc references before finishing.
Use the codegraph index when available. Fall back to direct source search and verification when it is unavailable or empty.

Graph-Aware Refactor Rules

Start graph-assisted refactors with codegraph explore "<refactor goal>" (or codegraph_explore).
Run codegraph sync before broad refactors ($build-graph when no index exists).
Symbol renames have no graph preview: list codegraph callers <old> and codegraph impact <old> first, edit, then confirm with rg "<old>" -> 0 hits (plus a positive control on the new name).
For broad or shared-code changes, run codegraph impact <symbol> before editing.
For dead code exposed by the refactor, codegraph callers <symbol> empty is a candidate only (it resolves by name); delete only High-confidence candidates after rg, config, and dynamic-reference checks.
Before final summary, run codegraph sync + codegraph affected <changed files> and run the tests it lists.

Agent Compatibility

Write this skill so any AI agent can follow it, not only one product or runtime.
Prefer generic terms such as "agent", "current repo", and "available verification tools".
If the host environment has its own global or shared memory system, treat that as separate from repo-local docs.
If the current repo uses different handoff files, adapt carefully but preserve the same responsibilities.

Step 0: Locate Doc Folder

Session and continuity docs live in a single agent-agnostic folder at the repo root:

doc folder = <repo-root>/.safe-code/

No agent detection is needed. Codex, Claude, Cursor, and Windsurf all share the same .safe-code/ folder so continuity belongs to the repo, not the tool. Create <repo-root>/.safe-code/ if it does not exist yet.

Doc file locations:

File	Path
`AGENTS.md`	repo root (always)
`MEMORY.md`	`.safe-code/MEMORY.md`
`CHANGELOG.md`	`.safe-code/CHANGELOG.md`
`safe-refactor-code.md`	`.safe-code/safe-refactor-code.md`

Step 0.5: Assess and Write AGENTS.md

This step is mandatory. Run it before reading or touching any code — except under /safe-code: when that run already reconciled AGENTS.md (Step 3d: created, populated, reconciled, or audited unchanged), that reconciliation satisfies this step; do not repeat it.

Canonical authoring rules: When running under safe-code, the single source of truth for how to write AGENTS.md is the safe-code skill's references/agents-md-authoring.md (decision test, investigation order, what to extract/exclude, minimum quality bar). Follow it instead of improvising. The compact rules below are the standalone fallback when that reference is not available.

Timing under safe-code: when this skill runs under /safe-code, AGENTS.md content updates follow safe-code's Draft-Until-Save (draft in .safe-code/SESSION.md, apply on /safe-code --save; First-Run Population excepted). The mandatory-immediate write below applies when running standalone.

Detect if AGENTS.md is effectively empty

Treat AGENTS.md as effectively empty if it contains only:

HTML comment blocks  ... 
Blank lines
Auto-generated rules injected by tooling

Do not treat generated blocks as agent or human-written state. They are tooling artifacts, not project context.

Detect project freshness

if AGENTS.md is missing OR effectively empty
    → fresh = true   (full project scan required)

if AGENTS.md has existing agent-written or human-written state sections
    → fresh = false  (update affected sections only)

Write AGENTS.md — no skipping allowed

Regardless of fresh value, always update AGENTS.md before touching any code. This is not optional — standalone. Under /safe-code, the AGENTS.md reconciliation that run already did satisfies it (see above).

If fresh = true, scan the project and write a full orientation snapshot:

Stack — languages, frameworks, major dependencies with versions if available
Folder structure — key directories and what they own
Key files — entry points, config files, critical modules
Conventions — naming patterns, coding style, file organisation rules
Gotchas — anything non-obvious a future agent must know before editing

Preserve any existing generated blocks (). Append the orientation snapshot after them — do not replace or remove tooling-injected content.

If fresh = false, update only the sections relevant to the upcoming refactor. Preserve all existing content outside those sections.

AGENTS.md is the primary handoff document for any future agent entering this repo in a new context. Never skip this step.

Workflow

1. Read Continuity Files First

After writing AGENTS.md, inspect these files when present:

AGENTS.md at repo root (already written in Step 0.5)
.safe-code/safe-refactor-code.md
.safe-code/MEMORY.md
.safe-code/CHANGELOG.md

If one is missing, create it only if the refactor work makes it useful.

Fallback for missing AGENTS.md:

Prefer an existing equivalent file such as CLAUDE.md, GEMINI.md, or another repo handoff guide at root.
If an equivalent exists, treat it as the main continuity document for this run.
If no equivalent exists, create AGENTS.md only when the refactor changes architecture or handoff risk enough that future agents would benefit.

2. Plan With Graph Context When Available

Use this order:

codegraph explore "<refactor goal>"
codegraph sync if the index is stale ($build-graph if none exists)
codegraph impact <symbol> for files or symbols likely to affect callers
codegraph callers|callees <symbol> for changes that can affect runtime paths

If codegraph fails, record the failure briefly and continue with rg, imports, manifests, tests, and direct source reads.

3. Refactor in Safe Slices

Prefer one subsystem or concern at a time.
Preserve behavior unless the user asked for a behavior change.
Verify each slice with the narrowest useful checks available: lint, type-check, tests, build, or targeted probe.
If a refactor exposes dead code, remove obvious leftovers in the same area when confidence is high.
If cleanup risk is non-trivial or the repo has many stale modules, map blast radius before deleting and flag low-confidence candidates instead of auto-removing.
A refactor claimed to be "faster" or "lighter" needs a before-baseline measured under the same conditions; without one, report the claim as a hypothesis. "Fewer lines" is not performance evidence.
Undo a slice by re-editing or from a backup; no destructive git in a checkout that may be shared — follow the safe-code skill's references/multi-session.md (Shared-checkout rules).

If widespread dead code is detected beyond the immediate refactor area, invoke the codebase-pruner skill for a full repo dead code audit.

4. Post-Change Review

Before syncing docs:

Run codegraph sync + codegraph affected <changed files> if an index is available, and run the tests it lists when blast radius is non-trivial.
Read changed files directly and remove accidental unused imports or stale exports.
Run the narrowest useful verification command.

5. Sync Docs Before Finishing

After real code changes, update the continuity files in .safe-code/ (and AGENTS.md at repo root). When running under safe-code, draft these updates in .safe-code/SESSION.md instead and apply them on /safe-code --save:

AGENTS.md (repo root) — current state, key decisions, blockers, handoff notes
safe-refactor-code.md — repo-specific refactor constraints and recurring cleanup rules
MEMORY.md — short current snapshot, active caveats, important paths
CHANGELOG.md — releasable changes only; under safe-code the Keep-a-Changelog template, standalone today's dated section

6. Keep Changelog Shape Stable

Under safe-code, follow its Keep-a-Changelog template (the safe-code skill's references/doc-templates.md) and add entries only for releasable changes. Standalone, use this dated structure:

## [YYYY-MM-DD]

### Added
- ...

### Changed
- ...

### Fixed
- ...

### Removed
- ...

Reuse today's section if it already exists.
Omit empty subsections when nothing belongs there.
Do not add a changelog entry for read-only review or analysis turns.

7. Finish With a Hygiene Pass

Before closing:

Remove unused imports introduced by the refactor.
Remove helpers, exports, or files made dead by the refactor when confidence is high.
Update stale file/path references in docs.
Note any flagged but unremoved dead code in safe-refactor-code.md or AGENTS.md.

What To Write

`AGENTS.md` (repo root)

Update only the sections affected by the refactor. Prefer:

Current repo state
Important architectural decisions
Known blockers or caveats
Where future agents should start