docs: add controller diagnostic PR scope guide

docs/SKILL-INDEX.md

@@ -2,7 +2,7 @@
 
 这套文档面向 Addon 开发与测试工程师，采用渐进式披露的目录组织：
 
-- 顶层：本索引列出 8 个领域，每个领域 1 行描述。
+- 顶层：本索引列出 9 个领域，每个领域 1 行描述。
 - 中层：每个领域子目录的 `README.md` 列本领域所有 guide。
 - 底层：guide 本身写方法论；引擎相关内容放在 `cases/` 下。
 
@@ -15,6 +15,7 @@
 | [`design/`](design/README.md) | 设计 / 开发新 addon — ComponentDefinition、lifecycle action、bootstrap、role publish、switchover、TLS、reconfigure、probe、ParametersDefinition、controller crash resilience | `design/README.md` |
 | [`test/`](test/README.md) | 写 smoke / chaos / soak / regression 测试 — first blocker、bounded retry、evidence discipline、harness 三轨、baseline / intensity / parallel、fake server validation、ship-readiness validation | `test/README.md` |
 | [`troubleshoot/`](troubleshoot/README.md) | 运行期排障 — Ops/Restart 卡住、reconcile 诊断、chart vs KB schema skew、finalizer 死锁、stuck-resource cleanup、image-tag vs PR merge 边界 | `troubleshoot/README.md` |
+| [`controller/`](controller/README.md) | KubeBlocks controller 开发经验 — DataProtection、Configure、Ops、诊断补丁、patch image、主线修复边界 | `controller/README.md` |
 | [`code-submission/`](code-submission/README.md) | GitHub 提交 / PR / merge / review 纪律 | `code-submission/README.md` |
 | [`agent-collab/`](agent-collab/README.md) | Agent 自我纪律 + 互相协作 — skill 推广、skill 清单治理、Slock 线程纪律、pre-escalation、wording calibration | `agent-collab/README.md` |
 | [`vcluster/`](vcluster/README.md) | IDC vcluster 测试环境 — bootstrap、syncer 资源、镜像策略、生命周期、未发布 controller patch 验证 | `vcluster/README.md` |
@@ -46,4 +47,4 @@
 
 ## 找不到合适入口？
 
-如果以上 8 个领域和 cases 都不直接匹配你的场景，从根 [`addon-autonomous-development-loop-guide.md`](addon-autonomous-development-loop-guide.md) 开始，那篇 guide 描述的工作循环会自然带你走到对应领域。
+如果以上 9 个领域和 cases 都不直接匹配你的场景，从根 [`addon-autonomous-development-loop-guide.md`](addon-autonomous-development-loop-guide.md) 开始，那篇 guide 描述的工作循环会自然带你走到对应领域。

docs/controller/README.md

@@ -0,0 +1,9 @@
+# controller — KubeBlocks controller 开发经验
+
+这个目录放 KubeBlocks controller / DataProtection / Configure / Ops 等 controller 侧的开发经验。
+
+这里的文档只写 controller 通用规则。具体 addon、引擎、测试现场结果放到对应 `cases/` 目录。
+
+## Guides
+
+- [`addon-controller-diagnostic-pr-scope-guide.md`](addon-controller-diagnostic-pr-scope-guide.md) — controller 诊断-only PR 的边界：只为抓证据加日志时不默认进 main，先走临时分支 / release 分支 / patch image；证据闭合后再开正式修复 PR。

docs/controller/addon-controller-diagnostic-pr-scope-guide.md

