cavekit-revision

修订：追溯缺陷，回溯到套件

在 Cavekit 中，修订是指沿着 cavekit 链向上追溯生产环境中的缺陷，直到找到导致缺陷出现的缺口。实际操作中，如果构建的软件存在缺陷或遗漏，就要将问题追溯到套件和提示词，并从源头修复，而不只是修改代码。

关键洞见： 如果修复只存在于代码中，没有相应的 cavekit 更新，那么下一轮迭代可能会再次引入同一缺陷。目标是让套件加上迭代循环能够自主复现任何修复。

---

1. 修订为何重要

如果没有修订，每次缺陷修复都只是一次性补丁。迭代循环下次运行时，可能会重新引入缺陷，因为套件或计划中没有任何内容能避免这种情况。

通过修订：

• 缺陷修复会成为 cavekit 改进，并在今后的所有迭代中持续生效
• 迭代循环会变得 能够自我纠正——从每次人工干预中学习
• 套件会随着时间推移 逐步完善
• “套件所描述的内容”与“实际可用的内容”之间的差距会 持续缩小

Without revision:
  Bug found -> Fix code -> Bug may return next iteration

With revision:
  Bug found -> Fix code -> Update cavekit -> Re-run iteration loop -> Fix emerges from kits alone

---

2. 修订的 6 个步骤

这是将缺陷追溯到 cavekit 层面的根本原因并闭环处理的完整流程。

步骤 1：识别并修复缺陷

通过手动测试、自动化测试失败、用户报告或监控告警等方式定位缺陷，并按照常规调试流程解决。这样会得到一项可用的代码变更，但工作远未结束：只要底层的 cavekit 缺口尚未弥补，这项修复就很脆弱。

# The fix produces commits that we will analyze
git log --oneline -5
# a1b2c3d Fix: connection pool exhaustion under concurrent load
# e4f5g6h Fix: missing rate limit headers in API responses

步骤 2：分析 Cavekit 遗漏了什么

这是关键步骤。请问：“这项需求是在 cavekit 链的哪一环遗漏的？”

从以下五个维度展开分析：

• **WHAT（内容）**变了什么（文件、函数、可观察到的行为）
• **WHY（原因）**为什么错了（哪项假设被证明是错误的）
• VISUAL（视觉）——这项修复会改变视觉外观吗（CSS、样式、布局）？如果会，请检查 DESIGN.md 是否涵盖了这一模式。缺少设计模式意味着设计系统存在缺口，应与 cavekit 缺口一并修复。
• RULE（规则）（本应明确说明的不变量）
• LAYER（层级）（本应包含此内容的 cavekit、计划或提示词）

分析示例：

## Revision Analysis: Database Connection Pooling

**WHAT changed:** Added pool size limits and idle timeout in `src/db/pool.ts`
**WHY:** The data layer cavekit assumed unlimited connections; under load the database
         rejected new connections once the server-side limit was reached
**RULE:** "The database module MUST configure a bounded connection pool with
          idle timeout and max-connection limits matching the deployment target"
**LAYER:** cavekit-data.md (no mention of pool configuration), plan-data.md (no task for pool tuning)
**Cavekit implications:** Add requirement R5 to cavekit-data.md covering connection pool settings

步骤 3：更新 Cavekit

在相应的 cavekit 文件中添加缺失的要求或约束。重点关注足够具体、可供迭代循环执行的验收标准：

# In context/kits/cavekit-data.md, add:

### R5: Database Connection Pool Configuration
**Description:** The database module must use a bounded connection pool
with configurable limits to prevent resource exhaustion under load.
**Acceptance Criteria:**
- [ ] Maximum pool size is configurable and defaults to a sensible value
- [ ] Idle connections are reaped after a configurable timeout
- [ ] Pool exhaustion returns a clear error rather than hanging indefinitely
- [ ] Connection health checks run before returning a connection from the pool
**Dependencies:** R1 (database client setup), R2 (environment configuration)

步骤 4：将变更传递到计划和跟踪记录

沿着每个下游上下文文件追踪 cavekit 更新：

1. 找出受影响的计划文件： 哪些计划负责管理已变更的源代码路径？
2. 更新计划： 添加或关闭反映新要求的任务。
3. 更新实现跟踪记录： 记录修订事件及其根本原因。
4. 添加注释： 使用修订元数据标记更新的部分，以便后续审查时追踪其沿革。

