I propose a guided refactor workflow
I propose adding a guided refactor workflow to Memtrace for files and functions that have become too large or tangled for an agent to change safely.
The problem is not the line count by itself. Some large files are generated, repetitive, or stable. Other files are much smaller but contain one long function, several responsibilities, a lot of recent change, and callers spread across the repository. A simple “this file has 10,000 lines” warning does not tell a developer what to do next, and it gives a coding agent almost no useful boundary.
I would like Memtrace to answer a more practical question:
Is there a safe first step toward splitting this code, and can an agent complete it without widening the change as it goes?
What the user would see
The Quality page would explain why a refactor is worth considering. It could show complexity, recent change activity, affected callers, test evidence, and architectural boundaries alongside LOC. The result would be classified as Automatic, Staged, or Manual, so the user can see how much confidence Memtrace has before any source code changes.
A finding might look like this:
parser.rs
Refactor recommended · Staged
Why: one 1,372-line function, high recent churn, 43 upstream callers,
two stable responsibilities, and one boundary that needs review.
First safe step: capture the current diagnostic behavior in tests.
[Build blueprint]
Clicking Build blueprint would open a refactor workspace with four stages:
- Diagnose explains the finding and the risks.
- Blueprint shows the proposed boundaries, exact order of work, and checks for each step.
- Execute follows the active agent, current diff, completed checks, and any decision that needs the user.
- Verify compares the code before and after, including tests, compiler or type-checker results, complexity, and affected callers.
The important part is that this would be a tracked run, not a large prompt that disappears into an agent chat. A user could close the browser, come back later, and see where the refactor stopped and why.
The same workflow from an agent
I also propose making this available as a Memtrace skill. A user could ask an agent to run something like:
$memtrace-guided-refactor parse_inner
The skill and the Quality page would refer to the same run. If the agent starts it, progress appears in the UI. If the user starts in the UI, the run can be handed to an agent. Each change stays small, is checked before the next change begins, and pauses when the source has changed or the evidence is not good enough.
This fits the role I want Memtrace to play. Memtrace already helps an agent understand callers, change history, impact, and code structure. A guided refactor would turn that understanding into a visible sequence of work while leaving the compiler, tests, and user in control of acceptance.
Language support
I do not think this should pretend every language has the same refactoring safety. Rust ownership and macros create different risks from Python imports, JavaScript module side effects, C++ preprocessing, or Elixir metaprogramming.
The first version should give every language Memtrace currently indexes an honest diagnosis and plan. Source edits can then be enabled language by language, starting with a narrow set of operations that the language's own compiler and tooling can check. When Memtrace cannot prove that a boundary is safe, it should say Manual and still provide the evidence a developer needs.
Configuration languages would also need a different workflow. Splitting a Terraform block, SQL migration, or YAML document is not the same action as extracting a function, even when the Quality page is the entry point.
What this should avoid
- Flagging a file only because it crossed an arbitrary LOC threshold
- Asking one agent to rewrite a giant file in a single pass
- Hiding uncertainty behind an “automatic” label
- Letting several agents edit the same large file at once
- Continuing after a compiler, test, API, or scope check fails
- Claiming that passing tests proves every behavior is unchanged
The goal is smaller and more useful: find a credible boundary, make one bounded change, check it, record it, and only then continue.
Feedback wanted
I would like feedback from people who have watched coding agents struggle with large refactors.
- Which languages should be supported for source edits first?
- What kind of refactor repeatedly goes wrong in your codebase?
- Which checks would you need to trust a staged run?
- Would you rather begin from the Quality page, an agent skill, or both?
Concrete examples are especially useful, including cases where a large file should not be split at all.
I propose a guided refactor workflow
I propose adding a guided refactor workflow to Memtrace for files and functions that have become too large or tangled for an agent to change safely.
The problem is not the line count by itself. Some large files are generated, repetitive, or stable. Other files are much smaller but contain one long function, several responsibilities, a lot of recent change, and callers spread across the repository. A simple “this file has 10,000 lines” warning does not tell a developer what to do next, and it gives a coding agent almost no useful boundary.
I would like Memtrace to answer a more practical question:
What the user would see
The Quality page would explain why a refactor is worth considering. It could show complexity, recent change activity, affected callers, test evidence, and architectural boundaries alongside LOC. The result would be classified as Automatic, Staged, or Manual, so the user can see how much confidence Memtrace has before any source code changes.
A finding might look like this:
Clicking Build blueprint would open a refactor workspace with four stages:
The important part is that this would be a tracked run, not a large prompt that disappears into an agent chat. A user could close the browser, come back later, and see where the refactor stopped and why.
The same workflow from an agent
I also propose making this available as a Memtrace skill. A user could ask an agent to run something like:
The skill and the Quality page would refer to the same run. If the agent starts it, progress appears in the UI. If the user starts in the UI, the run can be handed to an agent. Each change stays small, is checked before the next change begins, and pauses when the source has changed or the evidence is not good enough.
This fits the role I want Memtrace to play. Memtrace already helps an agent understand callers, change history, impact, and code structure. A guided refactor would turn that understanding into a visible sequence of work while leaving the compiler, tests, and user in control of acceptance.
Language support
I do not think this should pretend every language has the same refactoring safety. Rust ownership and macros create different risks from Python imports, JavaScript module side effects, C++ preprocessing, or Elixir metaprogramming.
The first version should give every language Memtrace currently indexes an honest diagnosis and plan. Source edits can then be enabled language by language, starting with a narrow set of operations that the language's own compiler and tooling can check. When Memtrace cannot prove that a boundary is safe, it should say Manual and still provide the evidence a developer needs.
Configuration languages would also need a different workflow. Splitting a Terraform block, SQL migration, or YAML document is not the same action as extracting a function, even when the Quality page is the entry point.
What this should avoid
The goal is smaller and more useful: find a credible boundary, make one bounded change, check it, record it, and only then continue.
Feedback wanted
I would like feedback from people who have watched coding agents struggle with large refactors.
Concrete examples are especially useful, including cases where a large file should not be split at all.