Capstone: Give Precise Advice on a Risky Change

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

• Write a short review comment for a risky technical change using calibrated modal verbs.

• Separate capability, uncertainty, recommendation, permission, requirement, and rollback judgment in one artifact.

• Use a rubric to revise vague advice into precise engineering English.

Idea in one sentence: A good risk comment uses modal verbs to show what may happen, what the team should do, what the system must guarantee, and when rollback becomes required.

Core Insight

A team is preparing a risky change.

They want to enable automatic retries for a new checkout worker. The change should reduce stuck requests, but it also changes how the system behaves after a timeout.

A rough review comment says:

This can be dangerous. We could ship it but must be careful. Maybe support can disable it if there is a problem.

The comment is understandable. It is not precise enough for a risky change.

Can be dangerous does not say whether the risk is a capability, a possibility, or evidence from testing. Must be careful sounds strong, but it does not name a rule. Maybe support can disable it mixes weak uncertainty with permission.

A better comment separates the jobs:

The new checkout worker might retry after a timeout and could submit the same payment twice.
We should keep the canary at 5% until duplicate-payment alerts stay quiet for one hour.
Support may disable the canary for one customer if checkout errors affect that customer.
The worker must not create two charges for the same payment id.
If duplicate payments appear, we must roll back before increasing traffic.

This is the capstone task for the track: write one short artifact where every modal has one visible engineering job.

The Capstone Situation

Use this scenario.

The team is changing a checkout worker.

Current behavior:

Client -> checkout API -> old worker -> payment provider

New behavior:

Client -> checkout API -> new worker -> retry policy -> payment provider

The new worker retries payment requests after some timeouts. That can help when the first attempt never reached the provider. It can hurt when the first attempt reached the provider but the response was lost.

The visible facts are:

Capability: the new worker can retry failed-looking requests.
Uncertainty: a timeout does not prove that the provider did nothing.
Possible event: the worker might retry after the provider already accepted the payment.
Possible consequence: the retry could create a duplicate charge.
Recommendation: the team should start with a small canary.
Permission: support may disable the canary for one affected customer.
Requirement: the worker must not create two charges for the same payment id.
Rollback rule: if duplicate payments appear, the team must roll back.
Retrospective judgment: if the alert fires, the team should have blocked the traffic increase.

The naive model is:

Use strong language when the change is risky.

That model breaks because a risky change contains different kinds of claims.

A possible event needs might. A possible consequence often needs could. A recommended control needs should. A permission needs may or can. A hard guardrail needs must. A missed better action often needs should have.

Plain meaning:

Do not make one modal verb carry the whole review.

In this scenario:

The retry is uncertain. The duplicate charge is a possible consequence. The small canary is recommended. The no-duplicate rule is required. The rollback condition is non-negotiable.

Technical name:

This is modal calibration in a risk review. Calibration means the strength of the English sentence matches the strength of the engineering claim.

Build the Advice in Six Moves

Start from the rough concern:

The retry change can break checkout. We must be careful.

That sentence creates pressure, but it hides the decision.

Build the final comment one move at a time.

Intermediate state:

The new checkout worker can retry payment requests after a timeout.
The worker might retry after the provider already accepted the payment.
The retry could submit the same payment twice.
We should keep the canary at 5%.
Support may disable the canary for one affected customer.
The worker must not create two charges for the same payment id.

That is clear, but it reads like notes. A review comment should be short enough to post.

Combine the related pieces:

The new checkout worker can retry payment requests after a timeout.
If the provider accepted the first request but the response was lost, the worker might retry and could submit the same payment twice.
We should keep the canary at 5% until duplicate-payment alerts stay quiet for one hour.
Support may disable the canary for one affected customer, but the worker must not create two charges for the same payment id.
If duplicate payments appear, we must roll back before increasing traffic.

Output:

The reader can now answer five questions:

• What can the new worker do?
• What might happen under uncertainty?
• What could go wrong?
• What should the team do now?
• What must never happen?

Naive failure contrast:

This can break checkout, so we must be careful and maybe support can turn it off.

That version sounds serious. It still fails as advice because it hides the risk path, the canary condition, the permission boundary, and the hard rule.

A Second Pass: Repair the Weak Comment

Now revise the weak comment directly.

Input:

This can break checkout, so we must be careful and maybe support can turn it off.

First, mark the hidden pieces.

This can break checkout

This tries to describe risk, but it uses can in a confusing way. Does the worker have a normal capability to break checkout? Is checkout already broken? Or is there an uncertain risk path?