# In context/plans/plan-data.md, add:

### T-DATA-005: Configure bounded connection pool
- **Status:** DONE (revised from manual fix a1b2c3d)
- **Cavekit:** R5 in cavekit-data.md
- **Files:** src/db/pool.ts
- **Acceptance criteria:**
  - [ ] Max pool size enforced
  - [ ] Idle timeout configured
  - [ ] Exhaustion handled gracefully

步骤 5：应用系统性提示词改进（如果发现模式）

如果缺陷反映的是一类反复出现的问题，而非个例，就应将修复提升到提示词层面，使其适用于所有领域：

以下迹象表明问题具有普遍模式：

• 同类缺陷已在多个模块中出现
• 缺口具有结构性（例如，没有任何规范涉及资源限制）
• 缺少验证关卡，导致问题未被拦截

系统性修复示例：

# In prompt 003, add to the validation section:

## Resource Management Validation
For every external resource integration, verify:
- [ ] Connection or handle limits are bounded and configurable
- [ ] Idle resources are cleaned up on a timeout
- [ ] Exhaustion scenarios return actionable errors
- [ ] Resource lifecycle is covered by tests under load

步骤 6：验证并固化

针对更新后的套件运行迭代循环，证明仅凭套件就能产生该修复，然后生成回归测试，以防问题再次出现：

# Proof step: remove the manual fix and re-run from specs
git stash  # temporarily remove the manual fix
iteration-loop context/prompts/003-generate-impl-from-plans.md -n 5 -t 1h
# Verify the fix appears in the generated implementation

# If it does NOT, the cavekit update is insufficient -- return to Step 3

验证通过后，创建回归测试：

# Generate tests targeting the updated cavekit
{TEST_COMMAND} --cavekit context/kits/cavekit-data.md

# Or manually create a regression test
# tests/db/connection-pool-limits.test.ts

回归测试应：

• 与步骤 3 中的验收标准直接对应
• 在修复被撤销时失败
• 从今往后作为标准测试套件的一部分运行

---

3. 修订分析（自动化）

修订分析通过检查近期 git 历史记录，实现步骤 2 至 4 的自动化。

3.1 对提交进行分类

分析近期提交，并对每个提交进行分类：

分类	含义	操作
手动修复	人工或交互式 Agent 修复了 Bug	追溯到 cavekit——这是一个修订目标
迭代循环	自动迭代循环做出了更改	无需操作——这是系统按预期运行
基础设施	构建配置、CI、工具方面的更改	无需操作——与 cavekit 无关

分类方法：

• 迭代循环会话产生的提交具有可预测的模式（自动生成的提交消息、批量更改）
• 手动修复通常是针对单一问题的专注提交，且提交消息描述明确
• 基础设施更改涉及配置文件、构建脚本、CI 流水线

3.2 分析每项手动修复

对于每个归类为手动修复的提交，确定：

## Commit: abc1234 "Fix: auth token not refreshing on 401"

### WHAT changed
- File: src/auth/client.ts
- Function: handleApiResponse()
- Behavior: Added 401 detection and token refresh logic

### WHY it was wrong
- The auth module did not handle 401 responses
- Tokens would expire and never refresh, causing cascading auth failures

### RULE (invariant that should have been specified)
- "Authentication tokens must be refreshed automatically on 401 responses"

### LAYER (which context file should have caught this)
- cavekit-auth.md: Missing requirement for error-based token refresh
- plan-auth.md: No task for 401 handling

### Cavekit Implications
- Add R7 to cavekit-auth.md: Token Refresh on Authentication Failure
- Add T-AUTH-007 to plan-auth.md: Implement token refresh on 401

3.3 发现受影响的计划文件

动态发现哪些计划文件负责管理已更改的源代码路径：

