Capstone: Rewrite an Ambiguous Design Review

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

• Map short references to the exact object, claim, group, option, or subset they name.

• Keep a useful pronoun or determiner when its referent is unique, and restore a noun or claim when it is not.

• Rewrite a dense design-review thread so that it stays concise without making the reader guess.

Idea in one sentence: Good technical compression removes repeated words only after the reference map is stable.

Core Insight

Imagine a design review for Notification v2. The team has a client, a gateway, a backend, two rollout options, two log versions, and a batch of failed requests. The participants know the system, but a late reader sees only the message thread.

The writer wants short sentences:

This is simpler, but the other one isolates retries.

Some reached the gateway, and none of them reached it.

Short words are useful only when the reader can answer two questions immediately:

1. What does the word point to?
2. What claim does the word include or exclude?

The track has supplied the tools: it and they for objects and groups, possessives for ownership, reflexives for self-directed behavior, this and that for pointing, one and ones for substitution, another and the other for alternatives, each, every, and all for distribution, both, either, and neither for a pair, and some of them and none of them for subsets. This capstone asks you to select among those tools, not to collect more forms.

The Small Situation: Notification v2

The team is comparing two rollout options:

The review also has two evidence versions:

• Version A changes the gateway contract.
• Version B changes the client retry behavior.

During a canary, ten requests enter the gateway. Six pass authentication. Two of those six are retried. The dashboard reports a healthy status, but neither rollout option has passed the failover test.

The facts are manageable. The language is not, because the discussion moves between options, components, versions, claims, and subsets in a few lines.

The Naive Idea: Repeat Everything or Shorten Everything

There are two tempting repairs.

The first repeats every noun:

The API adapter is simpler. The queue worker isolates retries. The API adapter is healthy. The queue worker is healthy.

This is hard to scan and can make a connected decision sound like unrelated facts.

The second keeps every short word:

This is simpler, and it handles it. Both are healthy, but neither passed it. Some reached it, and none of them reached it.

This is shorter, but the reader must guess whether this means the API adapter, the design, or the change; whether it means the client or a request; and whether neither describes options or services.

The capstone target sits between those extremes:

Keep a short form when it has one plausible referent. Restore the noun, qualifier, or claim at the first point where two referents compete.

Capstone Method: Name, Map, Compress, Check

Use four passes.

1. Name the sets and pairs

Before using both, either, neither, some of them, or none of them, state the pair or parent group:

The API adapter and the queue worker are the two rollout options.

Ten requests entered the gateway.

This gives later short forms a stable address.

2. Map each short form

For every it, they, this, that, one, other, each, or them, write the full noun or claim in the margin. If two full phrases fit, the short form is not ready.

3. Compress one repetition at a time

Replace only a noun phrase whose referent remains unique. Then read the sentence with the previous sentence included. A pronoun can be clear locally and ambiguous across the paragraph.

4. Check the decision and the evidence

Confirm that determiners still express the intended scope:

• both includes the two options;
• either leaves one option open;
• neither rejects both for a stated condition;
• each inspects members separately;
• every states complete coverage;
• all describes the group;
• some of them and none of them stay inside a named parent set.

The Ambiguous Review Thread

Read this message thread as a late reader would. Do not repair it yet.

Mara, design: We have the API adapter and the queue worker. This is simpler, but the other one isolates retries.

Leo, platform: The gateway sends the request to the API. It stores it, and the queue also receives it.

Mara, design: Both are healthy in v2, but neither passed the failover test.

Leo, platform: Ten requests entered the gateway. Some passed authentication, two were logged, and none of them reached the backend after it timed out.

Mara, design: I compared version A and version B. The latter changed the client, and the former changed the gateway. This is safer.

Leo, platform: Each service has its own log, and all report it to the dashboard. One is cheaper, but the other one is safer. We can deploy either.

The thread contains real information, but several references are unstable:

• This could be the API adapter or the whole choice.
• It could be the request, the API, or the gateway’s record.
• Both could mean the two rollout options or two services.
• None of them might refer to ten requests, authenticated requests, or logged requests.
• It in “after it timed out” has no safe owner.
• This in “This is safer” could name Version B or the client change.
• All does not say which services report the dashboard claim.
• One and the other one are a pair, but the pair is not repeated near the final sentence.

Build the Reference Map

Start by listing the active referents. A map makes the repair mechanical rather than intuitive.

The map reveals that the draft needs a few nouns restored. It does not need every noun restored.

Worked Rewrite: Make the Chain Inspectable

Here is a revised version of the thread:

Mara, design: The API adapter and the queue worker are the two rollout options. The API adapter is simpler for the client; the queue worker isolates retries.

Leo, platform: In the API-adapter path, the gateway sends each accepted request to the notification API. The notification API stores its request record. In the queue-worker path, the gateway writes each accepted request to the queue, and the queue worker stores its own record.

Mara, design: Both rollout options are healthy in the v2 canary, but neither option has passed the failover test.

Leo, platform: Ten requests entered the gateway. Six of the requests passed authentication, and two of those six were logged for retry. None of the two logged requests reached the backend after the queue worker timed out.

Mara, design: Version A changed the gateway contract, while Version B changed the client retry behavior. Version B is safer for the client because it limits duplicate retries, but the claim still needs a failover test.

Leo, platform: Each service keeps its own operational log. The gateway, notification API, and queue worker all report their health to the dashboard. The API adapter is cheaper to run, while the queue worker is safer during retry bursts. Either option can be deployed after the failover test, but neither option should be deployed before it.

This rewrite is longer than the original, but it is still compressed. It uses short forms where the map has one answer:

