Capstone: Explain a Bug from Symptom to Fix

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

• Explain a small production bug with a clear timeline from symptom to fix.

• Combine present, past, perfect, passive, reported, and conditional forms without overclaiming.

• Write a short incident-style update that separates evidence, action, uncertainty, and next steps.

Idea in one sentence: A good bug explanation does not show every grammar form you know; it chooses the time frame that helps the reader understand what happened, what is true now, and what depends on the next signal.

Core Insight

This capstone closes the track by using one realistic engineering story.

The central practice line is:

The queue had been growing before the worker pool crashed.

That line matters because it does two jobs at once. had been growing shows a process that started earlier and continued up to a later past event. crashed gives the later event. The sentence does not prove the cause of the crash. It only gives a careful time relation.

That distinction is the heart of technical English for incidents.

In this track, you have practiced many small forms:

The service owns the retry policy.
I am testing the rollout.
The gateway rejected the request.
Errors have returned to baseline.
Users were failing checkout after we had changed the payment flow.
The team said the cache was warming up.
If metrics stay stable, we will expand the rollout tomorrow.

The capstone asks you to stop seeing those as separate grammar topics. They are tools for answering reader questions.

The reader of a bug explanation is usually asking:

• What was the symptom?
• What was happening before the failure?
• What did the team do?
• What evidence do we have now?
• What is still unknown?
• What happens next if the system stays stable?

Each question needs a different sentence job. The trade-off is precision versus speed. You can write a rough update quickly, but if the time frame is wrong, the reader may think the root cause is confirmed, the fix is permanent, or the rollout is guaranteed. A few extra seconds choosing the verb form can prevent that confusion.

The Capstone Scenario

Imagine a small export system.

Users request data exports from the API. The API puts jobs in a queue. A worker pool reads from the queue and writes export files. A dashboard shows queue depth, worker restarts, error rate, and export latency.

At 09:20, support reports that users are waiting too long for exports. The on-call engineer checks the dashboard. Queue depth is high. Worker restarts increased around the same time. The team pauses scheduled exports, restarts the worker pool, and watches the metrics.

After the restart, export latency returns to normal. Queue depth falls. User impact is gone. However, the team does not yet know why the worker pool crashed. Logs suggest memory pressure, but the root cause is still under review.

You need to write a short update for the team channel.

This is not a grammar exam. It is a communication task. The reader needs a reliable timeline and a safe current status.

The Rough Explanation

A rough update might look like this:

Exports were slow. The queue was growing. Workers crashed. We restarted it. It is fixed. We will turn exports on tomorrow.

This is understandable, but it has several risks.

Exports were slow is useful, but it does not show whether the symptom is still happening. The queue was growing is also useful, but it does not show whether that growth happened before the crash or after the crash. Workers crashed names an event, but the plural may be unclear if there is one worker pool. We restarted it has an unclear object. It is fixed overclaims. User impact may be mitigated, but the root cause may still be unknown. We will turn exports on tomorrow sounds like a promise, even if the decision should depend on metrics.

The rough version is not bad because it is simple. Simplicity is good. It is weak because the sentence jobs are blurry.

A better update keeps the sentences short but assigns each one a clear role.

The Worked Explanation

Here is a stronger version:

Users were waiting longer for exports after the queue had been growing for several minutes. The worker pool crashed at 09:20, and the on-call engineer restarted it. Export latency has returned to normal, and scheduled exports are still paused. The root cause is under review. If queue depth stays normal overnight, we will re-enable scheduled exports tomorrow.

This version uses the track's main patterns together.

Users were waiting longer for exports uses past continuous. It describes the symptom window, not just one isolated event.

after the queue had been growing for several minutes uses a perfect form in a past timeline. It shows that queue growth began before the crash. This is similar to the central line:

The queue had been growing before the worker pool crashed.

The worker pool crashed at 09:20 uses past simple. The crash is a finished event at a known time.

the on-call engineer restarted it uses active voice. It says who acted and what they did.

Export latency has returned to normal uses present perfect. The return happened before now, and the result matters now.

scheduled exports are still paused uses passive voice for the current system state. The sentence does not need the actor. The important fact is the state.

The root cause is under review uses present simple for a current status. It avoids saying the root cause is known.

If queue depth stays normal overnight, we will re-enable scheduled exports tomorrow uses a conditional. It makes the next action depend on a signal.