Changed file: src/auth/client.ts
  -> Matches pattern: src/auth/*
  -> Governed by: plan-auth.md
  -> Cavekit: cavekit-auth.md

Changed file: src/data/api.ts
  -> Matches pattern: src/data/*
  -> Governed by: plan-data.md
  -> Cavekit: cavekit-data.md

使用文件所有权表（来自提示词）或目录约定，将源文件映射到计划文件或 cavekit 文件。

3.4 更新上下文文件

针对每个修订目标，更新：

1. Cavekit 文件： 添加缺失的要求及验收标准
2. 计划文件： 添加引用新要求的任务
3. Impl 跟踪： 记录修订事件

# In context/impl/impl-auth.md, add:

## Revision Log
| Date | Commit | Issue | Cavekit Update | Plan Update |
|------|--------|-------|-------------|-------------|
| 2026-03-14 | abc1234 | 401 not handled | R7 added to cavekit-auth.md | T-AUTH-007 added |

3.5 运行测试

更新上下文文件后，运行测试套件以验证没有破坏任何内容：

{BUILD_COMMAND}
{TEST_COMMAND}

3.6 生成回归测试

针对每个修订目标，生成一个回归测试，该测试：

• 测试新 cavekit 要求中的具体验收标准
• 如果修复被回退，测试将失败
• 后续纳入标准测试套件

---

4. 模式与反模式

流程运行正常的迹象

模式	观察到的现象
人工干预逐渐减少	每个迭代周期都需要更少的人工修复，因为 kits 捕获了更多真实情况
每次修复覆盖更广的 cavekit 范围	单次修订事件会添加可阻止一整类相关缺陷的约束，而不只是一个缺陷
跨领域预防	针对某个模块中的 Bug 所做的提示词级调整，可防止类似 Bug 出现在其他模块中
自主复现能力	更新 cavekit 后，迭代循环能够独立地产生与人工修复相同的修正

警示信号与补救措施

反模式	症状	补救措施
仅修改代码	同一类缺陷在多个迭代中反复出现	遵循完整的 6 步流程；切勿在第 1 步修复代码后就停止
过于具体的 cavekit 补充内容	每次修订只能防止遇到的确切 Bug，稍有变化就会漏网	将 RULE 表述为通用不变量，而不是狭窄的补丁
跳过验证	kits 已更新，但无人确认迭代循环能否独立复现修复	始终执行第 6 步；无法驱动正确生成的 cavekit 并不完整
脆弱的过度规范	kits 规定了实现细节，导致轻微重构也会造成破坏	约束 WHAT 和 WHY；HOW 留给实现
修订债务累积	一批手动修复未追溯，且随着每个冲刺不断增加	设定固定周期（例如每次迭代结束时）清理积压；债务会迅速累积

---

5. 何时不需要修订

并非每次代码修复都需要修订：

• 偶发的环境问题（配置错误、缺少依赖项）——这些属于基础设施问题，而不是 cavekit 的缺口
• 拼写错误和格式问题——无关紧要的修复，并不意味着缺少需求
• 原型开发期间的探索性更改——套件仍在形成中
• 不会改变行为的性能优化——除非性能是 cavekit 的要求

**经验法则：**如果迭代循环有可能再次引入该错误，就进行修订；如果没有，就跳过。

---

6. 修订与收敛

修订会直接改善收敛：

Iteration 1: 350 lines changed, 8 manual fixes needed
  -> Revise all 8 fixes into kits
Iteration 2: 140 lines changed, 3 manual fixes needed
  -> Revise 3 fixes
Iteration 3: 30 lines changed, 1 manual fix needed
  -> Revise 1 fix
Iteration 4: 10 lines changed, 0 manual fixes needed
  -> Convergence achieved

每个修订周期都会完善套件，让迭代循环经过更少轮次就能稳定在可行的解决方案上。如果收敛没有改善，最可能的原因是手动修复没有追溯到套件。

**收敛停滞，同时仍在持续手动修复，是存在修订债务的明确信号。**套件没有吸收以往纠正中总结的经验，因此循环会不断生成有缺陷的输出，需要人工修复。

---

7. 与其他 Cavekit 技能的集成

• **收敛监控：**使用 ck:convergence-monitoring 检测手动修复是在减少（良好）还是增加（修订债务）。
• **提示词流水线：**修订可能会触发提示词更改（步骤 6），进而影响 ck:prompt-pipeline 的设计。
• **验证优先设计：**更严格的验证关卡能更早发现问题，减少修订需求。
• **差距分析：**系统化的差距分析（/ck:scan）可主动识别修订目标，而不是等到出现错误才处理。

---

交叉引用

• **收敛模式：**参见 references/convergence-patterns.md，了解修订如何推动收敛。
• **提示词流水线：**参见 ck:prompt-pipeline 技能，了解提示词 006（重写模式）如何实现自动修订。
• **实现跟踪：**参见 ck:impl-tracking 技能，了解实现跟踪文档中的修订日志格式。
• **验证关卡：**参见 ck:validation-first 技能，了解在问题需要修订前将其发现的验证层。