Back to Details

safe-change

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: safe-change

Skill: safe-change

WHAT

是什么

Purpose và context

目的与上下文

  • Purpose: sửa code dùng chung (hàm/class/module có nhiều caller) mà không làm gãy caller hiện có.
  • Trigger (when to use): Modifying any function, class, or module called from more than one place.
  • Non-goals: không refactor tiện tay code kề bên, không viết thêm test ngoài phạm vi task, không tự tìm caller bằng tay thay 
    impact-check
    .
  • 目的： 修改共享代码（被多个 caller 调用的 function/class/module），且不破坏现有 caller。
  • 触发条件（何时使用）： 修改任何从不止一个位置调用的 function、class 或 module。
  • 非目标： 不顺手 refactor 邻近代码；不在 task 范围之外额外编写 test；不手动查找 caller 来替代 
    impact-check
    。

Mental model

思维模型

symbol dùng chung → impact-check (callers + dependents) → hành vi quan sát được hiện tại → thay đổi tối thiểu → từng caller: tương thích ngược hoặc cập nhật tường minh → test (nếu có) → "Changed X. Verified Y" → verify-before-commit
.
共享 symbol → impact-check（callers + dependents）→ 当前可观察行为（observable behavior）→ 最小变更 → 逐个 caller：保持向后兼容或显式更新 → test（如有）→ "Changed X. Verified Y still works." → verify-before-commit
。

Input và output contract

输入与输出约定

FieldRequired?Ý nghĩa
Insymbol/module cần sửa + yêu cầu thay đổicóthứ có hơn một caller
Intest của modulekhôngcó thì chạy; không có thì ghi rõ trong commit message
Outthay đổi tối thiểu + caller đã xác minh/cập nhậtcómọi caller từ bước 1 đều được xét
Outcâu xác nhận "Changed X. Verified Y still works."córồi gọi 
verify-before-commit
Out
wiki/sources/draft/DDMMYY-<ten>.md
có (trừ khi 0 artifact)output report
字段是否必需？含义
In需要修改的 symbol/module + 变更要求是存在多个 caller 的对象
Inmodule 的 test否如有则运行；如无则在 commit message 中明确注明
Out最小变更 + 已验证/更新的 caller是第 1 步中的所有 caller 均已处理
Out确认语句 
"Changed X. Verified Y still works."
是随后调用 
verify-before-commit
Out
wiki/sources/draft/DDMMYY-<ten>.md
是（除非为 0 个 artifact）output report

Rules và capabilities

规则与能力

  • RULE-01 (MUST): Backward compatibility impossible → surface to user before proceeding.
  • RULE-02 (MUST): Touch only what task requires — no opportunistic refactoring.
  • RULE-03 (MUST): No tests exist → acceptable to note — don't add tests outside task scope.
  • Capabilities: truy vấn đồ thị caller/dependent; đọc + sửa code trong phạm vi task; chạy test cục bộ; ghi draft wiki.
  • RULE-01 (MUST): 无法保持向后兼容性（backward compatibility）→ 在继续之前向用户说明。
  • RULE-02 (MUST): 仅修改 task 要求的内容——不进行顺带 refactor。
  • RULE-03 (MUST): 没有 test → 可以明确注明——不要在 task 范围之外添加 test。
  • 能力：查询 caller/dependent 图；读取并修改 task 范围内的 code；运行本地 test；编写 wiki draft。

Failure boundaries

失败边界

  • Không giữ được tương thích ngược → clarify: dừng, báo user trước khi làm tiếp (RULE-01).
  • Test đỏ sau khi sửa → blocked, không sang 
    verify-before-commit
    .
  • Không có test → partial hợp lệ: ghi rõ trong commit message, không tự viết test.
  • 无法保持向后兼容性 → clarify：停止，在继续之前告知用户（RULE-01）。
  • 修改后 test 失败 → blocked，不得进入 
    verify-before-commit
    。
  • 没有 test → 可接受 partial 结果：在 commit message 中明确注明，不自行编写 test。

HOW

如何

Main workflow

主工作流

