Back to Details

ssotize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Find where one truth lives, get approval for the consolidation plan, then collapse it into one canonical home.
找到事实的可信存储位置，获取整合计划的批准，随后将其合并到一个权威主源中。

Goal

目标

Enforce Single Source of Truth (SSOT): one fact = one home, and every other place that needs it references that home instead of copying it. References don't drift; copies do. This mutates artifacts, so it is deliberate and loss-averse.
ssotize
starts as a read-only audit. It names the truth in scope, finds every copy, chooses the canonical home, and reports the exact consolidation plan. Only after the user approves that plan does it mutate artifacts.
Use this to establish or repair SSOT — messy, legacy, or freshly-scaffolded states. Once SSOT holds, don't overuse it: consolidation is a one-time repair, not ongoing upkeep. When a read-only checker and a mutating follow-up have become one inseparable workflow, fold the checker into the consolidator and keep the approval gate; splitting the reflex only makes the safer first half easier to skip.
强制执行单一可信源（SSOT）原则：一个事实对应一个存储位置，其他所有需要该事实的地方都引用这个主源，而非复制内容。引用不会出现偏差，复制则会。此操作会修改工件，因此需谨慎执行并避免信息丢失。
ssotize
初始为只读审核模式。它会明确当前范围内的事实，找到所有副本，选定权威主源，并汇报具体的整合计划。只有在用户批准该计划后，才会对工件进行修改。
可使用此方法建立或修复SSOT——适用于混乱的遗留系统、现有状态或刚搭建的新系统。一旦SSOT确立，请勿过度使用：整合是一次性的修复操作，而非持续维护工作。当只读检查与后续修改操作已成为不可分割的工作流时，可将检查环节整合到整合工具中，并保留批准流程；拆分这两个环节只会让更安全的前置检查环节更容易被跳过。

Workflow

工作流程

  1. Name the truth in scope — the specific fact, value, spec, decision, status, or definition being tracked, not the whole document.
  2. Audit read-only first: enumerate every occurrence across the given artifacts and platforms.
  3. Re-enumerate by a second method — a different search term, synonym, or tool — and confirm it surfaces no occurrence the first pass missed.
  4. Classify each occurrence: exact copy, paraphrase, partial, stale, or contradictory.
  5. Pick the canonical home — the most authoritative and most-maintained location, closest to where the fact actually changes. Never promote a weak copy just because it is convenient; extract a new canonical home if none exists.
  6. Decide the action per non-canonical occurrence: dedupe (redundant copy), reference (docs should link to canonical, code should import/source/include it, config should use a shared read), or reconcile (it disagrees and needs a human call).
  7. Report the audit before editing: a table of occurrences (location · kind · action), the proposed canonical home with a one-line justification, unique details that must be folded into it, contradictions that need a decision, and the exact mutation plan.
  8. Ask for explicit approval to execute the mutation plan. If approval is not given, stop after the read-only report.
  9. Make or extract the canonical home complete and current — fold in any unique detail that lived only in a copy. Never lose information to consolidation.
  10. Reconcile contradictions in the canonical home first; when the correct value is ambiguous, confirm it before replacing anything.
  11. Replace each duplicate with a live reference to the canonical home — for docs, use a link, a "see <home>", a quote-with-link, or a transclude where the platform supports it; for code, use an import/source/include of the shared home; for config, use a shared read from the one maintained file.
  12. Remove the now-redundant copies. Where removal would orphan a reader, leave a one-line pointer instead of deleting outright.
  1. 明确当前范围内的事实——即被追踪的具体事实、数值、规范、决策、状态或定义，而非整个文档。
  2. 首先进行只读审核：枚举给定工件和平台中的所有相关实例。
  3. 通过第二种方法重新枚举——使用不同的搜索词、同义词或工具——确认首次扫描未遗漏任何实例。
  4. 对每个实例进行分类：完全复制、改写、部分引用、过时内容或矛盾内容。
  5. 选定权威主源——选择最具权威性、维护最频繁且最接近事实变更源头的位置。绝不能仅为了方便就选用质量较差的副本；如果不存在合适的主源，则需新建一个权威主源。
  6. 为每个非权威实例决定处理方式：去重（冗余副本）、引用（文档应链接到权威主源，代码应导入/引用/包含该主源内容，配置应读取共享源）或调和（内容存在矛盾，需人工决策）。
  7. 在编辑前汇报审核结果：包含实例表格（位置 · 类型 · 处理方式）、拟议的权威主源及一行理由说明、必须整合到主源中的独特细节、需要决策的矛盾点，以及具体的修改计划。
  8. 请求明确批准以执行修改计划。若未获得批准，则在只读汇报后停止操作。
  9. 创建或完善权威主源，确保其内容完整且最新——整合仅存在于副本中的所有独特细节。整合过程中绝不能丢失任何信息。
  10. 首先调和权威主源中的矛盾内容；若正确数值不明确，需先确认再进行替换。
  11. 将每个副本替换为指向权威主源的实时引用——对于文档，使用链接、“参见<主源>”、带链接的引用，或在平台支持的情况下使用嵌入；对于代码，使用导入/引用/包含共享主源的方式；对于配置，从维护的单一文件中读取共享内容。
  12. 删除现已冗余的副本。若删除会导致读者无法找到相关内容，则保留一行指向主源的提示，而非直接删除。

