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チェーンのどこで、この要件が抜け落ちたのか？」

分析を次の5つの観点に分けます。

• 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 コミットを分類する

最近のコミットを分析し、それぞれを次のように分類します。

分類	意味	対応
手動修正	人間または対話型エージェントがバグを修正した	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. 実装の追跡： 改訂イベントを記録します

# 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. パターンとアンチパターン

プロセスが機能している兆候

パターン	観察される内容
手動介入の減少	キットが実態をより多く反映するため、反復サイクルごとに手作業で適用する修正が減ります
修正ごとの cavekit 対応範囲の拡大	1 回の改訂イベントで、単一の不具合だけでなく、関連する不具合の一群を防ぐ制約が追加されます
ドメインをまたいだ予防	あるモジュールのバグを受けて行ったプロンプトレベルの調整により、他のモジュールでも同様のバグの発生が防がれます
自律的な再現性	cavekit の更新後、反復ループが人間による手動修正と同じ修正を独立して生成します

警告サインと対処法

アンチパターン	症状	対処法
コードのみのパッチ	同じ種類の不具合が反復のたびに再発します	6 段階のプロセス全体を実施します。ステップ 1 のコード修正だけで終わらせてはいけません
cavekit への過度に具体的な追加	各改訂で遭遇した特定のバグしか防げず、わずかに異なるバグが発生します	RULE は狭い範囲のパッチではなく、一般的な不変条件として定式化します
検証の省略	キットは更新されますが、反復ループが修正を独立して再現できるか誰も確認しません	必ずステップ 6 を実行します。正しい生成を促せない cavekit は不完全です
壊れやすい過剰な指定	キットが実装の細部まで指定し、軽微なリファクタリングで問題が発生します	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 を参照してください。
• プロンプトパイプライン： プロンプト 006（書き換えパターン）による自動改訂の実装方法については、ck:prompt-pipeline スキルを参照してください。
• 実装の追跡： 実装追跡ドキュメントにおける改訂ログの形式については、ck:impl-tracking スキルを参照してください。
• 検証ゲート： 改訂が必要になる前に問題を検出する検証レイヤーについては、ck:validation-first スキルを参照してください。