• each accepted request makes the member-by-member path visible.
• its request record has a unique owner in the previous clause.
• both rollout options and neither option keep the pair explicit.
• those six and the two logged requests preserve the subset chain.
• their health has a clear plural subject: the three named services.
• either option is safe because the pair was named at the start.
• the final it refers to the failover test, not to an option or service, because the noun phrase appears immediately before it.

Trace the worked path

The rewrite follows a visible path:

1. Input: two named rollout options, three named services, and ten requests.
2. Transition: the gateway filters ten requests to six authenticated requests, then to two retry-log entries.
3. Intermediate state: both options pass the v2 health check, but neither passes failover.
4. Decision: either option may deploy after the missing test; neither may deploy before it.
5. Naive failure contrast: “Both are healthy, but neither passed it” hides whether both names options or services and what it names.

The language mirrors the engineering state. The reader can follow the objects and claims without holding a second hidden map.

What Changed, Form by Form

Objects and claims: it, they, this, and that

Use it only after one object or claim is salient. Use they for a clearly plural group. Use this or that when the distance or contrast matters, but attach the noun when two choices are nearby:

This option changes the client; the other option changes the API.

The rewrite prefers the nouns in the first pass because the design review contains several possible objects.

Ownership and self-directed behavior

The phrase its request record makes ownership explicit: the notification API stores the record belonging to that API path. If the review said “the worker retries itself,” itself would show that the worker is the actor and target. Do not use a reflexive form merely to avoid repeating a noun.

Demonstratives and substitution

This can point to a nearby proposal; that can point to a previous claim or a more distant result. One and ones can replace a repeated countable noun when the modifier remains clear:

The API adapter is cheaper; the safer one is the queue worker.

In the capstone rewrite, repeating API adapter and queue worker is better at the first mention because the pair is carrying the decision.

Alternatives and distribution

Both, either, and neither require a known pair. Each, every, and all require the writer to choose member-level, coverage, or group-level scope. The rewrite uses each accepted request for the gateway action and all report for a group health statement.

Subsets

The chain “ten requests → six authenticated requests → two logged requests” makes those six and the two logged requests safe. If another request group appeared between those sentences, the nouns would need to return.

Active Checks

Check: Which repair gives “Both are healthy, but neither passed it” a unique scope?

A. Both services are healthy, but neither option passed the failover test.

B. Both are healthy, but neither passed the test.

C. Both options are healthy, but neither passed it.

Think first, then reveal.

Answer: A. It names both the group being reported and the pair being rejected, and it states the condition instead of leaving it unresolved.

Check: Which continuation preserves the 10 → 6 → 2 request chain?

A. Ten requests entered. Six passed, two were logged, and none reached it.

B. Ten requests entered the gateway. Six of the requests passed authentication, and two of those six were logged. None of the two logged requests reached the backend.

C. Ten entered the gateway. Some passed, and none of them reached it.

Think first, then reveal.

Answer: B. Every subset has an explicit parent, and the backend identifies the destination.

Trade-offs and Limits

Controlled compression makes a design review shorter and easier to scan. It prevents a reader from treating one request subset as the whole batch, one option as the whole pair, or one version’s claim as the other version’s evidence. It also keeps repeated nouns from burying the decision.

The cost is deliberate repetition at boundaries. Restoring the two logged requests or the failover test adds words. A writer must also maintain a reference map while editing; a sentence that is clear today can become ambiguous after a new option or log line is inserted.

The trade-off is scanability versus explicit scope: fewer repeated nouns make the decision easier to scan, while a restored noun makes the ownership or evidence boundary harder to misread.

The method does not repair a missing engineering definition. A perfectly clear sentence can still report a stale health signal, an incomplete canary, or a failover test that covers only one path. The signal to watch is a technical reader asking “Which one?” or “Which requests?” If the answer is not visible in the sentence or the previous line, restore the noun or claim before publishing.

Transfer Practice: A Second Review

Rewrite this shorter review using the same method. Keep it concise, but make every reference resolvable.

We have the old client and the new client. This sends to the gateway, and that sends to the API. Both changed it, but neither is ready. Eight requests entered, four passed, and some of them were retried. None reached it. One is faster, but the other is safer, so we can use either after they check it.

Assume these facts:

• the new client sends requests to the gateway;
• the old client sends requests directly to the API;
• both clients changed the request header;
• neither client passed the compatibility test;
• eight requests entered the gateway path, four passed authentication, and two of those four were retried;
• none of the two retried requests reached the backend;
• the new client is faster, the old client is safer, and either client may be selected after the compatibility test.

A model answer is:

The old client sends requests directly to the API, while the new client sends requests to the gateway. Both clients changed the request header, but neither client passed the compatibility test. In the gateway path, eight requests entered the gateway; four passed authentication, and two of those four were retried. None of the two retried requests reached the backend. The new client is faster, while the old client is safer, so either client can be selected after the compatibility test.

Use this rubric to evaluate your version:

The capstone is complete when another engineer can reconstruct the same object-and-claim map without asking you to explain the pronouns.

Resources

• [ARTICLE] Cambridge Dictionary: Pronouns — Focus: reference, substitution, and personal pronoun forms.
• [ARTICLE] Cambridge Dictionary: Determiners — Focus: scope, alternatives, distribution, and quantity links.
• [ARTICLE] Microsoft Writing Style Guide: Voice and tone — Focus: concise technical explanations that keep claims and referents visible.

Key Takeaways

• Name the object, claim, pair, or parent group before compressing it.
• Keep a short form only while its referent is unique to a late reader.
• Use determiners to preserve scope: member, coverage, group, pair, or subset.
• Restore nouns at boundaries where a new option, version, service, or subset appears.
• Clear technical English is not the shortest possible text; it is the shortest text that preserves the decision and evidence map.