Notice what this update does not do. It does not say that queue growth caused the crash. It does not say the issue is permanently fixed. It does not promise tomorrow's action unconditionally. It gives the reader enough to understand the path from symptom to mitigation.

A Five-Part Explanation Frame

Use this frame when you explain a bug in English.

1. Name the Symptom

Start with what users, operators, or systems experienced.

Useful forms:

Users were waiting longer for exports.
The API was returning 500 errors.
The checkout page was timing out.

Past continuous is useful because incidents often have a symptom window. The issue was happening for a period, not just at one instant.

Avoid beginning with a suspected cause if the reader first needs impact.

Less helpful:

The worker memory problem happened.

Better:

Users were waiting longer for exports while the queue was growing.

The better version starts from visible impact.

2. Place the Earlier Signal

Next, explain what had already been happening before the failure or mitigation.

Useful forms:

The queue had been growing before the worker pool crashed.
The error rate had increased before the alert fired.
The cache had been warming up when the rollout started.

This kind of sentence is powerful, so use it carefully. It shows order. It does not prove cause.

If you are not sure about cause, add a limit:

The queue had been growing before the worker pool crashed, but the root cause is still under review.

That sentence is not weak. It is honest. In engineering communication, honest uncertainty is often more useful than confident guessing.

3. Say What the Team Did

Use past simple and active voice for completed actions.

Useful forms:

The on-call engineer restarted the worker pool.
The release owner paused the rollout.
The team reverted the configuration change.

Active voice is good when ownership matters. It helps the reader know whether the action already happened and who performed it.

Passive voice is still useful when the actor is not important:

Scheduled exports were paused at 09:25.

The choice depends on the reader's need. If the reader needs accountability, prefer active voice. If the reader needs current or historical system state, passive voice may be clearer.

4. Report the Current Evidence

After the action, say what is true now.

Useful forms:

Export latency has returned to normal.
Queue depth has dropped below the alert threshold.
No new worker crashes have occurred since the restart.

Present perfect is useful here because it connects past action to current evidence. The restart happened earlier. The evidence matters now.

Do not turn evidence into a stronger claim than it supports.

Risky:

The issue is fixed.

Safer:

We have mitigated the issue, but the root cause is still under review.

This sentence separates user impact from root-cause certainty.

5. State the Limit and Next Step

Finish by telling the reader what remains uncertain and what will happen under a condition.

Useful forms:

The root cause is still under review.
If queue depth stays normal overnight, we will re-enable scheduled exports tomorrow.
If worker restarts increase again, we will keep scheduled exports paused.

This is where conditionals are especially useful. A conditional sentence prevents overpromising. It says the plan is tied to evidence.

The reader can trust an update more when it names the decision rule.

Capstone Rubric

Use this rubric to judge your own final update.

A strong bug explanation includes a visible user or system symptom. The reader should understand what was going wrong before they read about internal causes. If the first sentence jumps directly to a component, ask whether impact is missing.

A strong explanation places earlier signals carefully. If queue growth, error rate, or deploy timing happened before another event, use a form such as had grown, had increased, or had been growing. Do not use that form to imply certainty about cause unless you have evidence.

A strong explanation reports completed actions with simple, direct verbs. The on-call engineer restarted the worker pool is clearer than A restart was made when ownership matters. Use passive voice only when the state is more important than the actor.

A strong explanation separates mitigation from root cause. Export latency has returned to normal is evidence. The root cause is under review is a limit. Together, they give a calm current status without claiming too much.

A strong explanation makes the next step conditional when the next step depends on metrics. If queue depth stays normal, we will re-enable scheduled exports tomorrow is safer than We will re-enable scheduled exports tomorrow when the team still needs overnight stability.

A weak explanation is often not grammatically terrible. It is weak because it makes the reader infer too much. The capstone goal is not fancy English. The goal is reliable English.

What to Leave Out

A bug explanation also improves when you leave out details that do not change the reader's next decision.

For example, the team channel probably does not need every log line, every restart count, or every internal guess from the first five minutes. Those details may belong in a post-incident note later. In the first update, the reader needs impact, current safety, and the decision rule.

This is why grammar and editing work together. A clear time frame helps you decide what each sentence is doing. If a sentence does not name a symptom, earlier signal, action, current result, current limit, or next condition, remove it or move it to a deeper follow-up.

The final update should feel calm because it is selective.

Common Confusions

Confusion: More Tenses Mean Better English