Rules

规则

  • A pass that finds no scatter to consolidate changes nothing.
  • The audit phase is read-only. Do not edit, move, or delete before the user approves the mutation plan.
  • An empty findings list is a valid result — never invent drift to justify a consolidation.
  • Keep contradictions separate from plain duplicates; never silently decide which conflicting value is "true".
  • Flag any detail that lives only in a non-canonical copy — it must be folded into the canonical home before that copy can be cut.
  • Don't consolidate across a trust/permission boundary (private → public, customer-facing → internal) without explicit confirmation.
  • Mutate with edit-safety: assert each replace target exists before touching it (report a MISS, never a silent no-op), edit unicode-safe (
    PYTHONUTF8=1
    ), and act per occurrence, never a blanket sweep; make structural code moves with language-aware tools or scripted AST/parser edits, never scripted text rewrites.
  • Be platform-aware: transclude where possible, else link to a stable anchor the reader can follow; prefer a reference over a hard deletion when a platform can't link back.
  • When the same project fact is split between a read-only audit artifact and a mutating artifact, and the audit has no independent durable use, treat that as SSOT scatter: propose folding the audit into the mutating artifact, then execute only after approval.
  • 若扫描未发现需要整合的分散内容，则不进行任何修改。
  • 审核阶段为只读模式。在用户批准修改计划前，不得进行编辑、移动或删除操作。
  • 空结果列表是有效的审核结果——绝不能虚构偏差来合理化整合操作。
  • 将矛盾内容与普通副本分开处理；绝不能擅自决定哪个冲突数值是“正确的”。
  • 标记仅存在于非权威副本中的所有细节——在删除该副本前，必须将这些细节整合到权威主源中。
  • 未经明确确认，不得跨信任/权限边界进行整合（如从私有到公开、从面向客户到内部）。
  • 修改时需确保编辑安全：在修改前确认每个目标位置存在（汇报缺失情况，绝不静默无操作），支持Unicode安全编辑（
    PYTHONUTF8=1
    ），逐个实例处理，绝不批量操作；使用语言感知工具或脚本化AST/解析器编辑来进行结构化代码迁移，绝不使用脚本化文本重写。
  • 适配平台特性：尽可能使用嵌入，否则链接到读者可访问的稳定锚点；当平台无法反向链接时，优先使用引用而非直接删除。
  • 若同一项目的事实分散在只读审核工件和可修改工件中，且审核工件无独立持久用途，则将其视为SSOT分散问题：提议将审核内容整合到可修改工件中，仅在获得批准后执行。

Verification

验证

Before finishing:
  1. The audit was reported before mutation and approval was received, unless the run stayed read-only.
  2. The canonical home holds the complete, current truth on its own.
  3. Every former copy now references it, and each reference resolves.
  4. No unique detail was lost and nothing was orphaned.
  5. Contradictions were reconciled to one value, not left duplicated.
  6. Report what was consolidated, where the canonical home is, what was only audited, and what still needs a human decision.
完成操作前需确认：
  1. 若进行了修改操作，则已在修改前汇报审核结果并获得批准；若仅进行只读审核则无需批准。
  2. 权威主源自身包含完整、最新的事实内容。
  3. 所有原副本现在均引用权威主源，且每个引用均可正常访问。
  4. 未丢失任何独特细节，也未出现内容孤立的情况。
  5. 矛盾内容已调和为单一数值，未保留重复内容。
  6. 汇报整合的内容、权威主源的位置、仅进行审核的内容，以及仍需人工决策的事项。