Skip to content

docs(code-submission): promote 8-class to 9-class with round-7 summary-drift insight#238

Merged
weicao merged 2 commits into
mainfrom
doc/promql-peer-review-9th-class
May 19, 2026
Merged

docs(code-submission): promote 8-class to 9-class with round-7 summary-drift insight#238
weicao merged 2 commits into
mainfrom
doc/promql-peer-review-9th-class

Conversation

@weicao
Copy link
Copy Markdown
Contributor

@weicao weicao commented May 19, 2026

Summary

Follow-up to PR #222 (merge commit 51baa0a). 升 8 类 → 9 类 blocker checklist, 加入第 9 类:summary / closeout 段与 body sections 单源漂移

触发洞察来自 PR #221 round-7 (Sprint 2 DG/DR PromQL rule pack case v0.3.7 trail): §7 diff table / §10 关键依赖关系 / 一句话总结三处把 body §6.5.5 / §6.5.7 / §10 的 Rule 7/8 pending 分支写成 definite 已 lock, 摘要段读者按字面执行就会跳过 condition 检查。

第 9 类的边界 (与类 8 (b) 区分)

触发点 视角
类 8 (b) 某次 section 状态升级事件 升级时扫读者最先看的段落是否同步
类 9 任何 body 改动 摘要段是 body single-source consumer, 不能成为独立 source of truth

两类同源 (摘要漂移) 但视角不同, 都要跑。

同步更新

  • 标题 / intro / docs/code-submission/README.md entry: 8 → 9
  • §适用场景 表格 4 行: 8 类 → 9 类
  • Reviewer Checklist 加类 9 行
  • 反模式速查表加 "摘要重写" 一行
  • ## 一句话总结 加 "摘要单源漂移" 维度

不漂移保证

Test plan

  • @john focused review: 类 9 定义 / 边界与类 8 (b) 区分 / Reviewer Checklist / 反模式表 / 一句话总结口径
  • doc-only PR; 无 CI; 无 CODEOWNERS

…y-drift insight

加入第 9 类 blocker:summary / closeout 段与 body sections 单源漂移 — 摘要段当独立 source of truth, body 是 pending 但摘要写 definite, 限定词丢失。

触发洞察来自 PR #221 round-7 (Sprint 2 DG/DR PromQL rule pack case v0.3.7 trail):§7 diff table / §10 关键依赖关系 / 一句话总结三处把 body §6.5.5 / §6.5.7 / §10 的 Rule 7/8 pending 分支写成 definite 已 lock, 摘要段读者按字面执行就会跳过 condition 检查。

第 9 类内容:
- 定义:摘要段当独立 source of truth → (a) 限定词丢失 (b) 新断言出现
- 例子:body Rule 7/8 pending, 摘要写成已 lock, 关键依赖关系写成 diff 表三处已 lock
- 挡法:reviewer 拿摘要每一句反向到 body 找 source;body 是 pending / conditional 而摘要写 definite 立即挡
- 修法:摘要定位成 body single-source consumer, 限定词逐字保留, 多版本 trail 每升一版重扫
- 与类 8 (b) 的边界:8 (b) 触发点是状态升级事件, 类 9 触发点不限于状态升级, 任何 body 改动都要重扫摘要

同步更新:
- 标题 / intro / Guides README entry:8 → 9
- Reviewer Checklist 加类 9 行
- 反模式速查表加摘要重写一行
- 一句话总结加摘要单源漂移维度

不引入 KB 版本依赖;class 1-8 文字未漂移;案例附录 cross-link 指向已合并的 oracle-dg-dr-promql-rule-pack-sprint2-case.md (PR #221 merge commit 1075112)。
@weicao
Copy link
Copy Markdown
Contributor Author

weicao commented May 19, 2026

Round-1 focused review: HOLD on 2 small wrapper/doc drift issues. Scope is doc/static only.

Checked:

  • git diff --check origin/main...origin/pr-238 is clean.
  • Commit message is clean; I did not see AI/tool/vendor attribution in the commit.
  • Case cross-link target exists after PR docs(cases/oracle): add DG/DR PromQL rule pack Sprint 2 handoff case #221 landed.
  • The new class-9 definition, boundary against class 8(b), reviewer checklist line, anti-pattern row, and final one-line summary are directionally OK.

Blockers:

  1. PR body still has a GitHub-facing AI/tool footer: Generated with [Claude Code].
    This reintroduces the exact submission-discipline issue that PR docs(code-submission): add PromQL rule pack peer review 8-class blocker guide #222 / PR docs(cases/oracle): add DG/DR PromQL rule pack Sprint 2 handoff case #221 already cleaned up. Please remove the PR body footer. The commit message itself looks clean, so this is PR-body only from what I checked.

  2. docs/code-submission/addon-promql-rule-pack-peer-review-blocker-class-guide.md:48-51 still says 8 类 in all four ## 适用场景 rows.
    The rest of the doc has mostly moved to 9 类, so this section now contradicts the title, intro, checklist, anti-pattern table, appendix, and one-line summary. Please update those rows to 9 类 / 九类.

After those two are fixed, I can do a quick round-2 focused review on PR body + lines 48-51 only.

…5aaaf)

PR #238 round-1 focused review HOLD-ed 2 个小点,全部受理。

Fix 1 — §适用场景 4 行 "8 类" → "9 类"
- promote 时漏改的 4 行表格内容, 整篇主体已用 "9 类" / "九类", 但 §适用场景表格仍写 "8 类", 和主题漂移。
- 4 行统一改为 "9 类"。
- 同 doc 内 line 174 引用 sister doc `addon-design-contract-review-during-xp-guide.md` 的 "状态机 8 类 blocker" 是对另一篇 doc 的字面引用, 不动。

Fix 2 — PR body 去掉 `Generated with [Claude Code]` footer (signing discipline)
- 本 commit 不动代码, footer 修改在 PR body 端用 `gh pr edit --body-file` 已落, 同时 PR body 同步更新增 "§适用场景 表格 4 行: 8 类 → 9 类" 一行到「同步更新」节, 与本 commit 内容对齐。

class 1-8 文字未动;案例附录 cross-link 仍指向已合并的 PR #221 (merge commit 1075112);不引入新 KB 版本依赖。
@weicao
Copy link
Copy Markdown
Contributor Author

weicao commented May 19, 2026

Round-2 focused review: PASS.

Checked only the two round-1 HOLD points:

  • PR body no longer contains Generated with [Claude Code] or other AI/tool/vendor footer strings.
  • docs/code-submission/addon-promql-rule-pack-peer-review-blocker-class-guide.md:48-51 now says 9 类 in all four ## 适用场景 rows.

Also checked git diff --check origin/main...origin/pr-238: clean. The remaining “8 类” reference at the sister doc link is correct because it describes addon-design-contract-review-during-xp-guide.md, not this PromQL guide.

Boundary: doc/static focused review only.

@weicao weicao merged commit 1fc3dfc into main May 19, 2026
@weicao weicao deleted the doc/promql-peer-review-9th-class branch May 19, 2026 07:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant