Recently, in the translation workflow for Go Learning & Documentation v2, I encountered a very confusing situation.
After an independent Reviewer reviewed a complete page, they gave it a B.
The finding also explicitly listed several issues.
Generation modified the text item by item according to these issues.
Machine validation passed.
Then it entered successor re-QC.
As a result, the Reviewer gave another:
B.
Moreover, the issues pointed out in this new round were actually the same type of problem as in the previous round.
When first seeing this result, it’s easy to suspect:
Did Generation not carefully revise according to the finding?
But after further breakdown, I found that the real problem isn’t necessarily “no revision was made.”
The more common situation is actually the opposite:
The Reviewer only listed a few representative examples, and Generation mistakenly treated these examples as the complete revision boundary.
This ultimately formed a cycle:
First independent review gives a B
→ Reviewer lists several examples
→ Generation fixes these examples
→ successor re-QC
→ Same category still has residuals
→ B given againThis kind of issue later prompted me to re-clarify the boundaries between Reviewer findings and Generation exact revisions.
It ultimately led to a principle that now seems very important:
finding-anchored does not mean example-anchored.
That is to say:
A revision must be authorized by a formal finding, but the few examples given by the Reviewer do not automatically equal the full scope of this category of problems.
This article is specifically dedicated to sorting out this issue.
The initial problem: The Reviewer discovered a “category” but only wrote down “examples”
Assume that in a Chinese page, there is a recurring spacing issue between a certain type of inline Go API identifier and the surrounding Chinese body text.
There are actually 8 occurrences in the complete page.
The Reviewer saw 3 of them while reading, so they wrote in the finding:
Some inline API identifiers are stuck to the Chinese body text, such as A, B, and C. Please fix.
From a human reading perspective, this finding is very natural.
Because “such as” already expresses:
I am giving examples.
But for an exact revision workflow, it has a big problem:
Exactly how much is authorized to be fixed?
Generation might have two interpretations.
The first interpretation is:
The A, B, and C listed by the Reviewer are the entire formal authorized scope, so I can only fix these 3 occurrences.
The second interpretation is:
The Reviewer has identified a recurring defect category, and A, B, and C are just evidence. I should continue checking for same-class instances within the current TranslationUnit.
If the contract doesn’t make this clear, both interpretations seem somewhat reasonable.
And what a formal workflow fears most is:
Relying on guessing.
“For example” is natural for humans, but dangerous for machine workflows
In natural language reviews, it’s common to write:
For example…
Like…
Etc.
This way of writing isn’t a big problem for ordinary human collaboration.
Because the receiver will usually understand on their own:
This is a category, please handle similar situations together.
But v2’s exact revision is not ordinary editing.
It has a very important restriction:
Generation is not allowed to use a finding as an excuse to expand into free polishing of the entire page.
That is, Generation cannot see:
A punctuation issue somewhere.
And then take the opportunity to modify:
- Other word orders;
- Sentences they feel aren’t natural enough;
- Terminology not authorized by the Reviewer;
- Unrelated punctuation;
- Other style preferences.
So the workflow has always emphasized:
finding-anchored.
The problem also happens to lie right here.
If finding-anchored is understood as:
Only modifying the few instances listed verbatim in the finding is allowed.
Then recurring issues are easily missed.
If it is understood as:
As long as it feels similar, you can freely change the whole page.
It will cause scope expansion.
So there must be a more accurate concept in between:
defect category + bounded scope.
What the Reviewer should really submit isn’t just a few examples
Later, the formal rules became clearer.
When a Reviewer makes a fresh judgment on a complete current TranslationUnit, once they decide to give a B, C, or D, and have already identified a certain defect category, they cannot just stop after seeing two or three examples.
Instead, they should:
Perform a same-class scan for this category within the current complete TranslationUnit.
Here, same-class can be understood as:
A complete scan of the same defect category.
It does not require absolute exhaustion in a mathematical sense.
But at the very least, it cannot:
Clearly see that this is a recurring pattern, yet only write down two representative examples and leave the remaining instances for the next round’s Reviewer to find.
For example, if it has been determined that the problem category is:
In the current Page, there is improper sticking between inline Go API identifiers and adjacent Chinese body text that does not conform to Chinese typographic conventions.
Then the Reviewer should subsequently check:
Whether there are any other locations in the current complete Page that also satisfy this predicate.
If there are only 4 occurrences, try to list all 4.
If there are dozens, and it’s not suitable to list them all one by one, at least provide:
A sufficiently precise predicate, plus a clear bounded scope.
A finding should describe the “problem category”, not just “this is wrong here”
I increasingly feel that the core of a high-quality finding is not the number of examples.
Rather, it’s being able to answer four questions.
First:
What is the Finding category?
That is, exactly what type of problem it is.
Second:
What are the Observed instances?
Which actual instances have been observed, and where they are.
Third:
Where does the Revision scope end?
Within what scope is Generation allowed to perform a complete scan of the same class.
Fourth:
What is Out of scope?
What things explicitly cannot be modified along the way.
For example, a relatively clear finding can be expressed as:
Problem category:
In the current Page, there is the same kind of improper sticking between inline Go API identifiers and adjacent Chinese body text.
Observed instances:
List the instances already found, and provide stable paragraph, section, or adjacent text positioning.
Revision scope:
Within the current complete Page, perform a complete scan and fix only for the above same category.
Out of scope:
Other wording preferences, general polishing, other punctuation categories, terminology adjustments, and all protected content.This way, Generation truly knows:
What I should continue looking for.
And:
What I absolutely should not modify along the way.
examples are evidence, not by default the complete revision boundary
This is a rule I later felt was the most crucial.
The examples provided by the Reviewer are, first and foremost:
finding evidence.
They prove:
This problem actually exists.
But they do not implicitly mean:
Only these specific locations can be modified.
Only if the Reviewer explicitly states:
This is an exact-instance-only finding.
Should Generation strictly limit itself to the listed examples.
Otherwise, for recurring problems that have already been clearly defined with a:
- defect category;
- predicate;
- bounded scope;
Generation still needs to continue performing a:
same-class complete sweep.
That is:
Within the same current TranslationUnit, the same problem category, and the same authorized scope, handle other instances that clearly belong to the same predicate together.
finding-anchored does not mean only fixing the literal examples in the finding
This is also the most easily misunderstood part on Generation’s side.
The project has always emphasized:
exact revision must be finding-anchored.
There is no problem with this rule.
Because without finding constraints, Generation easily degrades into:
“Since I’ve already opened this Page, I might as well re-polish the whole page.”
This would destroy:
- Reviewer authorization boundaries;
- candidate identity;
- revision provenance;
- the stability of unaffected content.
So it must be maintained:
finding-anchored.
But its true meaning should be:
All modifications must be traceable back to the defect category and authorized scope of the persisted finding.
Rather than:
Only modifying the few examples listed verbatim in the finding prose is allowed.
The difference between these two interpretations is huge.
locally complete also doesn’t mean “fixing this one sentence completely”
There is another easily misunderstood term:
locally complete.
Previously, it was easy to understand it as:
Find this location, and fix this sentence completely.
Later I realized that this wasn’t enough.
In recurring findings, what locally complete should really express is:
Completely closing the same category of problem within the authorized local scope.
Here, “local” restricts the:
scope.
Not the:
instance count.
For example, if the Reviewer’s finding scope is:
Inline identifier spacing throughout the current Page.
Then local is:
The current Page.
Generation cannot expand to other Pages.
But within this Page, if there are 8 instances belonging to the same predicate, they shouldn’t only fix 3 of them.
Why “only fixing examples” looks safe but actually creates re-QC loops
From Generation’s perspective, only fixing the instances explicitly listed by the Reviewer is actually very conservative.
Because it maximally avoids:
scope expansion.
But the side effect is:
Mistakenly treating the Reviewer’s examples as an exhaustive list.
So after the first revision:
Reviewer explicitly listed instances: 3
Generation fixed instances: 3
Actual same-class instances on the page: 8
Remaining residuals: 5Machine validation might still completely PASS.
Because:
Machine validators usually only verify structure, protected content, identity, schema, and formal mechanical semantics.
It will not judge on behalf of the Reviewer:
Whether the same problem still exists in the Chinese typography of the other 5 occurrences.
So ultimately, it can only wait for successor re-QC to find it again.
Machine validation PASS cannot close a language finding
This is also a very important misconception in this cycle.
After the revision is completed, if you see:
validation：PASSIt easily creates a mindset:
The revision should be complete.
In reality, validation can only prove:
This replacement is legal under the machine contract.
For example:
- No protected token was lost;
- Source identity remained unchanged;
- The structure is valid;
- The output format is correct;
- No prohibited technical content was modified.
It cannot prove:
The language category pointed out by the Reviewer has been completely closed.
Therefore:
machine validation PASS ≠ finding closure PASS.
This is also why an independent successor re-QC must continue to exist.
Generation should also perform a finding closure check before submitting
To reduce these obvious round-trips, Generation later also needed to take on a task completion check.
Note, this is not self-review.
Generation cannot give itself an A.
Nor can it say:
I think the translation quality has passed.
What it should do is more mechanical:
finding closure check.
That is, before submitting the replacement, confirm:
- Whether all explicitly listed instances have been handled;
- Whether the persisted finding category has been understood;
- Whether there are still obvious same-class residuals within the bounded scope;
- Whether other content outside the finding was accidentally modified;
- Whether protected content remains unchanged;
- If the category or scope is unclear, whether to stop and report ambiguity.
This is a:
Task completion check.
Not a:
Formal language quality review.
The final rating can still only be given by an independent Reviewer.
A same-class sweep also cannot turn into “polishing the whole text along the way”
After the rules were tightened, another risk immediately emerged.
Generation might think:
Since a same-class scan is required, I’ll fix all similar problems I see together.
This direction itself isn’t wrong.
But “similar” cannot be infinitely expanded.
For example, if the persisted finding is:
There is the same kind of abnormal space before Chinese punctuation in the current section.
Then the same-class sweep can check:
Whether there are the same abnormal spaces in the currently authorized section.
But it cannot conveniently expand to:
- Another type of punctuation issue;
- Terminology style;
- Heading tone;
- Sentence rewriting;
- Unrelated expressions in other sections.
So same-class completeness needs to simultaneously satisfy three constraints:
Same category.
Same bounded scope.
Same formal Unit / slot authorization.
As long as it exceeds one of these, it no longer belongs to this finding-anchored revision.
You cannot rely on “looks about the same” to determine same-class
This boundary is also very important.
Assume the finding is:
Inline API identifiers are stuck to Chinese body text.
Generation then sees another place with:
No space between an English brand name and the Chinese body text.
These two might look very similar visually.
But whether they belong to the same defect category is not necessarily true.
The former might involve:
- code / identifier formatting;
The latter involves:
- Chinese typographic conventions for brand names.
If it cannot be reliably determined:
Whether this is the same predicate.
Then Generation should not guess.
The correct approach should be:
Keep that location unchanged, and report an ambiguity / blocker.
Because the goal of same-class completeness is:
To completely fix an authorized category of problems.
Not to use this opportunity to expand into new language judgments.
Reviewer’s completeness also cannot turn into endlessly finding problems
The Reviewer side also needs boundaries.
A same-class scan is not:
After giving a B, re-searching the entire page for all possible language problems.
If the Reviewer finds another independent issue during fresh judgment, they can of course record it.
But it should be treated as:
A new defect category.
Rather than mixing it into the original finding.
For example, if the page simultaneously has:
- inline identifier spacing;
- A terminology translation error;
- A semantic omission in a certain table.
These should be three independent categories.
Each category should separately define:
- observed instances;
- predicate;
- bounded scope;
- revision boundary.
It cannot ultimately be written as:
The page still has some language issues, please optimize overall.
Because this kind of finding is almost equivalent to authorizing:
Re-translating the entire page.
This is exactly what exact revision wants to avoid.
successor re-QC also cannot just check old examples
Where this round of rules truly closes the loop is in successor re-QC.
Previously, re-QC easily degraded into:
The Reviewer listed A, B, and C last time.
Now let’s see if A, B, and C have been fixed.
If all were fixed:
PASS.
The problem is, this will still miss same-class residuals.
So successor re-QC must perform a fresh judgment again on:
The complete current TranslationUnit
Especially for persisted findings, it must also check:
Whether this finding category has been completely closed within the original authorized scope.
That is, it not only has to ask:
Were the 3 examples listed last time fixed?
It also has to ask:
Are there a 4th or 5th same-class residual in the current scope?
If there are still residuals, it should be explicitly written as a same-class residual
Assume the previous round’s finding was:
There is an inline identifier spacing issue in the current Page.
Generation fixed most of them.
After re-QC, 1 occurrence is still found.
At this point, the most accurate expression is not:
A new spacing issue was found.
Because it is not a completely new category.
It is a:
same-class residual of the persisted category.
This way the historical chain is clear:
Original finding category
→ revision
→ successor re-QC
→ same-class residualRather than looking like:
Old issue completely closed
→ Reviewer suddenly finds a completely new issueThis is also more accurate for subsequent revision scopes.
Why old findings should not be rewritten
After the rules became more complete, it’s easy to have another impulse:
Since we now know the first finding wasn’t written completely enough, should we change the historical finding?
The answer should be:
No.
Because historical evidence should record:
What the Reviewer actually submitted at that time.
If the later successor re-QC finds residuals, it creates new evidence.
Rather than going back and changing the old evidence to:
“Actually, I had already found all the problems at that time.”
Otherwise, history is no longer trustworthy.
So the correct approach is:
Old finding: Keep unchanged
New re-QC: Record same-class residual
New revision: Continue handling the residualHistory can be imperfect.
But it cannot be rewritten.
Why this rule does not require mathematical exhaustion
Seeing same-class completeness, you might worry:
Must the Reviewer prove that absolutely nothing was missed on the entire page?
Actually, no.
Language judgment is hard to achieve an exhaustive proof in a mathematical sense.
The formal requirement is closer to:
reasonable complete scan.
That is to say:
Once the Reviewer has identified a recurring pattern, they should consciously scan the entire authorized scope, rather than just stopping after casually seeing two.
If there are many instances, you can use:
exact predicate + bounded scope.
Rather than having to write lists of dozens of lines.
What is truly prohibited is:
Knowing full well it is a recurring defect, yet deliberately only giving a few examples, and then leaving the remaining problems for the next round.
A good predicate can be more valuable than dozens of examples
Assume a page has 30 occurrences of the same problem.
Listing 30 instances one by one is certainly doable.
But a more stable finding might be:
All inline Go API identifiers throughout the current Page that should be separated from adjacent body text according to Chinese typographic conventions, but have actually undergone improper sticking.
This already specifies:
- category;
- predicate;
- scope.
Then list a few specific instances as evidence and positioning references.
Generation can then perform a complete sweep within the current Page.
And the Reviewer during successor re-QC also knows:
Which predicate should be verified as closed.
This is much more stable than:
For example A, B, C, etc.
Much more stable.
Why bounded scope must be clear
If there is only a predicate and no scope, problems will also arise.
For example:
Fix all API identifier spacing.
Does “all” here mean:
- The current paragraph;
- The current section;
- The current Page;
- The entire package;
- The entire locale?
None of this is clear.
So the scope must be limited.
For example:
The full text of the current Page.
Or:
The Security Considerations section of the current Page.
Or:
The description column of the current table.
Or:
The currently authorized teaching-comment area.
This way, Generation will not spread across TranslationUnits.
When exact-instance-only should be used
Not all findings are suitable for a same-class sweep.
Sometimes the problem the Reviewer identifies is:
A specific sentence has a one-time semantic error in its translation.
For example, a certain sentence missed a negation relationship.
And the same pattern does not exist elsewhere on the page.
In this case, it is perfectly fine to explicitly specify:
exact-instance-only.
That is:
Only authorizing the modification of this one specific instance.
This way, Generation doesn’t need to search the whole page for a non-existent category just for the sake of “completeness”.
So the key is not:
Every B must expand the scope.
Rather:
Recurring problems should be completely scanned; one-time problems should be explicitly limited.
The roles of Reviewer examples and Generation examples are different
There is another distinction worth making here.
Reviewer examples are:
evidence.
The actual modifications in Generation’s output are:
finding closure.
The two do not have a one-to-one correspondence.
For example, the Reviewer provides 3 examples, but the category + scope clearly covers the current complete Page.
Generation might ultimately modify 7 occurrences.
This does not mean:
Generation expanded the scope without authorization.
As long as the other 4 newly modified occurrences all satisfy:
- The same defect category;
- The same predicate;
- The same bounded scope;
- No crossing of formal authorization;
Then it is still a:
finding-anchored revision.
This is a point I later felt was particularly important:
finding-anchored describes the “causal source of the modifications”, not “the number of modified instances must match the number of finding examples”.
This can significantly reduce meaningless Reviewer round-trips
Without same-class completeness, a recurring problem might turn into:
QC: Finds 3 occurrences
→ revision: Fixes 3 occurrences
→ re-QC: Finds another 2 occurrences
→ revision: Fixes 2 more occurrences
→ re-QC: Finds 1 more occurrenceEach round is real work.
But a lot of the cost is actually not the language problem itself, but rather:
The boundaries of the first finding were not expressed completely enough.
This will additionally consume:
- Generation invocation;
- Reviewer invocation;
- Bundle export;
- validation;
- Snapshot;
- evidence;
- re-QC;
- Manual coordination time.
So completeness is not just a quality issue.
It is also a very direct:
Cost optimization.
But this is still different from “having the Reviewer find all problems at once”
Here we need to specifically avoid going to the other extreme.
same-class completeness does not require the Reviewer to:
Find all possible future problems in the entire TranslationUnit during the first QC.
The Reviewer is still a fresh judgment.
It should try its best to find the problems it currently sees.
The only difference is:
Once a recurring defect category has been identified, don’t deliberately only review a few representative examples.
In other words:
What is required is completeness within the category, not requiring the Reviewer to have precognition.
If a completely new category that was never identified before indeed appears after successor re-QC, then it can still be treated as a new finding.
This set of rules still keeps Reviewer and Generation independent
After adding completeness, the two roles cannot be merged either.
The Reviewer’s responsibility is still:
Judging quality, defining the finding category, evidence, and revision scope.
Generation’s responsibility is still:
Generating the replacement within the formal finding authorization.
Generation can do a same-class complete sweep.
But it cannot:
Give itself an A just because it feels it has fixed things.
The Reviewer can point out the complete category.
But it cannot:
Directly generate a replacement and then approve its own modifications.
Role isolation is still maintained.
machine scope and language scope also cannot be mixed
same-class completeness only solves:
The complete closure of language findings.
It does not change:
- TranslationUnit membership;
- package membership;
- parser slot authorization;
- protected token;
- candidate identity;
- Snapshot;
- machine validation;
- A-only finalization.
For example, the current formal scope only has one Page TranslationUnit.
Even if the Reviewer finds that another Page seems to have a similar problem, they cannot conveniently include the other Page in this round of revision.
That already belongs to:
A new formal affected scope.
It needs to go through its own authority.
This actually exposes a very common problem
Looking back, this is not just a translation workflow problem.
Many engineering collaborations encounter:
The bug reporter gives two examples.
The bug fixer only fixes those two examples.
The tester finds a third one in the next round.
What is truly missing is:
Whether the problem category has been clearly defined.
For example, a parser bug, if only:
fixture A and fixture B are fixed.
Without defining:
What kind of input belongs to the same failure predicate.
Then fixture C will very likely appear in the future.
So same-class completeness is actually a more general engineering habit:
Don’t just fix the samples; understand the defect class behind the samples.
But the defect class must also have boundaries
This statement also cannot be abused.
“Understanding the category” does not mean:
Refactoring the entire system along the way after finding one problem.
This is especially true in translation revisions.
The correct question should be:
Why does this instance belong to the current finding?
Rather than:
Since there’s a problem here, what else looks unpleasant to me?
The former is:
category closure.
The latter is:
scope expansion.
These two must be strictly distinguished.
The Reviewer finding structure I now favor more
If I encounter B/C/D in the future, I will be more inclined to have the finding at least include the following four parts.
The first part states:
Finding category: Specific defect category.
The second part states:
Observed instances: As complete a list of observed instances as possible, or an exact predicate.
The third part states:
Revision scope: The clear scope within the current TranslationUnit where a same-class complete sweep is allowed.
The fourth part states:
Out of scope: Other categories, general polishing, and protected content are explicitly not allowed to be modified.
This does not require adding a new JSON schema.
Nor does it require adding CLI fields.
It can completely continue to exist in the Reviewer’s natural language evidence.
But the precision of expression will be much higher.
Generation also has a corresponding checklist
After receiving the revision Bundle, Generation should first ask:
What is the defect category defined by the Reviewer?
Then ask:
Where does the bounded scope end?
Then ask:
Are the examples evidence, or an explicit exact-instance-only boundary?
If it is not exact-instance-only, continue asking:
Are there any other instances in the currently authorized scope that clearly satisfy the same predicate?
Finally, also ask:
Did I touch other categories, general polishing, or protected content?
If I did:
Don’t modify.
If same-class attribution itself cannot be reliably determined:
Don’t guess.
In this case, reporting an ambiguity is actually more correct than modifying without authorization.
successor re-QC is ultimately responsible for truly closing this chain
After Generation completes the replacement, it ultimately must still return to an independent Reviewer.
The Reviewer cannot just look at:
The originally listed examples have all been changed.
Instead, they should check:
Whether this persisted finding category has been truly closed within the original revision scope in the current complete TranslationUnit.
If all are closed:
Only then can an A be given based on a complete fresh judgment.
If there are still residuals:
Continue giving a B/C/D, and explicitly state that this is a same-class residual.
If a completely new independent problem is found:
Create another category.
This way the entire chain will become:
Reviewer defines defect category and bounded scope
→ Generation completes same-class sweep within the scope
→ machine validation verifies the replacement is legal
→ successor re-QC verifies whether the category is completely closed
→ Only after all pass does it enter A-only finalizationThis is much more stable than:
Reviewer gives a few examples
→ Generation changes a few examples
→ Reviewer finds a few moreMuch more stable.
What this rule change really wants to solve is not “the Reviewer needs to be more careful”
If we simply summarize this matter as:
The Reviewer should look more carefully the first time.
It’s actually not accurate.
Because the real problem is:
The workflow previously did not define the relationship between category, example, and revision boundary clearly enough.
The Reviewer might have thought:
“For example” was enough to express same-class problems.
Generation, due to a fail-closed tendency, might have thought:
Only explicitly listed instances are formally authorized.
Both sides were actually doing what seemed reasonable to each.
Yet ultimately formed a meaningless loop.
So the focus of improvement is not:
Requiring a certain role to be smarter.
Rather:
Writing the handoff contract more precisely.
A good workflow should reduce “relying on tacit understanding”
This is also a principle the entire project has increasingly clarified.
The more formal, recoverable, and cross-session the process, the less it can rely on:
“You should know what I mean.”
Because Reviewer and Generation are inherently two independent sessions.
They might even be executed across different times.
What they truly share should be:
- Bundle;
- persisted finding;
- exact source;
- candidate;
- formal authority.
Rather than:
Implicit tacit understanding.
So the clearer the defect category and bounded scope, the more stable the downstream will be.
The most worthwhile principles to keep this time
After several rounds of B → revision → re-QC repetition, I think the current rules can be condensed into a few points.
First:
Once the Reviewer identifies a recurring defect category, they should perform a reasonable same-class scan within the complete current TranslationUnit.
Second:
Reviewer examples are evidence and do not by default constitute an exhaustive revision boundary.
Third:
When there are too many instances, you can use an exact predicate + bounded scope, rather than leaving an open boundary with “for example” or “etc.”.
Fourth:
Only when the Reviewer explicitly marks it as exact-instance-only should Generation only modify the listed specific instances.
Fifth:
finding-anchored does not mean example-anchored.
Sixth:
locally complete means completely closing the same category within the authorized local scope, not just fixing one local sentence.
Seventh:
Generation should perform a same-class complete sweep within the persisted category + bounded scope, but cannot expand to other categories or general polishing.
Eighth:
When same-class attribution cannot be reliably determined, do not guess; keep the original text and report an ambiguity.
Ninth:
successor re-QC not only checks old examples, but also verifies whether the persisted category is completely closed within the authorized scope.
Tenth:
If there are still same-class residuals, they should be explicitly recorded as same-class residuals, rather than disguised as a completely new problem.
Ultimately, the one sentence I most want to keep now is:
What a revision should truly close is the “problem category”, not just the few examples the Reviewer happened to write down at the time.
This does not mean expanding the revision scope.
Quite the opposite.
It requires us to define the:
Category, scope, and boundary
more precisely.
Only in this way can two things be achieved simultaneously:
Not missing residuals that clearly belong to the same problem.
And:
Not using the name of a finding to rewrite content that originally had no problems.
This is what I now understand as:
finding-anchored, locally complete.