@@ -0,0 +1,84 @@
+# Controller Diagnostic PR Scope 指南
+
+> **Audience**: KubeBlocks controller / DataProtection / Configure / Ops 工程师，以及 review 这些 PR 的同伴。
+> **Status**: draft
+> **Applies to**: 只为排查问题而加日志、指标、事件或临时观测点的 controller 改动。
+> **Applies to KB version**: all
+> **Affected by version skew**: yes — 诊断补丁通常只服务某个 release 现场或 patch image。
+
+当 addon 测试卡在 controller 链路里，但证据还不足以写修复时，工程师常会先加诊断日志。这个文档解决一个边界问题：**诊断补丁不是正式修复**。它应该帮助下一轮测试抓证据，而不是默认合进 main。
+
+## 先用白话理解这篇文档
+
+如果一段代码只是为了"看清楚现场发生了什么"，它就不应该被当成产品修复。先用临时分支、release 分支、patch image 或 sideload 跑一轮，把证据抓回来。
+
+等证据说明根因和修法后，再开真正的修复 PR。真正修复 PR 才考虑进 main。
+
+## 适用场景
+
+| 我在做什么 | 这篇 guide 怎么用 |
+|---|---|
+| 为卡住的 OpsRequest 补 queue 日志 | 走诊断补丁，不默认进 main |
+| 为 Configure 卡住补 reconcile 入口日志 | 先服务当前复现和证据采集 |
+| 为 DataProtection restore 补一次性状态打印 | 只证明现场路径，不替代修复 |
+| 已经知道修法并改了行为 | 这不是诊断补丁，按正常修复 PR 走 |
+
+## 通用方法论
+
+### 硬规则
+
+1. **只加诊断信息，不改行为**：日志、事件、指标可以；排队、状态机、重试、删除、回滚语义不能变。
+2. **诊断-only PR 不默认进 main**：优先用临时分支、release 分支、本地 build、patch image、sideload 跑目标现场。
+3. **PR 标题和正文要写明范围**：写清楚 `diagnostic only` / `logging only`，并说明不会闭合根因。
+4. **证据回来后再决定是否修 main**：如果证据证明是产品 bug，再单独开修复 PR。
+5. **不要把分支级 CI 问题混进诊断 PR**：release 分支工具链红项要单独维护，不塞进日志补丁。
+
+### 判断表
+
+| 改动内容 | 归类 | 下一步 |
+|---|---|---|
+| 只补 `V(1)` 日志，帮助区分分支 | 诊断补丁 | 临时分支 / release 分支 / patch image |
+| 补日志同时改变 retry / queue / status | 行为修复 | 写红测，开正式修复 PR |
+| 为现网 release 复现加一次性日志 | 诊断补丁 | 不默认 cherry-pick 到 main |
+| 修掉 nil deref / 错误状态 / 状态不收口 | 行为修复 | main PR + backport PR |
+
+### PR 正文最小模板
+
+```markdown
+Scope: diagnostic only.
+
+This PR adds logs for <object/path> so the next run can distinguish:
+- <branch 1>
+- <branch 2>
+- <branch 3>
+
+It does not change behavior:
+- no queue/status/retry/delete semantics changed
+- not a root-cause fix
+
+Validation:
+- <focused compile/test>
+- <known branch-wide CI issue, if any>
+
+Next:
+- build/sideload patch image for <addon/test>
+- collect evidence in <next run>
+```
+
+## 与其他 doc / skill 的关系
+
+- [`../../skills/autonomous-controller-development-loop/SKILL.md`](../../skills/autonomous-controller-development-loop/SKILL.md) 要求 controller agent 主动处理 PR、CI 和 addon handoff。本文补充的是"诊断补丁是否进 main"的边界。
+- [`../test/addon-patch-image-controller-active-verification-guide.md`](../test/addon-patch-image-controller-active-verification-guide.md) 说明 patch image 跑起来后，如何证明测试真的命中了目标 controller commit。
+- [`../code-submission/addon-github-submission-discipline-guide.md`](../code-submission/addon-github-submission-discipline-guide.md) 仍然适用于诊断 PR 的提交纪律。
+
+## 案例附录
+
+### OceanBase OpsRequest queue 日志
+
+一个 release-1.0 PR 只给 OpsRequest queue / deletion / dequeue 加诊断日志。它用于下一轮 OceanBase 长跑时区分"没进队列"、"被已有 Running 操作挡住"、"已经在跑"、"出队没有命中 annotation"。
+
+这类 PR 不改行为。它只服务当前证据采集，不需要再推一份 main PR。后续如果证据证明 queue 逻辑真的要改，再开正式修复 PR。
+
+## 一句话总结
+
+诊断补丁先用来抓证据，不默认进 main；证据指向真实修法后，再开正式修复 PR。