cavekit-revision
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRevision: Tracing Bugs Back to Kits
修订：将漏洞追溯至Kits
In Cavekit, revision means tracing a production defect upstream through the cavekit chain until you find the gap that allowed it. In practice, when the built software has bugs or gaps, you trace the issue back to the kits and prompts and fix at the source -- not just in code.
Key insight: When a fix lives only in code with no corresponding cavekit update, the next iteration loop may reintroduce the same defect. The goal is that kits plus the iteration loop can reproduce any fix autonomously.
在Cavekit中，修订指的是沿着cavekit链向上追溯生产环境中的缺陷，直到找到导致问题的漏洞。实际操作中，当构建的软件存在漏洞或缺陷时，你需要将问题追溯至kits和prompts并从源头修复——而不只是修改代码。
核心洞察： 如果修复仅存在于代码中而未同步更新cavekit，下一次迭代循环可能会重新引入相同的缺陷。目标是让kits加上迭代循环能够自主复现任何修复方案。
1. Why Revision Matters
1. 修订的重要性
Without revision, every bug fix is a one-off patch. The next time the iteration loop runs, it may reintroduce the bug because nothing in the kits or plans prevents it.
With revision:
- Bug fixes become cavekit improvements that persist across all future iterations
- The iteration loop becomes self-correcting -- it learns from every manual intervention
- Kits become progressively more complete over time
- The gap between "what kits describe" and "what works" shrinks monotonically
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如果不进行修订，每一次漏洞修复都是一次性补丁。下一次迭代循环运行时，可能会重新引入该漏洞，因为kits或计划中没有任何内容能阻止它。
进行修订后：
- 漏洞修复成为cavekit改进，并在未来所有迭代中持续生效
- 迭代循环变得自我修正——它会从每一次人工干预中学习
- Kits会随着时间推移逐步完善
- "kits描述的内容"与"实际可行的内容"之间的差距持续缩小
不进行修订:
发现漏洞 -> 修复代码 -> 下一次迭代可能再次出现漏洞
进行修订:
发现漏洞 -> 修复代码 -> 更新cavekit -> 重新运行迭代循环 -> 仅通过kits即可生成修复方案2. The 6-Step Revision Process
2. 六步修订流程
This is the complete process for tracing a bug back to its cavekit-level root cause and closing the loop.
这是将漏洞追溯至其cavekit层面根本原因并闭环的完整流程。
Step 1: Identify and Fix the Defect
步骤1：识别并修复缺陷
Locate the bug -- whether through manual testing, automated failures, user reports, or monitoring alerts -- and resolve it through normal debugging. This produces a working code change, but the job is far from done: until the underlying cavekit gap is closed, this fix is fragile.
bash
undefined定位漏洞——无论是通过手动测试、自动化测试失败、用户反馈还是监控告警——并通过常规调试解决问题。这会产生有效的代码变更，但任务远未完成：除非填补底层的cavekit漏洞，否则这个修复是脆弱的。
bash
undefinedThe fix produces commits that we will analyze
修复产生的提交将被我们分析
git log --oneline -5
git log --oneline -5
a1b2c3d Fix: connection pool exhaustion under concurrent load
a1b2c3d Fix: connection pool exhaustion under concurrent load
e4f5g6h Fix: missing rate limit headers in API responses
e4f5g6h Fix: missing rate limit headers in API responses
undefinedundefinedStep 2: Analyze What the Cavekit Missed
步骤2：分析Cavekit遗漏的内容
This is the pivotal step. Ask: "Where in the cavekit chain did this requirement slip through?"
Break the analysis into five dimensions:
- WHAT changed (files, functions, observable behavior)
- WHY it was wrong (which assumption proved false)
- VISUAL — does this fix change visual appearance (CSS, styling, layout)? If yes, check whether DESIGN.md covers the pattern. A missing design pattern is a design system gap that should be fixed alongside the cavekit gap.
- The RULE (the invariant that should have been stated)
- The LAYER (which cavekit, plan, or prompt should have contained this)
Example analysis:
markdown
undefined这是关键步骤。问自己："这个需求在cavekit链的哪个环节被遗漏了？"
从五个维度展开分析：
- 变更内容（文件、函数、可观察行为）
- 错误原因（哪个假设被证明不成立）
- 视觉层面——该修复是否改变了视觉外观（CSS、样式、布局）？如果是，检查DESIGN.md是否涵盖了该模式。缺失的设计模式是设计系统漏洞，应与cavekit漏洞一同修复。
- 规则（本应明确的不变量）
- 层级（本应包含该内容的cavekit、计划或prompt）
分析示例：
markdown
undefinedRevision Analysis: Database Connection Pooling
修订分析：数据库连接池
WHAT changed: Added pool size limits and idle timeout in
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
src/db/pool.tsundefined变更内容: 在中添加了池大小限制和空闲超时设置
错误原因: 数据层cavekit假设连接数不受限制；在负载情况下，一旦达到服务器端限制，数据库会拒绝新连接
规则: "数据库模块必须配置有界连接池，其空闲超时和最大连接数限制需与部署目标匹配"
层级: cavekit-data.md（未提及池配置），plan-data.md（没有池调优任务）
Cavekit影响: 在cavekit-data.md中添加需求R5，涵盖连接池设置
src/db/pool.tsundefinedStep 3: Update the Cavekit
步骤3：更新Cavekit
Add the missing requirement or constraint to the appropriate cavekit file. Focus on acceptance criteria that are concrete enough for the iteration loop to act on:
markdown
undefined将缺失的需求或约束添加到相应的cavekit文件中。重点关注足够具体的验收标准，以便迭代循环能够据此执行：
markdown
undefinedIn context/kits/cavekit-data.md, add:
在context/kits/cavekit-data.md中添加:
R5: Database Connection Pool Configuration
R5: 数据库连接池配置
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)
undefined描述: 数据库模块必须使用有界连接池
并配置可调整的限制，以防止负载情况下的资源耗尽。
验收标准:
- 最大池大小可配置，且默认值合理
- 空闲连接在可配置的超时后被回收
- 池耗尽时返回清晰的错误而非无限挂起
- 从池返回连接前运行连接健康检查 依赖项: R1（数据库客户端设置），R2（环境配置）
undefinedStep 4: Propagate Changes to Plans and Tracking
步骤4：将变更传播至计划与跟踪系统
Trace the cavekit update through every downstream context file:
- Identify affected plan files: Which plans govern the changed source paths?
- Update plans: Add or close tasks reflecting the new requirement.
- Update impl tracking: Record the revision event and its root cause.
- Annotate: Mark updated sections with revision metadata so future reviews can trace lineage.
markdown
undefined将cavekit更新追溯至所有下游上下文文件：
- 识别受影响的计划文件: 哪些计划管理着变更的源路径？
- 更新计划: 添加或关闭反映新需求的任务。
- 更新实现跟踪: 记录修订事件及其根本原因。
- 标注: 为更新的部分添加修订元数据，以便未来评审时可追溯 lineage。
markdown
undefinedIn context/plans/plan-data.md, add:
在context/plans/plan-data.md中添加:
T-DATA-005: Configure bounded connection pool
T-DATA-005: 配置有界连接池
- 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
undefined- 状态: 已完成（从手动修复a1b2c3d修订而来）
- Cavekit: cavekit-data.md中的R5
- 文件: src/db/pool.ts
- 验收标准:
- 最大池大小已生效
- 空闲超时已配置
- 耗尽情况已被妥善处理
undefinedStep 5: Apply Systemic Prompt Improvements (If Pattern Detected)
步骤5：应用系统性Prompt改进（若检测到模式）
When the defect represents a recurring class of problem rather than a one-off, elevate the fix to the prompt level so it applies across all domains:
Signs you are looking at a pattern:
- The same category of bug has surfaced in more than one module
- The gap is structural (e.g., no specs anywhere address resource limits)
- A missing validation gate allowed the issue through
Example systemic fix:
markdown
undefined当缺陷代表一类反复出现的问题而非一次性问题时，将修复提升至prompt层面，使其适用于所有领域：
模式识别迹象:
- 同一类漏洞在多个模块中出现
- 漏洞是结构性的（例如，没有任何规范涉及资源限制）
- 缺失的验证环节导致问题产生
系统性修复示例:
markdown
undefinedIn prompt 003, add to the validation section:
在prompt 003的验证部分添加:
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
undefined对于每个外部资源集成，验证:
- 连接或句柄限制是有界且可配置的
- 空闲资源在超时后被清理
- 耗尽场景返回可操作的错误
- 资源生命周期在负载下有测试覆盖
undefinedStep 6: Verify and Lock In
步骤6：验证并固化修复
Run the iteration loop against the updated kits to prove the fix emerges from kits alone, then generate regression tests to prevent future recurrence:
bash
undefined针对更新后的kits运行迭代循环，证明仅通过kits即可生成修复方案，然后生成回归测试以防止未来再次出现该问题：
bash
undefinedProof 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
git stash # 临时移除手动修复
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
如果未包含，则cavekit更新不充分——返回步骤3
Once verified, create regression tests:
```bash
验证通过后，创建回归测试：
```bashGenerate tests targeting the updated cavekit
针对更新后的cavekit生成测试
{TEST_COMMAND} --cavekit context/kits/cavekit-data.md
{TEST_COMMAND} --cavekit context/kits/cavekit-data.md
Or manually create a regression test
或手动创建回归测试
tests/db/connection-pool-limits.test.ts
tests/db/connection-pool-limits.test.ts
The regression tests should:
- Map directly to the acceptance criteria from Step 3
- Fail if the fix is reverted
- Run as part of the standard test suite going forward
---
回归测试应：
- 直接映射到步骤3中的验收标准
- 若修复被回退则测试失败
- 作为标准测试套件的一部分持续运行
---3. Revision Analysis (Automated)
3. 自动化修订分析
The revision analysis automates Steps 2-4 by examining recent git history.
修订分析通过检查最近的git历史自动完成步骤2-4。
3.1 Classify Commits
3.1 提交分类
Analyze recent commits and classify each as:
| Classification | Meaning | Action |
|---|---|---|
| Manual fix | Human or interactive agent fixed a bug | Trace back to cavekit -- this is a revision target |
| Iteration loop | Automated iteration loop made the change | No action -- this is the system working as intended |
| Infrastructure | Build config, CI, tooling changes | No action -- not cavekit-related |
How to classify:
- Commits from iteration loop sessions have predictable patterns (automated commit messages, batch changes)
- Manual fixes are typically single-issue, focused commits with descriptive messages
- Infrastructure changes touch config files, build scripts, CI pipelines
分析最近的提交并将每个提交分类：
| 分类 | 含义 | 操作 |
|---|---|---|
| 手动修复 | 人类或交互式agent修复了漏洞 | 追溯至cavekit——这是修订目标 |
| 迭代循环 | 自动化迭代循环做出的变更 | 无需操作——系统按预期运行 |
| 基础设施 | 构建配置、CI、工具变更 | 无需操作——与cavekit无关 |
分类方法:
- 迭代循环会话的提交具有可预测的模式（自动化提交信息、批量变更）
- 手动修复通常是针对单一问题的聚焦提交，带有描述性信息
- 基础设施变更涉及配置文件、构建脚本、CI流水线
3.2 Analyze Each Manual Fix
3.2 分析每个手动修复
For each commit classified as a manual fix, determine:
markdown
undefined对于每个分类为手动修复的提交，确定：
markdown
undefinedCommit: abc1234 "Fix: auth token not refreshing on 401"
提交: 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
- 文件: src/auth/client.ts
- 函数: handleApiResponse()
- 行为: 添加了401检测和令牌刷新逻辑
WHY it was wrong
错误原因
- The auth module did not handle 401 responses
- Tokens would expire and never refresh, causing cascading auth failures
- 认证模块未处理401响应
- 令牌过期后不会刷新，导致连锁认证失败
RULE (invariant that should have been specified)
规则（本应明确的不变量）
- "Authentication tokens must be refreshed automatically on 401 responses"
- "认证令牌必须在401响应时自动刷新"
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-auth.md: 缺失基于错误的令牌刷新需求
- plan-auth.md: 没有处理401的任务
Cavekit Implications
Cavekit影响
- Add R7 to cavekit-auth.md: Token Refresh on Authentication Failure
- Add T-AUTH-007 to plan-auth.md: Implement token refresh on 401
undefined- 在cavekit-auth.md中添加R7：认证失败时的令牌刷新
- 在plan-auth.md中添加T-AUTH-007：实现401时的令牌刷新
undefined3.3 Discover Affected Plan Files
3.3 发现受影响的计划文件
Dynamically discover which plan files govern the changed source paths:
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.mdUse file ownership tables (from prompts) or directory conventions to map source files to plan/cavekit files.
动态发现哪些计划文件管理着变更的源路径：
变更文件: src/auth/client.ts
-> 匹配模式: src/auth/*
-> 由以下文件管理: plan-auth.md
-> Cavekit: cavekit-auth.md
变更文件: src/data/api.ts
-> 匹配模式: src/data/*
-> 由以下文件管理: plan-data.md
-> Cavekit: cavekit-data.md使用文件归属表（来自prompts）或目录约定将源文件映射到计划/cavekit文件。
3.4 Update Context Files
3.4 更新上下文文件
For each revision target, update:
- Cavekit file: Add missing requirement with acceptance criteria
- Plan file: Add task referencing the new requirement
- Impl tracking: Record the revision event
markdown
undefined针对每个修订目标，更新：
- Cavekit文件: 添加带有验收标准的缺失需求
- 计划文件: 添加引用新需求的任务
- 实现跟踪: 记录修订事件
markdown
undefinedIn context/impl/impl-auth.md, add:
在context/impl/impl-auth.md中添加:
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 |
undefined| 日期 | 提交 | 问题 | Cavekit更新 | 计划更新 |
|---|---|---|---|---|
| 2026-03-14 | abc1234 | 401未被处理 | cavekit-auth.md中添加R7 | 添加T-AUTH-007 |
undefined3.5 Run Tests
3.5 运行测试
After updating context files, run the test suite to verify nothing broke:
bash
{BUILD_COMMAND}
{TEST_COMMAND}更新上下文文件后，运行测试套件以验证未引入新问题：
bash
{BUILD_COMMAND}
{TEST_COMMAND}3.6 Generate Regression Tests
3.6 生成回归测试
For each revision target, generate a regression test that:
- Tests the specific acceptance criteria from the new cavekit requirement
- Would fail if the fix were reverted
- Is included in the standard test suite going forward
针对每个修订目标，生成回归测试，要求：
- 测试新cavekit需求中的具体验收标准
- 若修复被回退则测试失败
- 作为标准测试套件的一部分持续运行
4. Patterns and Anti-Patterns
4. 模式与反模式
Signs the process is working
流程正常运行的迹象
| Pattern | What You Observe |
|---|---|
| Declining manual intervention | Each iteration cycle requires fewer hand-applied fixes because kits capture more of the ground truth |
| Broader cavekit coverage per fix | A single revision event adds constraints that block an entire family of related defects, not just one |
| Cross-domain prevention | Prompt-level adjustments made after a bug in one module prevent analogous bugs from appearing in other modules |
| Autonomous reproducibility | After a cavekit update, the iteration loop independently produces the same correction that a human applied manually |
| 模式 | 观察到的现象 |
|---|---|
| 人工干预减少 | 每次迭代周期所需的手动修复更少，因为kits捕获了更多的真实需求 |
| 单次修复覆盖更广泛的cavekit | 一次修订事件添加的约束可以阻止一整类相关缺陷，而非仅单个漏洞 |
| 跨领域预防 | 一个模块出现漏洞后调整prompt，可防止其他模块出现类似漏洞 |
| 自主复现 | 更新cavekit后，迭代循环可独立生成与人工修复相同的修正方案 |
Warning signs and remedies
警告迹象与补救措施
| Anti-Pattern | Symptom | Remedy |
|---|---|---|
| Code-only patches | The same category of defect resurfaces across iterations | Follow the full 6-step process; never stop after the code fix in Step 1 |
| Overly specific cavekit additions | Each revision prevents only the exact bug encountered, while slight variations slip through | Formulate the RULE as a general invariant, not a narrow patch |
| Skipping verification | Kits are updated but nobody confirms the iteration loop can reproduce the fix independently | Always execute Step 6; a cavekit that does not drive correct generation is incomplete |
| Brittle over-specification | Kits dictate implementation minutiae, causing breakage on minor refactors | Constrain the WHAT and WHY; leave the HOW to the implementation |
| Accumulated revision debt | A backlog of manual fixes sits un-traced, growing with each sprint | Set a cadence (e.g., end of each iteration) to clear the backlog; debt compounds quickly |
| 反模式 | 症状 | 补救措施 |
|---|---|---|
| 仅修复代码 | 同一类缺陷在迭代中反复出现 | 遵循完整的六步流程；绝不能在步骤1的代码修复后就停止 |
| Cavekit添加过于具体 | 每次修订仅能防止遇到的 exact 漏洞，而轻微变体仍会出现 | 将规则制定为通用不变量，而非狭窄的补丁 |
| 跳过验证 | 更新了kits，但未确认迭代循环能否独立复现修复方案 | 务必执行步骤6；无法驱动正确生成的cavekit是不完整的 |
| 过度规范导致脆弱 | Kits规定了实现细节，导致轻微重构就会出现故障 | 约束变更内容和原因；将实现方式留给具体实现环节 |
| 累积修订债务 | 大量未追溯的手动修复积压，随每个sprint增长 | 设置节奏（如每次迭代结束时）清理积压；债务会迅速累积 |
5. When NOT to Revise
5. 无需修订的场景
Not every code fix needs revision:
- One-off environment issues (wrong config, missing dependency) -- these are infrastructure, not cavekit gaps
- Typos and formatting -- trivial fixes that do not reflect missing requirements
- Exploratory changes during prototyping -- kits are still being formed
- Performance optimizations that do not change behavior -- unless performance is a cavekit requirement
Rule of thumb: If the iteration loop could plausibly reintroduce the bug, revise. If not, skip it.
并非所有代码修复都需要修订：
- 一次性环境问题（错误配置、缺失依赖）——这些属于基础设施问题，而非cavekit漏洞
- 拼写错误和格式问题——不反映需求缺失的微小修复
- 原型开发期间的探索性变更——kits仍在形成中
- 不改变行为的性能优化——除非性能是cavekit需求
经验法则: 如果迭代循环可能重新引入该漏洞，则进行修订。否则可跳过。
6. Revision and Convergence
6. 修订与收敛
Revision directly improves convergence:
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 achievedEvery revision cycle tightens the kits, so the iteration loop settles into a stable solution in fewer passes. If convergence is not improving, the most likely cause is that manual fixes are being applied without tracing them back to kits.
Stalled convergence paired with ongoing manual fixes is a clear sign of revision debt. The kits have not absorbed the lessons from past corrections, so the loop keeps regenerating flawed output that demands human repair.
修订直接提升收敛效果：
迭代1: 变更350行，需要8次手动修复
-> 将所有8次修复修订至kits
迭代2: 变更140行，需要3次手动修复
-> 修订3次修复
迭代3: 变更30行，需要1次手动修复
-> 修订1次修复
迭代4: 变更10行，无需手动修复
-> 实现收敛每次修订都会收紧kits，因此迭代循环只需更少的次数就能稳定到解决方案。如果收敛没有改善，最可能的原因是手动修复未被追溯至kits。
收敛停滞且持续需要手动修复是修订债务的明确信号。 Kits未吸收过去修正的经验，因此循环不断生成有缺陷的输出，需要人工修复。
7. Integration with Other Cavekit Skills
7. 与其他Cavekit技能的集成
- Convergence monitoring: Use to detect when manual fixes are decreasing (good) or increasing (revision debt).
ck:convergence-monitoring - Prompt pipeline: Revision may trigger changes to prompts (Step 6), which affects the design.
ck:prompt-pipeline - Validation-first design: Stronger validation gates catch issues earlier, reducing the need for revision.
- Gap analysis: Systematic gap analysis () identifies revision targets proactively, rather than waiting for bugs.
/ck:scan
- 收敛监控: 使用检测手动修复是减少（良好）还是增加（修订债务）。
ck:convergence-monitoring - Prompt流水线: 修订可能触发prompt变更（步骤6），这会影响的设计。
ck:prompt-pipeline - 优先验证设计: 更强的验证环节可更早发现问题，减少修订需求。
- 差距分析: 系统性差距分析()可主动识别修订目标，而非等待漏洞出现。
/ck:scan
Cross-References
交叉引用
- Convergence patterns: See for how revision drives convergence.
references/convergence-patterns.md - Prompt pipeline: See skill for how prompt 006 (rewrite pattern) implements automated revision.
ck:prompt-pipeline - Impl tracking: See skill for the revision log format in implementation tracking documents.
ck:impl-tracking - Validation gates: See skill for validation layers that catch issues before they require revision.
ck:validation-first
- 收敛模式: 请参阅了解修订如何驱动收敛。
references/convergence-patterns.md - Prompt流水线: 请参阅技能，了解prompt 006（重写模式）如何实现自动化修订。
ck:prompt-pipeline - 实现跟踪: 请参阅技能，了解实现跟踪文档中的修订日志格式。
ck:impl-tracking - 验证环节: 请参阅技能，了解可在需要修订前发现问题的验证层。
ck:validation-first