Capstone: Write a Short Refactor Proposal

By the end of this lesson, you will be able to...

• Write a short refactor proposal that states a goal, purpose, method, ownership, risk, and trade-off.

• Use the track's action patterns naturally: doing, to do, by doing, without doing, and threshold language.

• Separate a recommendation from evidence, a plan from a result, and interest from responsibility.

Idea in one sentence: A strong refactor proposal makes one recommendation inspectable by showing what will change, why it matters, how it will happen, what it costs, and when the team should continue.

Core Insight

This is the capstone for the track. The goal is not to demonstrate every grammar label. The goal is to write the kind of short proposal an engineer could put in a pull request, design note, or team discussion.

A useful proposal answers six questions:

1. What problem are we seeing?
2. What change do we recommend?
3. What is the purpose of the change?
4. How will we implement it, and what will we avoid changing?
5. Who owns the work and what makes it risky?
6. What evidence tells us whether to continue, stop, or roll back?

The grammar patterns make those relationships visible:

We recommend extracting validation from the API handler to reduce coupling.
We plan to do this by moving one rule at a time without changing the public API.
Maya is responsible for reviewing the new interface.
The refactor is too risky to deploy globally before a canary.
It is worth testing because the current module is difficult to isolate.

The proposal is not only about grammar. It is an engineering argument in a small form. The reader should be able to disagree with the recommendation, but should not have to guess what the recommendation means.

The Scenario

The request service has one module that performs three jobs:

• it parses incoming configuration;
• it validates the configuration;
• it formats HTTP error responses.

The module has grown over time. Tests that should check validation now need HTTP fixtures. A small validation change can affect response formatting. Engineers also find it difficult to reuse the parser in a background worker because the module expects an HTTP request and response.

The team is considering a refactor. It does not want to redesign the public API during the same change. It wants a smaller boundary first:

request handler -> parser and validator -> response formatter

The proposal must be honest about the scope. The team is not promising a new architecture for every service. It is recommending one extraction that makes validation easier to test and reuse.

Constraints

Before writing the proposal, collect the constraints. They give the grammar something concrete to express:

• clients must continue sending the same request shape;
• existing error responses should remain compatible;
• the first change should move one validation rule at a time;
• unit tests should cover the extracted module;
• contract tests should protect the public response shape;
• the refactor should be tested in staging before a global deployment;
• rollback should be possible without restoring an old database schema;
• one engineer owns interface review, while another owns the canary decision.

These constraints create a real trade-off. A small extraction reduces coupling and improves testability, but the team must temporarily maintain a boundary between old response formatting and new validation code. A larger rewrite might look cleaner, but it would increase the number of simultaneous changes and make rollback harder.

The Promise We Need to Keep

A proposal should state its promise before listing its steps. Here the promise is:

We recommend extracting validation from the request handler to make the validation rules easier to test and reuse, without changing the public API.

The sentence contains the recommendation, purpose, and boundary:

• recommend extracting names the proposed action as an activity;
• to make explains the purpose;
• without changing names the preserved contract.

The proposal does not promise that the refactor will remove every dependency. It promises a smaller improvement that can be checked.

Compare a weaker promise:

We recommend improving the parser to make everything cleaner.

“Improving” and “everything” hide the object and the success condition. A reviewer cannot tell what should change or what should remain stable. Prefer the concrete boundary:

We recommend extracting validation from the handler to make the rules easier to test, without changing the request or response contract.

The Naive Proposal

Here is a literal and overconfident draft:

We recommend to extract the parser because it is difficult testing. We plan extracting all validation by move it to a new service without to change the API. Luis is interested to review the interface. The refactor is enough safe to deploy everywhere because the tests pass.

There are grammar problems, but there are also engineering problems:

• recommend to extract uses the wrong pattern for this recommendation;
• difficult testing hides what is difficult;
• plan extracting should show a plan with to + verb;
• by move needs by + -ing;
• without to change needs without + -ing;
• interested to review reports neither normal interest nor clear ownership;
• enough safe puts enough in the wrong position;
• passing tests alone does not prove that a global deployment is safe.

The last claim is especially dangerous. A proposal should not convert a local test result into a broad safety guarantee. The capstone must connect readiness to scope and evidence.

