visual-recap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

System recap

系统回顾

When a change is non-trivial (a plan, a PR create or update, or a request for a visual recap), put one marker-delimited block in the PR description. GitHub renders it. It does not replace reading the diff.
当变更并非简单修改时(无论是制定计划、创建或更新 PR,还是收到可视化回顾请求),都要在 PR 描述中放入一个由标记界定的区块。GitHub 会渲染该区块,但它不能代替阅读 diff。

When

使用时机

Recap mode reads the diff, not memory. Claims about what changed must be checkable against
git diff <base>...HEAD
(plus
--stat
). Session context may explain intent only.
Run the classifier. Roll up to the highest of
adds
, then
extends
, then
composes
. You still choose
composes
vs
extends
from the diff.
adds
is a new map entry.
RollupRiskAlso
composes
lowWiring and call sites only.
extends
mediumVerify locally with the project's control CLI as the seeded user; a PR preview only when local cannot
adds
highUpdate
primitives.yaml
, run
check-primitives-map.mjs
, and the same local verify (preview when needed)
Update
primitives.yaml
when this PR adds, removes, or materially reshapes a primitive (new
id
, renamed meaning, or ownership roots that must change). Do not edit
summary
for ordinary feature work. Call out a touched invariant from that map at every risk.
Keep each entry's
adrs
in sync: list the current decision records that shape the primitive (
adrs: []
if none), and when this PR adds or supersedes a record, add it to (or swap it into) the matching entries. The classifier prints each touched primitive's
adrs
; read them before you change that primitive. The check script fails on missing or superseded paths.
Plan mode uses
**Mode:** plan
before a PR exists. Recap mode replaces that block from
git diff <base>...HEAD
. In plan mode, say explicitly when the plan requires no change to any primitive; that is the lowest-risk outcome.
The block shape is one example: references/block-format.md.
recap 模式以 diff 为依据,而不是依赖记忆。 关于变更内容的陈述必须能够通过
git diff <base>...HEAD
(以及
--stat
)进行核验。会话上下文只能用于解释意图。
运行分类器。按
adds
、
extends
、
composes
的顺序向上汇总,并取其中最高等级。
composes
与
extends
之间仍需根据 diff 进行选择。
adds
表示新增一个 map 条目。
汇总级别风险附加要求
composes
低仅涉及连接与调用点。
extends
中在本地以已预置用户的身份使用项目的 control CLI 进行验证;仅当本地无法完成验证时,才使用 PR 预览。
adds
高更新
primitives.yaml
,运行
check-primitives-map.mjs
,并执行同样的本地验证(必要时使用预览)。
当此 PR 新增、移除或实质性重构某个 primitive(使用新的
id
、含义被重新定义,或必须变更 ownership roots)时,请更新
primitives.yaml
。对于普通功能开发,不要修改
summary
。无论风险等级如何,都要明确指出该 map 中被触及的 invariant。
保持每个条目的
adrs
同步:列出当前塑造该 primitive 的决策记录(如果没有,则为
adrs: []
);当此 PR 新增或取代某条记录时,将其添加到匹配的条目中,或替换其中的旧记录。分类器会打印每个受影响 primitive 的
adrs
;修改该 primitive 前必须先阅读这些记录。检查脚本会在路径缺失或已被取代时失败。
在 PR 尚未创建时,plan 模式使用
**Mode:** plan
。recap 模式根据
git diff <base>...HEAD
替换该区块。在 plan 模式下,如果计划无需更改任何 primitive,请明确说明;这是风险最低的结果。
以下是一个区块格式示例: references/block-format.md。

Command

命令

bash
node .agents/skills/visual-recap/scripts/classify-primitives.mjs --base <base> --head HEAD --json
node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> <block-file>
node .agents/skills/visual-recap/scripts/check-primitives-map.mjs
The upsert script checks mermaid, then replaces the marker block or appends it. It does not edit text outside the markers. Re-run both commands after a significant push.
bash
node .agents/skills/visual-recap/scripts/classify-primitives.mjs --base <base> --head HEAD --json
node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> <block-file>
node .agents/skills/visual-recap/scripts/check-primitives-map.mjs
upsert 脚本会先检查 Mermaid,然后替换标记区块;若区块不存在,则进行追加。它不会修改标记范围之外的文本。完成重大 push 后,重新运行这两个命令。

Failure

失败处理

  • The mermaid check exits non-zero. Fix the diagram. Keep
    ;
    out of sequence notes and messages.
  • The block file must start with
    <!-- system-recap:start -->
    and end with
    <!-- system-recap:end -->
    .
  • gh pr edit
    fails with
    Resource not accessible by integration (updatePullRequest)
    . The script still prints the merged body. Apply that body with Cursor ManagePullRequest. Do not have Kody edit the PR.
  • A health check or login smoke is not medium or high verification. Prefer local control CLI proof; use a preview only when local cannot exercise the change. Do not cat the session cookie into curl or Python.
  • Mermaid 检查以非零状态退出。修复图表。序列图的 note 和 message 中不要使用
    ;
    。
  • 区块文件必须以
    <!-- system-recap:start -->
    开头,并以
    <!-- system-recap:end -->
    结尾。
  • gh pr edit
    失败并返回
    Resource not accessible by integration (updatePullRequest)
    。脚本仍会打印合并后的正文。使用 Cursor ManagePullRequest 应用该正文。不要让 Kody 编辑 PR。
  • health check 或 login smoke test 并不构成中、高风险级别的验证。优先提供本地 control CLI 验证证据;仅当本地无法验证变更时才使用预览。不要将 session cookie 通过
    cat
    管道传给 curl 或 Python。