Better:

The worker might retry after a timeout and could submit the same payment twice.

Now the event and consequence are visible.

we must be careful

This sounds responsible, but it is not a usable engineering action. A teammate cannot implement be careful in code, monitoring, or rollout policy.

Better:

We should keep the canary at 5% until duplicate-payment alerts stay quiet for one hour.

Now should recommends a concrete control. The recommendation has a number, a signal, and a time window.

maybe support can turn it off

This mixes weak uncertainty with permission. If support is allowed to disable the canary, say that directly. If support is required to disable it under a condition, say that instead.

Better permission:

Support may disable the canary for one affected customer.

Better requirement:

If duplicate payments appear, we must roll back before increasing traffic.

Those two sentences do different jobs. Permission gives someone an allowed action. Requirement names the hard condition.

Intermediate state:

The worker might retry after a timeout and could submit the same payment twice.
We should keep the canary at 5% until duplicate-payment alerts stay quiet for one hour.
Support may disable the canary for one affected customer.
If duplicate payments appear, we must roll back before increasing traffic.

That is already much better. But it still misses the system invariant. The comment says what the team should do during rollout, but it does not say what the worker must guarantee.

Add the invariant:

The worker must not create two charges for the same payment id.

Final revised comment:

The worker might retry after a timeout and could submit the same payment twice.
We should keep the canary at 5% until duplicate-payment alerts stay quiet for one hour.
Support may disable the canary for one affected customer.
The worker must not create two charges for the same payment id.
If duplicate payments appear, we must roll back before increasing traffic.

Notice what changed.

The revised comment is not more dramatic. It is more inspectable. Each sentence gives the reader a different handle: risk, control, permission, invariant, rollback.

So far, the capstone habit is:

When advice feels vague, ask what job each modal is trying to do.

The Modal Audit

Before you post a risky-change comment, audit each modal.

For the capstone, use the audit as a checklist, not as a table to memorize.

Ask:

• Is this a fact about capability?
• Is this an uncertain event?
• Is this a possible consequence?
• Is this a recommendation?
• Is this permission?
• Is this a hard requirement?
• Is this a rollback condition?
• Is this a retrospective judgment?

If two answers appear in one sentence, split the sentence or make the relation visible.

Check Your Understanding

Check: Which sentence in this comment states permission, not a requirement?

Support may disable the canary for one affected customer.
The worker must not create two charges for the same payment id.
If duplicate payments appear, we must roll back before increasing traffic.

Think first, then reveal.

Answer: Support may disable the canary for one affected customer states permission. Support is allowed to do it. The sentence does not require support to disable every canary.

Check: Why is this sentence weak for a capstone review comment?

The change can be risky, so we should maybe rollback if needed.

Think first, then reveal.

Answer: It does not separate the modal jobs. Can be risky is vague, should maybe weakens the recommendation, and if needed does not name the signal that makes rollback required.

Check: Which sentence adds a system invariant?

We should keep the canary at 5%.
Support may disable the canary for one affected customer.
The worker must not create two charges for the same payment id.

Think first, then reveal.

Answer: The worker must not create two charges for the same payment id adds the invariant. It names a state the system must prevent.

Your Capstone Task

Write one review comment for this change:

Change: enable automatic retries in the checkout worker.
Risk path: timeout -> retry -> duplicate payment request.
Signal: duplicate-payment alert.
Canary plan: start at 5% traffic.
Permission: support may disable the canary for one affected customer.
Hard rule: the worker must not create two charges for the same payment id.
Rollback condition: rollback if duplicate payments appear.
Retrospective note: if the alert fires after a traffic increase, the team should have held the canary.

Your comment should be five to seven sentences.

It must include:

• one capability sentence with can;
• one uncertainty sentence with might or may;
• one possible consequence with could;
• one recommendation with should;
• one permission sentence with may or can;
• one hard requirement or prohibition with must or must not;
• one rollback condition with must;
• one retrospective sentence with should have or would have.

You do not have to use every modal in a separate sentence. You may combine related ideas if the jobs stay clear.

Model Answer and Rubric

Model answer:

The new checkout worker can retry payment requests after a timeout.
If the provider accepted the first request but the response was lost, the worker might retry and could submit the same payment twice.
We should keep the canary at 5% until duplicate-payment alerts stay quiet for one hour.
Support may disable the canary for one affected customer if checkout errors affect that customer.
The worker must not create two charges for the same payment id.
If duplicate payments appear, we must roll back before increasing traffic.
If the alert fires after a traffic increase, we should have held the canary and reviewed the retry guardrail first.