The Proposed Model

Build the proposal in layers.

Recommendation and purpose

Use recommend + -ing for a recommendation about an activity:

We recommend extracting validation from the request handler to reduce coupling.

The recommendation is not yet a completed plan. It says what the writer believes the team should choose. The purpose says why.

If the team accepts the recommendation, move to a plan:

We plan to extract one validation rule at a time.

The distinction matters in a review. A recommendation invites a decision; a plan describes the next action after the decision.

Method and boundary

Explain how the extraction will happen:

We will reduce coupling by moving one validation rule at a time into a small module.

Protect the interface:

We will do this without changing the public request or response shape.

The method is by moving. The preserved boundary is without changing. Neither phrase is a purpose. If the reader asks “Why?”, use a separate purpose phrase:

We will move one rule at a time to make failures easier to isolate.

Ownership and interest

A proposal needs an owner for a decision or review:

Maya is responsible for reviewing the extracted interface.

Another engineer may be interested in a later improvement:

Luis is interested in reusing the validator in the background worker.

Do not use the second sentence as a delivery commitment. If Luis owns the next experiment, state it:

Luis plans to test the validator in the background worker after the first extraction.

The proposal can contain both facts without confusing them:

Maya is responsible for reviewing the interface. Luis is interested in reusing the validator, but that work is outside this first change.

Risk and readiness

Connect risk to a specific action:

The refactor is too risky to deploy globally before a canary.

Then define the smaller allowed action:

It is safe enough to test in staging after the contract tests pass.

After the canary produces evidence, the team may write:

The canary is stable enough to expand if error rate stays below the threshold and rollback completes within two minutes.

“Safe enough” is not a universal property. It is a threshold for a scope. The proposal should say what makes the threshold credible.

A Worked Proposal

Let us assemble the proposal from the scenario and constraints.

The short proposal is:

The handler mixes validation with HTTP response formatting, so validation tests require HTTP fixtures. We recommend extracting validation into a small module to make the rules easier to test and reuse. We plan to move one validation rule at a time by placing it behind a small interface, without changing the public request or response shape. Maya is responsible for reviewing the interface, while Luis is interested in later worker reuse. The refactor is too risky to deploy globally before a canary, but it is safe enough to test in staging after unit and contract tests pass. We will expand only if error rate and rollback time stay within the agreed limits.

This is a proposal, not a guarantee. It gives the reader enough information to approve, reject, or revise the change.

Walkthrough: Reading the Proposal as a Reviewer

Read the proposal in four passes.

Pass 1: find the recommendation

Ask what the team should choose:

We recommend extracting validation into a small module.

If the recommendation is missing, the rest may read like disconnected observations.

Pass 2: find the cost and purpose

Ask why the change is worth doing:

The handler mixes validation with response formatting, so validation tests require HTTP fixtures.

The purpose is not “make everything better.” It is easier testing and reuse. A purpose should connect to the problem.

Pass 3: find the boundary and owner

Ask what the team will not change and who checks the new boundary:

We will do it without changing the public request or response shape.
Maya is responsible for reviewing the interface.

This is where many short proposals fail. They describe an action but do not identify who owns the risk or what remains compatible.

Pass 4: find the evidence threshold

Ask what happens after implementation:

We will expand only if error rate and rollback time stay within the agreed limits.

This keeps “safe enough” tied to evidence. It also gives the team a stop condition.

Failure Review

A proposal can be grammatically correct and still be weak. Review these failures:

Failure: recommendation becomes an unsupported promise

Extracting the parser will solve the testing problem.

This is too strong. The extraction may help, but the proposal should name the intended benefit and the evidence:

We recommend extracting validation to make the rules easier to test. We will confirm the benefit by running module tests without HTTP fixtures.

Failure: method is hidden inside a vague verb

We will improve the parser by changing the code.

The method is technically grammatical but not inspectable. Name the mechanism:

We will reduce coupling by moving validation behind a small interface.

Failure: ownership becomes interest

Maya is interested in checking the interface.

This may be true, but it does not assign the work. If the proposal needs an owner, write:

Maya is responsible for checking the interface.

Failure: scope disappears from the risk sentence

The refactor is too risky to deploy.

