diff --git a/.takt/facets/instructions/aggregate-feedback.md b/.takt/facets/instructions/aggregate-feedback.md index 704e35a7..1141cacc 100644 --- a/.takt/facets/instructions/aggregate-feedback.md +++ b/.takt/facets/instructions/aggregate-feedback.md @@ -9,6 +9,7 @@ - 知見がない場合は「提案なし」で正常終了する。無理に提案を捻出しない - 重複する提案はマージし、根拠 (rationale) を統合する - Tier 1 を最優先で提案する。Tier 3 のみの提案は価値が低い +- **各提案には Severity / Frequency / Adoption Risk / Recommendation を必須で評価する** (順位 58 / PR #106 評価セッションで合意) --- @@ -43,23 +44,96 @@ PR タイトルが context に含まれていない場合は、レポート内 1. **重複検出**: 同じ `Target` + 似た `Description` の提案はマージする 2. **根拠統合**: マージした提案の `Rationale` カラムには複数ソース (PR diff / session / prepush) を併記する 3. **Tier 並び**: 最終リストは Tier 1 → Tier 2 → Tier 3 の順 -4. **品質フィルタ**: 以下の提案は除外する +4. **品質フィルタ**: 以下の提案は除外する (Recommendation 列での `❌ 却下` と区別: ここで除外するのは「最初から表に乗せない」レベル) - 一般的なベストプラクティスの押し付け (具体的根拠がない) - すでに hooks-config.toml / custom-lint-rules.toml に存在するルール (Read で確認可能) - 対象ファイルが read-only zone (`.takt/`, `docs/adr/`, `templates/`) のみで具体的な編集箇所が示せないもの + - **判定方法**: `Target` 列に含まれるパスを基準に、**編集可能 (write zone) なパスが一つでも含まれる場合は除外しない** + - 逆に、`Target` が上記 read-only zone に**完全に限定**され、かつ編集可能な行/差分/コードブロックが示されない提案のみ除外する -## Phase 2: 最終レポート生成 +## Phase 2: 各提案に Severity / Frequency / Adoption Risk / Recommendation を付与 -以下の Required output 形式で `feedback-report.md` を出力する。 +各提案について、以下の rubric に基づいて 4 つの判定列を埋める。**この評価は採用判定をユーザーへ委ねるための材料**であり、AI が判定を独占するわけではない。明確に判定できない場合は中庸な値 (`Medium` / `🤔 様子見`) を選び、`Rationale` で不確実性を明示する。 -### Source 表記の凡例 +### Severity rubric -`Rationale` に書く `Source` の表記: -- `PR diff` — PR の差分から抽出 -- `Review comment` — PR レビューコメントから抽出 -- `Session` — セッション transcript から抽出 -- `Prepush:simplicity` / `Prepush:security` — pre-push-review の各レポートから抽出 -- 複数ソースは `;` 区切り (例: `PR diff; Session`) +| 値 | 該当する状況 | +|---|---| +| `Critical` | data loss / security 脆弱性 / 致命的バグ / production-down リスクの再発防止 | +| `High` | 機能 bug / silent failure / data integrity 違反 | +| `Medium` | silent degrade / UX 低下 / 開発体験劣化 / token 浪費 | +| `Low` | style / micro-optimization / 局所改善 / 命名 convention | + +### Frequency rubric + +| 値 | 該当する状況 | +|---|---| +| `High` | 複数 PR で観測済み / systemic pattern (3 PR 以上で言及あり) | +| `Medium` | 1 PR + 類似コードベースで再発見込みあり / 過去 1-2 PR で関連事象 | +| `Low` | 本 PR のみで観測 / 局所現象 | +| `Very Low` | extreme edge case / 単発の特殊事情 | + +### Effort rubric + +実装に要する工数。Recommendation 判定の入力として使うため、許容値を以下に固定する: + +| 値 | 該当する状況 | +|---|---| +| `XS` | 文言/設定の微修正、単一箇所の変更、テストなしで完結 (1-数行) | +| `S` | 単一ファイルの局所変更、テスト追加含めて半日以内で完結 (数行〜数十行) | +| `M` | 複数ファイルにまたがる変更、テスト + 動作確認で 1-2 日 (数十〜数百行) | +| `L` | アーキテクチャレベルの変更、複数 PR / 新規モジュール追加、design doc 推奨 | +| `XL` | 大規模リファクタ / 機構新設、専用 design doc + 段階的 rollout 必須 | + +### Adoption Risk rubric + +採用時に発生しうるリスクや負債を **1-2 語の短いタグ** で記述する。よく出る選択肢: + +- `None` — リスクなし、採用に伴う overhead が極小 +- `既存ルール重複` — 既存 ADR / hooks / facets と内容が overlap +- `過剰一般化` — 局所事象を universal rule に昇格させるリスク +- `NLP 必要` — コメントと実装の照合等、自然言語処理が必要で実装非現実的 +- `OS 依存` — Windows / Unix 等の差異で挙動が変わる +- `false positive リスク` — regex / pattern matching で誤検出が高頻度に発生 +- `reviewer instruction 肥大化` — facet prompt に追加することで attention drift 再発リスク +- `派生プロジェクト deploy コスト` — techbook-ledger / auto-review-fix-vc 等への展開負荷 +- `takt test infra 未調査` — takt 側のテスト機構の有無で Effort が大きく変動 +- `runner 複雑化` — Rust 実装の cli-* に parse logic 等を追加する複雑度 + +該当しないものは独自に短いタグを作ってよい (1-2 語、英日混在可)。 + +### Recommendation rubric (必須) + +3 種類のいずれかを必ず emit する。条件式は **括弧で評価順を明示**しているので、人間 / AI どちらの解釈でもズレない: + +| 値 | 該当する状況 | +|---|---| +| `✅ 採用` | `(Effort ∈ {XS, S, M})` AND `(Severity ∈ {Medium, High, Critical} OR Frequency ∈ {Medium, High})` AND `(Adoption Risk が weak)` | +| `🤔 様子見` | 採用根拠は弱いが将来発生時に再評価したい (一般原則 / 不確実性高 / dogfood トリガ待ち / Severity 高だが Frequency Very Low 等)。✅ にも ❌ にも振り切れない場合の中庸 | +| `❌ 却下` | `(Frequency ∈ {Low, Very Low} AND Effort ∈ {L, XL})` OR `(Adoption Risk が strong)` OR `(実害観測前の preventive over-engineering)` | + +**Adoption Risk の「weak / strong」定義** (上記条件式で参照): + +- `weak` (✅ 側): `None` または採用に伴う overhead が極小なタグ。例: `派生プロジェクト deploy コスト` 単独 (= 単純な配布作業) +- `strong` (❌ 側): 採用 = 別の問題を生むタグ。例: `既存ルール重複` / `過剰一般化` / `NLP 必要` / `false positive リスク` / `reviewer instruction 肥大化` / `runner 複雑化` / `takt test infra 未調査` +- 中間 (= 🤔 様子見側に倒す): 上記いずれにも明確に分類できないタグ、または複数タグの組み合わせで weak/strong の境界が不明瞭な場合 + +### Rationale (拡張) + +従来の `Source` 表記 + **採用判断の根拠** を 1-2 文で記述する。Format: + +```text +; <採用根拠> +``` + +- Source 凡例: `PR diff` / `Review comment` / `Session` / `Prepush:simplicity` / `Prepush:security` (複数は `;` 区切りで 1 つの Source に集約してから採用根拠を続ける) +- 採用根拠: なぜ Severity × Frequency × Effort × Adoption Risk から Recommendation に至ったか + +例: + +- 採用 例: `PR diff; Session; collect_all_violations の MAX_VIOLATIONS contract を test 化、将来の lint 追加時の regression 防止網。Effort S かつ Frequency Medium` +- 様子見 例: `Session; Honesty constraint で抑制中、実観測 0 件、dogfood で虚偽申告観測後に着手` +- 却下 例: `Session; 1 観測の局所 artifact、汎用 regex は英語固有名詞・略語で誤検出確実、ROI 不見合い` --- @@ -76,23 +150,24 @@ PR タイトルが context に含まれていない場合は、レポート内 #### Tier 1: Hooks/Linter 改善 (決定論的防止) -| # | Type | Description | Target | Effort | Rationale (Source) | -|---|------|-------------|--------|--------|--------------------| -| 1 | custom_lint_rule | ... | .claude/custom-lint-rules.toml | Low | PR diff; Session | +| # | Type | Description | Target | Severity | Frequency | Effort | Adoption Risk | Recommendation | Rationale | +|---|------|-------------|--------|----------|-----------|--------|---------------|----------------|-----------| +| 1 | custom_lint_rule | ... | .claude/custom-lint-rules.toml | Medium | High | S | None | ✅ 採用 | PR diff; Session; ... | #### Tier 2: テスト/自動化 -| # | Type | Description | Target | Effort | Rationale (Source) | -|---|------|-------------|--------|--------|--------------------| +| # | Type | Description | Target | Severity | Frequency | Effort | Adoption Risk | Recommendation | Rationale | +|---|------|-------------|--------|----------|-----------|--------|---------------|----------------|-----------| #### Tier 3: ドキュメント/ルール -| # | Type | Description | Target | Effort | Rationale (Source) | -|---|------|-------------|--------|--------|--------------------| +| # | Type | Description | Target | Severity | Frequency | Effort | Adoption Risk | Recommendation | Rationale | +|---|------|-------------|--------|----------|-----------|--------|---------------|----------------|-----------| ### 次のアクション -- ユーザーがレポートを確認後、UserPromptSubmit hook (L2 recovery) または直接的な指示で実装へ進む +- ユーザーがレポートを確認後、Recommendation 列を参考に採用判断を下す (✅ 採用は基本採用、🤔 様子見は dogfood トリガ次第、❌ 却下は不要) +- 採用された提案は `docs/todo.md` 系列に登録するか直接実装へ進む - このレポートは `.claude/feedback-reports/.md` に保存される (`.gitignore` 除外、内部 artifact) ``` diff --git a/docs/todo.md b/docs/todo.md index 5afbaa17..7c82514a 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -70,7 +70,6 @@ | 55 | 💎 Tier 3 | **config 拡張 + SessionStart catch-up (Bundle b PR-3) ★ Bundle b** | todo5.md | S | 順位 53 / 54 land 後 (固定値の `monitor.toml` 化 + Claude Code 不在時に発火した wakeup を SessionStart で catch-up、AI 不在時の silent loss 防止) | | 56 | 🔧 Tier 2 | **comment-lint hook test 拡充 (PR #104 T2-1+T2-2 bundle)** | todo5.md | S | なし (UTF-8 multi-byte 5 パターン + block comment boundary 6 パターンを `locate_string_line_ranges` / `span_overlaps_ranges` の回帰テストとして体系化、PR #104 Critical/Minor fix の固定化) | | 57 | 🔧 Tier 2 | **Aggregation cap integration test (PR #105 T2-1 採用)** | todo5.md | S | なし (`collect_all_violations` の MAX_VIOLATIONS contract を test 化、将来の lint 追加時に `truncate(MAX)` 削除 regression を防止する explicit 安全網) | -| 58 | 🔧 Tier 2 | **post-merge-feedback findings table format 拡張 (Severity / Frequency / Adoption Risk / Recommendation を必須列化)** | todo5.md | S | なし (PR #105 評価で Effort + Rationale のみでは AI 採用判定が安定しないことを確認、rubric ベースの format 固定化で評価コスト削減 + 卻下根拠の言語化) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 diff --git a/docs/todo5.md b/docs/todo5.md index 4ed1b67c..09463eee 100644 --- a/docs/todo5.md +++ b/docs/todo5.md @@ -399,67 +399,3 @@ - 順位 56 (PR #104 T2-1+T2-2 test 拡充) と同 PR で bundle するか別 PR とするか。両者とも test additions、同ファイル同 test module で scope clean、bundle 推奨。 ---- - -### post-merge-feedback findings table format 拡張 (Severity / Frequency / Adoption Risk / Recommendation 必須化) - -> **動機**: PR #105 post-merge-feedback の評価セッションで、現フォーマット (Effort + Rationale のみ) では AI が採用判定根拠を systematically 落とすことが確認された。8 件中 1 件のみ採用 (T2-1) という評価をユーザーが下せたのは、AI が手動で各 finding の Severity / Frequency / 実装コスト / 過剰一般化リスクを補完したから。format に組み込めば AI 出力が rubric ベースで安定し、ユーザーの審査時間を削減できる。 -> -> **本タスクの位置づけ**: PR #105 評価セッションで合意。post-merge-feedback workflow の aggregate facet を拡張し、AI に rubric を強制することで卻下根拠の言語化と採用判定の安定化を図る。 -> -> **参照**: PR #105 評価セッション (本対話)、`.claude/feedback-reports/105.md` の現フォーマット、~/.claude/.takt/facets/ または equivalent (実際の facet 配置先は要調査) -> -> **実行優先度**: 🔧 **Tier 2** — Effort S。facet prompt 1-2 セクションの修正、派生プロジェクトへの展開も含む。 - -#### 設計決定 (案) - -##### 拡張する table 列 - -| 既存 | 拡張後 | -|---|---| -| `# / Type / Description / Target / Effort / Rationale` | `# / Type / Description / Target / Severity / Frequency / Effort / Adoption Risk / Recommendation / Rationale` | - -##### 各列の rubric (facet instructions に明記) - -- **Severity**: - - `Critical`: data loss / security / 致命的バグの再発防止 - - `High`: 機能 bug / silent failure / data integrity - - `Medium`: silent degrade / UX 低下 / 開発体験劣化 - - `Low`: style / micro-optimization / 局所改善 -- **Frequency** (再発リスク): - - `High`: 複数 PR で観測済 / systemic pattern - - `Medium`: 1 PR + 類似コードベースで再発見込み - - `Low`: single observation / 局所 -- **Adoption Risk** (採用時のリスク要素を 1-2 語で記述): - - 例: `既存ルール重複` / `過剰一般化` / `NLP 必要` / `OS 依存` / `派生プロジェクト deploy コスト` / `false positive リスク` / `None` -- **Recommendation** (必須付記): - - `✅ 採用`: 高コスパ判定 (Effort=S かつ Severity Medium+ または Frequency Medium+ かつ 根本原因が適切) - - `🤔 様子見`: 採用根拠は弱いが将来発生時に再評価したい (一般原則 / 不確実性高) - - `❌ 卻下`: 頻度 Low かつ 実装コスト High、または Adoption Risk が overlap / 過剰一般化 / NLP 必要 / 重複ルール -- **Rationale** (採用 / 卻下の根拠を必ず記述): - - なぜ Severity × Frequency × Effort × Adoption Risk から Recommendation に至ったかを 1-2 文で - -##### facet 配置の調査 - -- post-merge-feedback の aggregate step は takt facet として実装されている想定 -- 実際の prompt 配置: `~/.claude/.takt/facets/post-merge-feedback/*.md` か `.claude/feedback-reports/` か要調査 -- 派生プロジェクト (techbook-ledger / auto-review-fix-vc) は Python ベースで facet 配置が異なる可能性 - -#### 作業計画 - -- [ ] post-merge-feedback aggregate facet の実体を grep / find で特定 (`takt facet` / `post-merge` 等で検索) -- [ ] facet prompt の table format 部分を改訂 (列追加 + rubric 説明文) -- [ ] sample output (この PR の評価結果を例として facet に inline) を追加 -- [ ] dogfood: 次の post-merge-feedback で新フォーマットが出力されること確認 -- [ ] 派生プロジェクトの同 facet にも展開 (Python ベース facet があれば独立に対応) -- [ ] 本 todo5.md エントリを削除 - -#### 完了基準 - -- 次回以降の post-merge-feedback で 9 列フォーマット (Severity / Frequency / Adoption Risk / Recommendation 必須) が出力される -- ユーザーの採用判定セッションで「AI が rubric を埋めていない」ことに起因する補完作業が消滅 - -#### 詰まっている箇所 - -- aggregate facet が AI prompt なのか deterministic template なのか要調査。前者なら自然言語ルール追加で済むが、後者ならコード変更が必要 -- rubric の閾値 (Severity Medium 等) が AI 判定で揺れる可能性 → sample output を facet に inline することで cluster 化を狙うが、初回 dogfood で false positive / negative の頻度を観測する必要あり