Rubric:

Use the rubric to revise your own answer.

Trade-offs and Limits

Calibrated modal verbs improve risky-change advice because they make commitment visible. The reader can see what is possible, what is recommended, what is allowed, and what is required.

The trade-off is that the writer must slow down. A precise comment takes a little more thought than a vague warning.

This does not replace the engineering review. If the risk path is wrong, precise English will not make the design safe. It will only make the wrong assumption easier to inspect.

It also does not mean every comment must be long. When the risk is small, one or two calibrated sentences may be enough.

There is another limit: modal precision cannot decide the risk appetite for the team. The words can show that rollback is required if duplicate payments appear. They cannot decide whether a 5% canary is acceptable, whether one hour is enough evidence, or whether the payment provider's behavior is well understood.

Those are engineering decisions. Clear English makes them easier to review.

You can see the boundary when a teammate asks:

Is rollback recommended, allowed, or required?

If your comment cannot answer that question, the modal force needs another pass.

Confusion: can and could are interchangeable

Why it is tempting:

Both words often translate to similar words in Spanish, and both can appear in possible-change comments.

Better model:

Use can when you mean capability or permission. Use could when you mean a possible consequence or softer option.

The worker can retry requests.
The retry could submit the same payment twice.

Confusion: must makes advice more professional

Why it is tempting:

Production risk feels serious, so strong language feels responsible.

Better model:

Use must only when the action is a hard rule, invariant, policy, blocker, or rollback condition. For a recommended control, should is often clearer.

Confusion: Retrospective modals are only for blame

Why it is tempting:

Should have can sound like an accusation after an incident.

Better model:

Use retrospective modals to connect evidence to prevention.

We should have held the canary after the first duplicate-payment alert.

That sentence is useful when it points to a future rule:

Next time, the canary must stop when that alert fires.

Practice: Transfer to a New Risk

Now transfer the same structure to a cache change.

Rough facts:

Change: cache product prices for five minutes.
Risk path: refresh failure -> stale price -> wrong checkout total.
Signal: price-age metric above five minutes.
Permission: support may disable the cache for one affected merchant.
Hard rule: checkout must not charge a customer using a stale total.
Rollback condition: rollback if stale prices affect checkout totals.

Write a four to six sentence review comment.

Model answer:

The pricing service can cache product prices for five minutes.
If the refresh job fails, the cache might serve an old price and could show the wrong checkout total.
We should alert when cached prices are older than five minutes.
Support may disable the cache for one affected merchant while the team investigates.
Checkout must not charge a customer using a stale total.
If stale prices affect checkout totals, we must roll back the cache change.

Why this answer transfers:

The grammar pattern is the same, but the technical nouns changed.

In the checkout-worker case, the risky action was a retry. In the cache case, the risky action is serving stale data. The modal jobs stay stable:

This is the final skill, not the payment scenario itself. A learner who can move the pattern from retries to caches can use the track outside the lesson examples.

One more revision check:

The cache can be bad, so we must maybe disable it.

That sentence repeats the old problem. It is short, but the reader cannot tell whether disablement is allowed, recommended, or required. The model answer fixes that by giving support permission and giving the team a separate rollback condition.

Daily Practice Lines:

• The worker might retry after a timeout and could submit the same payment twice.
• We should keep the canary at 5% until duplicate-payment alerts stay quiet.
• If duplicate payments appear, we must roll back before increasing traffic.

Resources

• [ARTICLE] Cambridge Dictionary Grammar: Modals and modality
  • Focus: Compare modal meanings for possibility, obligation, permission, and advice.
• [ARTICLE] Microsoft Writing Style Guide: Be clear and concise
  • Focus: Keep technical advice direct and easy to scan.
• [REFERENCE] Google API Improvement Proposals: AIP-155 Request Identification
  • Focus: See why repeated requests need visible identifiers and clear API rules.

Key Takeaways

• A risky-change comment should separate capability, uncertainty, consequence, recommendation, permission, requirement, rollback, and retrospective judgment.
• Use might and could for uncertain risk paths, should for recommended controls, and must for hard rules.
• Permission is not the same as recommendation or requirement.
• Retrospective modals are useful when they connect a missed action to a future guardrail.
• The final test is practical: a teammate should be able to tell what can happen, what should happen next, and what must happen if the risk becomes real.