Deploy where? A staging deployment may be acceptable while a global deployment is not:

The refactor is too risky to deploy globally, but it is safe enough to test in staging.

Failure: purpose is reported as a result

We extracted validation to improve testability, so testing is now easier.

The second clause is a result claim. Add evidence before making it:

We extracted validation to improve testability. The new module now runs without HTTP fixtures in the staging test suite.

Trade-offs

Every refactor proposal should name what improves and what becomes more expensive. For this proposal:

The proposal should not say that the refactor “solves coupling” as if no cost remains. A precise statement is:

The refactor should reduce coupling in the validation path, at the cost of maintaining a small adapter until response formatting is separated later.

That is a useful trade-off because it lets the reviewer decide whether the intermediate state is acceptable.

Evidence and Readiness

Use observable signals to decide whether the proposal is working:

• module tests run without HTTP fixtures;
• contract tests preserve request and response behavior;
• error rate does not increase during the canary;
• rollback completes within two minutes;
• the extracted module can be imported by the worker without importing the HTTP layer.

A readiness statement can combine a threshold and a condition:

The canary is safe enough to expand if contract tests pass, error rate stays below the current threshold, and rollback completes within two minutes.

The sentence does not guarantee success. It describes the evidence needed for the next decision. If one signal fails, write the next action instead of hiding the failure:

The canary is not safe enough to expand because rollback took five minutes. We will keep the release at five percent while improving the restore path.

Final Challenge

Write your own short refactor proposal. Choose one scenario:

• extract a parser from an API handler;
• move a retry policy into a worker module;
• add a cache while preserving the response contract;
• migrate a queue without stopping its consumers.

Write six or seven sentences. Include:

1. the current problem;
2. a recommendation with recommend + -ing or an equivalent clear recommendation;
3. a purpose with to + verb;
4. a method with by + -ing;
5. a preserved boundary with without + -ing;
6. an owner with responsible for + -ing;
7. a risk, trade-off, and evidence threshold.

Use this rubric:

Model answer for a queue refactor:

The queue consumer retries acknowledged messages and sometimes creates duplicate jobs. We recommend moving the retry decision into a small worker policy to make the state transition easier to test. We plan to do this by checking acknowledgement state before scheduling a retry, without changing the consumer API. Luis is responsible for reviewing the policy, while Priya is interested in reusing it for the batch worker later. The refactor is too risky to deploy globally before a canary, but it is safe enough to test with five percent of traffic after the duplicate-job test passes. The trade-off is a temporary adapter between the old consumer and the new policy. We will expand only if duplicate jobs remain at zero and rollback completes within two minutes.

Before you finish, read the proposal once as an engineer and once as a non-native English reader. Remove any sentence that repeats a pattern without adding a decision. Keep the technical noun, the action, the boundary, and the evidence visible.

The reader should finish with a clear next decision, not only a polished paragraph. If the evidence is missing, the proposal should say what the team will measure before expanding the change.

Daily Practice Lines

Repeat these during the day. The third line revisits the method pattern from lesson 014.

• We recommend extracting the parser to reduce coupling.
• The refactor is too risky to deploy globally before a canary.
• We will do this by moving one rule at a time without changing the API.

Change one technical object when the lines feel easy: parser, worker, queue, cache, migration, or alert. Keep the proposal roles stable while the scenario changes.

Resources

• [ARTICLE] Cambridge Dictionary: Recommend - Compare recommend + -ing with recommendation structures and keep the proposed activity explicit.
• [ARTICLE] Cambridge Dictionary: Verb patterns - Review the action patterns used in the proposal: to + verb, preposition plus -ing, and purpose or method phrases.
• [ARTICLE] Microsoft Writing Style Guide - Keep the refactor proposal concise, concrete, and explicit about trade-offs, ownership, scope, and evidence.

Key Takeaways

• A refactor proposal should make one recommendation and connect it to a concrete problem.
• Use recommend + -ing for the proposed activity, to + verb for purpose, and by + -ing for method.
• Use without + -ing for a preserved boundary and responsible for + -ing for ownership.
• Too risky to do and safe enough to do must name an action and scope; neither is a universal safety guarantee.
• A complete proposal states its trade-off and its evidence threshold so the team knows when to continue, stop, or roll back.