It is tempting to use many forms because this is the end of a tense track.

Better model:

Use only the forms that answer reader questions.

This update is short and strong:

The worker pool crashed at 09:20. Export latency has returned to normal after the restart. The root cause is still under review.

It does not use every form in the track, but each sentence has a clear job.

Confusion: A Timeline Is the Same as a Cause

If the queue grew before the crash, the queue growth may be important. But time order alone is not proof.

Careful:

The queue had been growing before the worker pool crashed.

Too strong:

The queue growth caused the worker pool to crash.

Use the stronger version only when you have evidence.

Confusion: Mitigated Means Permanently Fixed

In production updates, mitigated usually means user impact is reduced or gone. It does not always mean the underlying defect is removed.

Careful:

We have mitigated the issue, but the root cause is still under review.

Too strong:

We fixed everything.

The careful version may feel less satisfying, but it is more trustworthy.

Confusion: Will Is Always a Promise

Will can express a decision or prediction, but in engineering updates the reader may hear it as a commitment.

When the action depends on a signal, use a condition:

If metrics stay stable, we will expand the rollout tomorrow.

That sentence still gives a plan. It also gives the rule for changing the plan.

Check Your Understanding

Check: Which sentence best explains an earlier signal without proving root cause?

A. The queue had been growing before the worker pool crashed.
B. The queue made the crash because it was bad.
C. The crash is tomorrow because queue grows.

Think first, then reveal.

Answer: A. It gives a careful time relation. It does not overclaim cause.

Check: Which sentence gives current evidence without saying the root cause is solved?

A. Export latency has returned to normal, but the root cause is still under review.
B. Everything is fixed forever.
C. Root cause was probably solved by something.

Think first, then reveal.

Answer: A. It separates current recovery evidence from root-cause certainty.

Check: Which sentence makes the next action depend on a metric?

A. If queue depth stays normal overnight, we will re-enable scheduled exports tomorrow.
B. We will re-enable scheduled exports tomorrow no matter what.
C. Scheduled exports tomorrow because maybe queue.

Think first, then reveal.

Answer: A. It uses a conditional to avoid overpromising.

Capstone Practice

Rewrite this rough update:

Exports slow. Queue grew. Worker crashed. Restart done. Looks okay. Tomorrow enable scheduled exports.

Use the five-part frame:

• symptom
• earlier signal
• action
• current evidence
• limit and next step

Model answer:

Users were waiting longer for exports after the queue had been growing for several minutes. The worker pool crashed at 09:20, and the on-call engineer restarted it. Export latency has returned to normal, but the root cause is still under review. If queue depth stays normal overnight, we will re-enable scheduled exports tomorrow.

Now inspect the model.

The first sentence gives impact. The reader knows users were affected. The same sentence also places the queue growth before the crash, but it does not say the queue caused the crash.

The second sentence gives the finished event and the completed action. crashed and restarted are past simple because both events are finished.

The third sentence gives current evidence and current uncertainty. has returned connects the recovery to now. is still under review prevents overclaiming.

The final sentence gives the next action as a condition. The team has a plan, but the plan depends on stability.

If your own answer has those four jobs, it is good even if the wording is not identical.

Daily Practice Lines

Repeat these three lines during the day:

The queue had been growing before the worker pool crashed.
We have mitigated the issue, but the root cause is still under review.
If metrics stay stable, we will expand the rollout tomorrow.

The first line reviews timeline order.

The second line reviews evidence and uncertainty.

The third line reviews conditional planning.

Together, they are a small version of the full capstone.

Resources

• [ARTICLE] Cambridge Dictionary Grammar: Past perfect continuous - Use it to review actions that continued up to a past event.
• [ARTICLE] Cambridge Dictionary Grammar: Present perfect - Use it to review evidence and results connected to now.
• [ARTICLE] Cambridge Dictionary Grammar: Conditionals - Use it to review conditional next actions.
• [ARTICLE] Microsoft Writing Style Guide - Use it as a reference for direct, reader-centered technical updates.

Key Takeaways

• Start from the reader's question, not from the grammar name.
• Use past continuous for symptom windows and past simple for finished events.
• Use perfect forms to connect earlier signals or current evidence to the reader's timeline.
• Use active voice when ownership matters and passive voice when state matters more than actor.
• Separate mitigation from root cause so the update does not overclaim.
• Use conditionals when the next engineering action depends on a metric or signal.