StepTypeInputsActionOutputs/exitFailure/next
W01deterministicsymbolChạy skill 
impact-check
danh sách callers + dependents—
W02judgmentcode hiện tạiGhi lại hành vi quan sát được (return value, side effect)baseline hành vi—
W03effectyêu cầuThay đổi tối thiểu, không đụng code kề bêndiffkhông giữ được tương thích → B01
W04judgmentcallers W01Từng caller: xác minh tương thích ngược hoặc cập nhật tường minhmọi caller đã xét—
W05deterministictest dirTìm test, có thì chạyrc 0 hoặc ghi chú "no tests"test đỏ → blocked; không test → B02
W06effectkết quảXác nhận + gọi 
verify-before-commit
+ output report		câu xác nhận + draft—
Chi tiết từng bước (nguồn chân lý cho W01–W06):
  1. Run 
    impact-check
    skill — get list of all callers and dependents.
  2. Note current observable behaviour (return values, side effects).
  3. Make minimal change. Don't touch adjacent code.
  4. For each caller from step 1: verify backward-compatible or explicitly update caller.
  5. CHECK: ls <test-dir>/*<module>* 2>/dev/null | head -3
    — if tests exist, 
    RUN: <test-cmd>
    . If none, note explicitly in commit message.
  6. Confirm: "Changed X. Verified Y still works." Then invoke 
    verify-before-commit
    .
步骤类型输入操作输出/退出失败/下一步
W01确定性（deterministic）symbol运行 
impact-check
skill		callers + dependents 列表—
W02判断（judgment）当前 code记录可观察行为（return value、side effect）行为 baseline—
W03执行（effect）变更要求进行最小变更，不触碰邻近 codediff无法保持向后兼容 → B01
W04判断（judgment）W01 中的 callers逐个验证向后兼容性，或显式更新 caller所有 caller 均已处理—
W05确定性（deterministic）test dir查找 test；如有则运行rc 0 或注明 
"no tests"
test 失败 → blocked；没有 test → B02
W06执行（effect）结果确认 + 调用 
verify-before-commit
+ 输出 report		确认语句 + draft—

Branches

各步骤详情（W01–W06 的权威事实来源）：

IDKindGuardHành viSkip / failureRejoin
B01recoverykhông thể giữ backward compatibilitydừng, báo user trước khi làm tiếpuser không duyệt → cancelledW04 sau khi user duyệt
B02conditional_requiredkhông có test cho moduleghi rõ "no tests" trong commit message, không viết test mới—W06
  1. 运行 
    impact-check
    skill——获取所有 caller 和 dependent 的列表。
  2. 记录当前可观察行为（return values、side effects）。
  3. 进行最小变更。不要触碰邻近代码。
  4. 对于第 1 步中的每个 caller：验证其向后兼容性，或显式更新 caller。
  5. CHECK: ls <test-dir>/*<module>* 2>/dev/null | head -3
    ——如果 test 存在，则执行 
    RUN: <test-cmd>
    。如果没有，则在 commit message 中明确注明。
  6. 确认：
    "Changed X. Verified Y still works."
    ，然后调用 
    verify-before-commit
    。

Validation và stopping

分支

Điều kiện đi tiếp: mọi caller trong danh sách 
impact-check
đã được xét, và test (nếu có) rc 0. Dừng ở câu xác nhận + 
verify-before-commit
; không tự refactor thêm.
ID类型Guard行为跳过/失败汇合点
B01恢复（recovery）无法保持向后兼容性停止，在继续之前告知用户用户未批准 → cancelled用户批准后返回 W04
B02条件必需（conditional_required）module 没有 test在 commit message 中明确写明 
"no tests"
，不编写新 test		—W06

Examples

验证与停止条件

  • Positive: thêm tham số optional 
    timeout=30
    vào 
    fetch_page()
    có 4 caller → impact-check liệt kê 4 caller, cả 4 không truyền tham số nên tương thích → test module xanh → "Changed fetch_page signature. Verified 4 callers still work." → verify-before-commit.
  • Boundary/failure: đổi kiểu trả về 
    get_user()
    từ dict sang object, 2 caller dùng 
    user["id"]
    → không giữ được tương thích → dừng, báo user (B01), chưa sửa caller khi chưa được duyệt.
继续条件：
impact-check
列表中的所有 caller 都已处理，且 test（如有）的 rc 为 0。在确认语句 + 
verify-before-commit
处停止；不得自行进行额外 refactor。

Delivery — Output Report

示例

After all main skill tasks complete, write a propose draft to the wiki.
  • 正向示例： 为有 4 个 caller 的 
    fetch_page()
    添加可选参数 
    timeout=30
    → 
    impact-check
    列出 4 个 caller，4 个均不传该参数，因此向后兼容 → module test 通过 → 
    "Changed fetch_page signature. Verified 4 callers still work."
    → 
    verify-before-commit
    。
  • 边界/失败： 将 
    get_user()
    的返回类型从 dict 改为 object，2 个 caller 使用 
    user["id"]
    → 无法保持向后兼容 → 停止并告知用户（B01）；未获批准前不修改 caller。

Steps

交付——Output Report

1. Build the filename:
  • Format: 
    DDMMYY-<ten>.md
  • DDMMYY
    = today (e.g., 
    020626
    for 2 June 2026)
  • <ten>
    = 2–4 kebab-case words summarising what was done (e.g., 
    landing-page-coteccons
    , 
    brand-kit-fintech
    , 
    ingest-auth-spec
    )
2. Write 
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
:
---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---
所有主 skill task 完成后，向 wiki 写入一份 proposed draft。

DDMMYY-<ten>

步骤

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD
1. 构建文件名：
  • 格式：
    DDMMYY-<ten>.md
  • DDMMYY
    = 今天（例如，
    020626
    表示 2026 年 6 月 2 日）
  • <ten>
    = 2–4 个概括本次完成内容的 kebab-case 单词（例如，
    landing-page-coteccons
    、
    brand-kit-fintech
    、
    ingest-auth-spec
    ）
2. 写入 
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
：
---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

What

DDMMYY-<ten>

<One sentence — what this skill invocation produced or decided>
Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

Output

What

<Key artefacts, files created/modified, or decisions made>
<One sentence — what this skill invocation produced or decided>

Files

Output

FileAction
path/to/file
created / modified
<Key artefacts, files created/modified, or decisions made>

Notes

Files

  • Invoked via: 
    /<skill-name>
    skill
FileAction
path/to/file
created / modified

Origin

Notes

  • Draft: 
    wiki/sources/draft/DDMMYY-<ten>.md
  • Commit: (filled by verify-before-commit)
  • Date promoted: (filled by verify-before-commit)

**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).
  • Invoked via: 
    /<skill-name>
    skill
—

Origin

—
  • Draft: 
    wiki/sources/draft/DDMMYY-<ten>.md
  • Commit: (filled by verify-before-commit)
  • Date promoted: (filled by verify-before-commit)

**3. 更新 wiki index 与 log：**
- `llmwiki/wiki/index.md`——追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md`——追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 仅当 skill 未产出任何 artifact 且未作出任何 decision 时才跳过（例如，`/caveman-stats` 这类纯展示模式）。