Back to Details

scoping-changes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scoping changes

范围变更管理

REQUIRED BACKGROUND: the 
principal-engineering
skill.
必备背景知识： the 
principal-engineering
skill.

Overview

概述

Scope fails in both directions: gold-plating grows a fix past its trigger, and silent descoping shrinks an approved task below what was agreed. Both are the same defect: the delivered change no longer matches its cause. Core principle: size fixes to their trigger, and when reality forces a cut, decompose visibly instead of trimming quietly.
范围失控存在两种情况：镀金式扩张使修复内容超出触发原因，而悄悄缩减范围则让已获批的任务达不到约定标准。两者本质相同：交付的变更与触发原因不再匹配。核心原则：根据触发因素确定修复规模，当实际情况必须削减时，需明确分解任务而非悄悄缩减范围。

Sizing to the trigger

根据触发因素确定规模

  • The fix is as big as the thing that triggered it. No gold-plating, no fencing unreachable edges, no refactor riding along because the file was open.
  • Adjacent improvements you noticed are real and belong in the tracker, not in this diff. One trigger, one change, one reviewable story.
  • The test for a borderline addition: would this change ship on its own merits if the main fix did not exist? If not, it is decoration on someone else's diff.
  • 修复规模应与触发因素匹配。不做镀金式优化，无需处理无法触及的边缘情况，也不要因为打开了某个文件就顺便进行重构。
  • 你发现的相邻改进点确实有价值，但应纳入任务追踪系统，而非放入本次代码变更中。一个触发因素对应一项变更、一个可评审的任务。
  • 判断某项新增内容是否合理的标准：如果没有主修复内容，这项变更是否能凭借自身价值独立发布？若不能，那它就是附加在他人代码变更上的装饰性内容。

Decompose, never silently descope

分解任务，绝不悄悄缩减范围

  • An approved task that turns out too big is decomposed into named parts with the cut line stated, never delivered as a quiet "pragmatic minimum" that looks complete.
  • What gets deferred becomes a tracked item with an owner (the tracker discipline lives in the technical-writer plugin's 
    writing-issues
    where installed); deferred work that lives only in the author's memory was descoped, not deferred.
  • The report says plainly which parts shipped and which did not. A partial delivery honestly labeled is a plan; a partial delivery labeled complete is a defect.
  • 若已获批的任务实际规模过大，需将其分解为多个明确命名的部分，并说明拆分界限，绝不能以看似完整的“务实最小版本”交付。
  • 被推迟的工作需成为有负责人的追踪项（任务追踪规范在已安装的technical-writer插件的
    writing-issues
    中）；仅存在于作者记忆中的推迟工作属于范围缩减，而非合理推迟。
  • 报告需明确说明已交付部分和未交付部分。如实标注的部分交付是计划内的，而标注为完成的部分交付则属于缺陷。

Driving to completion

推进至完成

  • An approved plan runs to completion without "want me to continue?" checkpoints; stop only for genuine blockers, destructive actions, or hard gates that need the operator.
  • Blocked on one part: finish the unblocked parts, surface the blocker with what it needs, never let one stuck task silently stall the rest.
  • Settled decisions stay settled mid-execution. New information that genuinely reopens one becomes an explicit re-decision (recorded, where the technical-writer plugin is installed, via 
    recording-decisions
    ), not a quiet swerve.
  • 已获批的计划需执行至完成，无需中途询问“是否需要继续？”；仅在遇到真正的阻塞、破坏性操作或需要操作者确认的关键节点时才停止。
  • 若某一部分受阻：先完成未受阻的部分，明确列出阻塞点及所需支持，绝不能因一个任务受阻而让整个工作悄悄停滞。
  • 已确定的决策在执行过程中保持不变。若新信息确实需要重新决策，需进行明确的重新决策（在已安装technical-writer插件的情况下，通过
    recording-decisions
    记录），而非悄悄改变方向。

Scope in review

评审中的范围管理

  • Reviewing a change: an unrelated defect you noticed in passing is not your finding; note it once for the tracker and stay on the diff. Out-of-scope findings dilute the verdict and train authors to fear review.
  • Being reviewed: findings against the diff get fixed or explicitly answered; findings outside the diff get tracked, not absorbed into the change.
  • 评审变更时：你偶然发现的无关缺陷不属于本次评审的发现；只需记录一次并纳入任务追踪系统，专注于当前的代码变更。超出范围的发现会削弱评审结论，还会让作者惧怕评审。
  • 接受评审时：针对当前代码变更的问题需修复或明确回应；超出当前变更范围的问题需纳入追踪，而非直接加入本次变更。

Common mistakes

常见错误

  • "While I'm here" as a justification. You are here for the trigger.
  • Descoping to hit a deadline and reporting done. The deadline pressure was real; the honest move was decomposing and saying which half shipped.
  • Fencing edge cases the system cannot reach, to feel thorough. Unreachable defensiveness is dead code with good intentions.
  • Re-litigating an approved design in the middle of implementing it because a mildly better idea appeared. Write the idea down; finish the plan; propose the idea against the shipped reality.
  • Letting a reviewer's out-of-scope wish expand the diff. Track it, thank them, ship the trigger.
  • 以“顺便做一下”作为理由。你当前的工作是为了处理触发因素。
  • 为了赶截止日期而缩减范围，并报告任务完成。截止日期的压力确实存在，但正确的做法是分解任务并说明已交付哪一部分。
  • 处理系统无法触及的边缘情况，以显得考虑周全。这种无法触及的防御性代码是出于好意的无效代码。
  • 在实施过程中，因为想到一个稍好的主意就重新讨论已获批的设计。先记下这个想法，完成现有计划，再基于已交付的成果提出新想法。
  • 让评审者提出的超出范围的需求扩大本次代码变更。将其纳入追踪，感谢对方，交付触发因素对应的变更即可。