[FB-NOTION-001] raw 値を toLowerCase() したまま fallback すると Jira / Markdown / JSON の原表記が壊れる | lookup は正規化しても、fallback は原入力の表記を保持する。resolveLabelEntry() では map lookup と fallback を分け、未登録値は元文字列をそのまま返す |
| [FB-STATE-DETAIL-001] template error のキャンセル後に stale guard がなく、遅延 reject が古いエラーを再表示する | template error 系の catch/finally では cancelled / active 系の stale guard を必ず確認し、キャンセル後の state 更新を遮断する。最初からやり直す ボタンを出す場合も、非アクティブ化後の再表示防止を先に実装する |
[FB-STATE-DETAIL-002] ConversationRoundStep の answers prop が変わっても internal state が再初期化されず、前回の回答が次ラウンドへ残留する | answers を props で受けるコンポーネントは、prop 変更を起点に internal state を再同期する effect を持たせる。初期化ロジックと手動編集ロジックを分け、useState 初期値だけに依存しない |
[FB-STATE-DETAIL-003] generationLockRef の解放漏れで、template / LLM いずれの生成フローも次回実行できなくなる | 生成フローでは try/catch よりも finally を解放責務の唯一の出口として扱う。成功・失敗・キャンセルの全経路で generationLockRef.current = false を実行することを Phase 5/11/12 の共通パターンとして固定する |
| [FB-STATE-DETAIL-004] Phase 11 の evidence が画面と current facts で食い違い、スクリーンショット参照先の指し直しが漏れる | Phase 11 の証跡更新では、画像ファイル・screenshot-plan.json・phase11-capture-metadata.json・Phase 12 implementation-guide.md の参照先を同一 wave で更新する。証跡の実体とドキュメントのリンク先を別 wave で動かさない |
| [FB-VISUAL-CAP-001] Phase 11 の screenshot ファイル名が旧 TC 命名のまま残り、metadata / manual-test / implementation-guide / completed ledger の canonical 名が分断される | VISUAL タスクの close-out では screenshot 名を task root で先に canonical 化し、phase11-capture-metadata.json / manual-test-result.md / implementation-guide.md / completed ledger を同一 wave で更新する。画像ファイル名は 1 つの正本に揃え、旧名は evidence 目的以外で残さない |
[UT-W3] implementation-guide.md が current contract（trackEvent → analyticsAdapter → analytics:send）ではなく旧方針（renderer-local no-op）のまま記述される | Phase 12 Task 12-1 で implementation-guide.md を作成する前に trackEvent.ts の prod sink 分岐と analyticsAdapter.ts の存在を確認し、current contract を先に記録してから説明文を書く |
[UT-W3] artifacts.json / outputs/artifacts.json parity 未確認のまま Phase 12 を閉じる | Phase 12 完了前に artifacts.json と outputs/artifacts.json の両ファイルを diff し、phase12_completed + phase13_blocked が同値であることを確認する |
[UT-W3] Phase 12 Task 12-2/12-3/12-6 で generate-index.js 実行を省略してインデックスが stale になる | Task 12-2（システム仕様書更新）・Task 12-3（changelog 更新）・Task 12-6（compliance check）の完了後は node .claude/skills/aiworkflow-requirements/scripts/generate-index.js を必ず実行し、インデックス stale を防ぐ |
[UT-W3] analytics:get-stats / sentCount / failedCount を documentation-changelog / system-spec-update-summary へ書き忘れ、送信契約のみで完了扱いにする | Phase 12 Task 12-2/12-5 では analytics:send に加えて stats API と counters を current facts へ同時記録し、analyticsHandler.ts の skipped 返却も確認する |
| Step 1-C（関連タスクテーブル）を未実行 | spec-update-workflow.md の「確認すべきファイル」表を実行前に必ず読む |
| topic-map.md 未更新 | 仕様書に新規セクション追加時は必ず topic-map.md のエントリも追加 |
| documentation-changelog.md が不完全 | 全Step（1-A/1-B/1-C/Step 2）の結果を個別に明記する（「該当なし」も記録） |
system-spec-update-summary.md を未作成で完了扱い | Phase 12成果物一覧と outputs/phase-12/ 実体を1対1で突合し、不足ファイルは完了前に作成する |
| LOGS.md が1ファイルのみ更新 | 必ず aiworkflow-requirements/LOGS.md と task-specification-creator/LOGS.md の両方 |
| 完了タスクセクションが簡略形式 | spec-update-workflow.md のテンプレート（テスト結果サマリー + 成果物テーブル）に従う |
artifacts.json と outputs/artifacts.json が不一致 | Phase 12完了前に2ファイルを同期し、completed成果物の参照切れを0件にする |
[Feedback 5] Phase 12 close-out で index.md / artifacts.json / outputs/artifacts.json を別 wave で更新して phase table と台帳が一時的に不一致になる | Phase 12 完了前に index.md の Phase 表、task root artifacts.json、outputs/artifacts.json を同一ターンで更新し、phase status の二重化を防ぐ |
| [FB-04] Phase 12 close-out で backlog ledger / completed ledger / lane index / workflow artifacts / skill artifacts の5点を同一waveで同期せず、タスク状態が二重化する | Step 1-A の開始時に三者同期チェックリストで5ファイルを1件ずつ突合し、同一ターンで一括更新する。更新後は validate-phase-output.js --phase 12 と diff -qr .claude/skills/task-specification-creator .agents/skills/task-specification-creator で整合を確認する |
設計タスクの workflow root を completed にしてしまう | workflow root は implementation_ready、completed ledger は spec_created に分離する |
| Phase 10 MINOR指摘を未タスク化せず進行 | Phase 10レビュー前に unassigned-task-guidelines.md を読み、MINOR判定→未タスク化ルールを確認 |
| 未タスク検出レポートで0件判定のまま未修正 | Phase 10 MINOR指摘は必ず未タスク化の対象。「機能に影響なし」は不要判定の理由にならない |
task-workflow.md の未タスクリンクが参照切れ | Step 1-E後に verify-unassigned-links.js を実行して ALL_LINKS_EXIST を確認する |
[Feedback 2] Phase 12 着手時に outputs/artifacts.json と phase spec の artifact 名が照合されない | Phase 12 の 最初の作業として outputs/artifacts.json と各 phase-*.md に記載されたartifact名を1対1で突合し、不一致があれば着手前に修正する |
| [Feedback 3] Phase 11 の UI task / docs-only task 判定がずれる | Phase 1 で記録したタスク分類（UI task / docs-only task）を Phase 11 着手時に必ず参照する。分類が変わっていた場合は再判定を明示する |
[Feedback W0-01] shared 型追加で root @repo/shared に再エクスポートすると SkillCategory が衝突する | 新しい共有型は subpath export（例: @repo/shared/types/skillCreator）に閉じ、既存 root barrel は触らない。phase-12-documentation.md と system spec の両方で公開経路を明記する |
| [Feedback P0-09-U1-1] Phase 4 仕様書に private method テスト方針が未記載 | (facade as unknown as FacadePrivate) キャストと public callback 経由テストの2択を Phase 4 仕様書に必ず明記する |
[Feedback P0-09-U1-2] improve() フローの canUseTool 配線先（SDK callback vs applyImprovement()）が仕様書から読み取れない | Phase 5 仕様書のタスク2に「canUseTool 適用可能範囲と制約」セクションを設け、llmAdapter.sendChat() 経由時は SDK callback 非適用と明記する |
| [Feedback BEFORE-QUIT-001] Phase 11 が非 visual task なのに実地操作を要求してしまう | Phase 11 では「実地操作不可」を明記し、自動テスト結果 + 既知制限リストを代替記録として残す |
| [Feedback BEFORE-QUIT-002] Phase 7 coverage が全ファイル一律指定だと局所検証の意図がぼやける | Phase 7 では coverage の対象範囲を明示し、変更したファイル/ブロック以外を対象外として書く |
| [Feedback BEFORE-QUIT-003] Phase 12 の system-spec update で workflow-local と global sync が混在する | documentation-changelog.md で workflow-local 同期と global skill sync を別ブロックで記録する |
| [Feedback 4] Phase 11 NON_VISUAL のとき manual-test-result.md の証跡メタが薄い | Phase 11 が NON_VISUAL の場合、manual-test-result.md のメタ情報に「証跡の主ソース（自動テスト名/件数）」と「スクリーンショットを作らない理由」を明記する。空メタでは reviewer が意図を読み取れない |
| [Feedback 5] Phase 7 の coverage 目標が広域指定のとき変更行の保護確認が曖昧になる | Phase 7 のカバレッジ目標が「全体 X%」など広域指定のとき、変更した関数/ブロックの line カバレッジと branch カバレッジの実測値を証跡に残す（例: applyWorkflowSnapshot 付近の line 100% / branch 100%） |
| [Feedback 6] ViewType を追加した際に navigation 契約・store 型・既存テストの3点更新が漏れる | store/types.ts（ViewType union）/ skillLifecycleJourney.ts（正規化関数・定数）/ renderView テスト を same-wave で更新し、ui-ux-navigation.md の ViewType テーブルも同時同期する。Phase 1 設計メモに「追加 ViewType: XYZ」を明示しておくと漏れが防げる |
| [FB-UI-02-1] Phase 9 QA で「ファイル削除」を PASS 基準にすると stub 化タスクが FAIL 扱いになる | Phase 9 の削除確認は「git delete されている OR export {} stub 化かつ live import ゼロのいずれか」を PASS とする。たとえば、廃止ファイルを stub 化した場合は grep -rn "import.*廃止ファイル名" src/ でゼロ件を証跡に残す |
[Feedback TASK-UI-04] 実装完了後に artifacts.json status が spec_created / in_progress のまま放置される | 実装 Phase（Phase 5 or 最終実装 Phase）完了時に complete-phase.js を必ず実行し、status を completed に更新する。実装完了と仕様書ステータス更新は同一 wave で行う（後回しは乖離蓄積の主因）。有効値: spec_created / in_progress / completed / phase12_completed |
[FB-DATAFLOW-001] SkillCreationContext 追加時に shared 型・renderer store・preload/main IPC の context bridge 同期が同一waveで更新されず、implementation-guide.md と実コードの dataflow が乖離する | Phase 12 Task 12-1/12-2 の開始前に buildSkillContext / buildSkillGenerationPrompt / skill.create(..., context) の3点を契約チェックとして固定し、packages/shared・apps/desktop/src/renderer・apps/desktop/src/main を同一 wave で突合する。ズレがあれば close-out 前に仕様と成果物（phase spec / artifacts）を同時修正する |
| [FB-SDK-07-2] Phase 1 で新規 IPC surface を定義する際に Preload API 経由が明記されない | Phase 1（要件定義）では新規 IPC surface を定義する場合、「Preload API 経由必須」を明記する。直接 ipcRenderer.on は禁止パターンとして記録する |
| [FB-SDK-07-4] Phase 1 で既存 API の命名パターンを確認せずに新規 API を命名し、Phase 3 で MINOR 指摘を受ける | Phase 1（要件定義）では既存の safeOn / safeInvoke 等の命名パターンを確認し、新規 API の命名規則一貫性を担保する。命名ドリフトは Phase 3 レビューゲートの MINOR 指摘の主要因となる |
[Feedback W1-02b-1] UI task の screenshot-plan.json が mode: "NON_VISUAL" のまま Phase 11 を迎えやすい | UI コンポーネント変更タスクでは screenshot-plan.json 生成時に mode: "VISUAL" をデフォルトにする。phase11-capture-metadata.json の taskId が現行タスク ID と一致するか Phase 11 着手前に確認する（jq '.taskId' outputs/phase-11/phase11-capture-metadata.json） |
| [Feedback W1-02b-2] multi-step wizard 設計で「ステップ間の state ownership と引き渡し項目」が Phase 2 設計書に未記載 | Phase 2（設計）でウィザード / マルチステップ UI を設計する場合、「ステップ間 state 引き渡しテーブル」を必須セクションとして設ける。smartDefaults など推論値の反映タイミング（初回のみ / 都度上書き / ユーザー優先）は decision 欄で固定する |
[Feedback W1-02b-3] implementation-guide.md の callback 名・props 名が実装と一致していない（identifier drift） | Phase 12 Task 12-6 で implementation-guide.md 内の識別子を現行コードで grep 確認する。スニペットは型定義・props interface から引用し、手書き snippets を避ける |
| [Feedback W1-02b-4] renderer UI コンポーネントで node-only パッケージを直接 import し、Vite browser bundle が runtime error になる | renderer コンポーネントでは node-only パッケージ（node-cron 等）を直接 import しない。cron/schedule 検証は browser-safe ユーティリティに切り出す。Phase 11 capture 前に「ブラウザで実際に route を開く smoke test」を必須にする |
[Feedback W0-RV-001] minLength / maxLength のテストケースで境界値文字列の実文字数を確認せずに誤った長さで書く（例: "十文字以上の目的" = 実際は 7 文字） | テスト文字列を書く前に "...".length で実文字数を確認する。日本語の漢数字表記の意味と .length は別物。境界値テストは // length: N コメントを付けてから書く |
[Feedback SC-13-1] IPC surface 追加時に apps/desktop/src/preload/channels.ts の ALLOWED_INVOKE_CHANNELS への追記が漏れる | IPC surface 追加タスクでは Phase 2 成果物のチェックリストに「ALLOWED_INVOKE_CHANNELS への追記」を必須項目として記載する。shared/ipc/channels.ts への定数追加だけでは Renderer から呼び出せない |
[Feedback SC-13-2] 公開 IPC メソッド名（verify(skillName, ...)）と内部エンジンメソッド名（verifySkill(skillDir)）が酷似し Phase 2 設計時に責務が不明確になる | 公開 surface と内部エンジンで名前が近い場合、Phase 2 成果物に「内部型 → 公開 DTO 変換表」と「解決レイヤ名称（例: resolveVerifySkillDir）」を必須セクションとして設ける |
[Feedback VSCPKR-01] JSDoc コメント内に */ を含む説明（例: ステップ値 */n）があると esbuild がコメント終端と誤認識しパースエラーになる | cron 式や数式を JSDoc コメント内で説明する場合は */ を避け、* /n のようにスペースを挿入するか、コードブロック（```）形式で書く。@example タグ内の inline cron 式も同様 |
[Feedback VSCPKR-02] happy-dom 環境で vi.stubGlobal("window", ...) でウィンドウ全体を置き換えると React 内部の instanceof HTMLElement が常に false になり、コンポーネントテストが壊れる | window.api などの Electron Preload API をモックする場合は Object.defineProperty(window, "api", { value: mockApi, writable: true }) を使う。vi.stubGlobal("window", ...) は使用禁止 |
| [VSCPKR-03] Phase 4 でコンポーネントテストを設計する際に、テストで操作する入力が外部 props か内部 state かを Phase 2 で確認しておらず、TDD RED フェーズで「テストが通らない」問題が props/state の混同に起因することに気づかない | Phase 2（設計）で UI コンポーネントのモード管理方法を明記する（例: "isAdvancedMode は内部 state"）。Phase 4 仕様書に「テスト操作対象は internal state か external prop か」を明記し、TDD RED を書く前にコンポーネントの props interface と内部 useState を区別する |
| [FB-CRONVL-001] Phase 2 でサードパーティライブラリを採用する際に、複合フィールド（day-of-month × day-of-week）の組み合わせ動作（AND/OR semantics）を実測確認しないと、Phase 5 で設計変更が必要になり TDD の期待値を修正し直す手戻りが発生する | Phase 2 設計書の「ライブラリ選定」セクションに「複合フィールドの semantics 実測確認」を必須チェック項目として記載する。例: CronExpressionParser.parse("0 0 31 2 1") の next-execution 計算結果で AND/OR 判定を確認する。期待 semantics と一致しない場合は safe-side 判定（到達不能を常にエラー）への方針変更を Phase 2 で決定する |
[FB-CRONVL-002] renderer utility に opt-in フラグ（例: semantic?: boolean）を追加する場合、Phase 1 スコープで「UI 呼び出し経路は別タスク化する」を明示しないと、UI 統合の担当タスクが曖昧なまま積み残される | Phase 1（要件定義）で opt-in フラグを設計する際は、「このフラグを UI から有効化するタイミングと担当タスク ID は別タスクで明示する」を scope out として明記する。NON_VISUAL タスクでは特に「将来の UI 統合経路 = 未タスク化候補」を Phase 1 成果物に書き残す |
[FB-TASK-01/02] testid 削除・改名後に describe.skip ブロック内の旧参照が残存し CI に検出されない（スキップ済みテストは実行されないため型エラーも発生しない） | testid 削除タスクでは Phase 5 完了チェックとして grep -rn "<削除testid>" apps/ を実行し、describe.skip 内を含む全残存参照をゼロにする。同一 wave で削除しないと cleanup タスクが積み残される |
| [WEEKGRD-01] NON_VISUALタスクのPhase 11では、source-level PASSと環境ブロッカーを混在させて記録してしまい、後からブロッカーの性質が判断できなくなる | source-level PASSと環境ブロッカー（esbuild mismatch等）を別カテゴリで記録する。製品コードの問題と環境起因の問題は分離しないと、次回タスクで同じ混乱が起きる |
| [WEEKGRD-02] 純粋関数ガードの実装方針として「例外スロー」を選択してしまい、呼び出し元への影響が広がる | 純粋関数ガードのデフォルト戦略は「例外なし・無効値返却（空文字等）」とする。入力バリデーションは呼び出し元（UIレイヤ等）に委ね、関数自体は防御的な値返却に徹する |
[WEEKGRD-03] NON_VISUALタスクの ui-sanity-visual-review.md に非該当理由が明記されず、reviewerがNON_VISUAL判断の根拠を読み取れない | NON_VISUALタスクでは ui-sanity-visual-review.md の冒頭に「NON_VISUAL宣言」（タスク種別・非視覚的理由・代替証跡）を明記する。空欄や略記はレビューアの混乱を招く |
| 漏れパターン | 防止方法 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
[UT-W3] implementation-guide.md が current contract（trackEvent → analyticsAdapter → analytics:send）ではなく旧方針（renderer-local no-op）のまま記述される | Phase 12 Task 12-1 で implementation-guide.md を作成する前に trackEvent.ts の prod sink 分岐と analyticsAdapter.ts の存在を確認し、current contract を先に記録してから説明文を書く |
[UT-W3] artifacts.json / outputs/artifacts.json parity 未確認のまま Phase 12 を閉じる | Phase 12 完了前に artifacts.json と outputs/artifacts.json の両ファイルを diff し、phase12_completed + phase13_blocked が同値であることを確認する |
[UT-W3] Phase 12 Task 12-2/12-3/12-6 で generate-index.js 実行を省略してインデックスが stale になる | Task 12-2（システム仕様書更新）・Task 12-3（changelog 更新）・Task 12-6（compliance check）の完了後は node .claude/skills/aiworkflow-requirements/scripts/generate-index.js を必ず実行し、インデックス stale を防ぐ |
[UT-W3] shared 型を追加したのに types/index.ts / package index / consumer wiring のどれかが残り、Phase 12 が false complete になる | |
| Step 1-C（関連タスクテーブル）を未実行 | spec-update-workflow.md の「確認すべきファイル」表を実行前に必ず読む |
| topic-map.md 未更新 | 仕様書に新規セクション追加時は必ず topic-map.md のエントリも追加 |
| documentation-changelog.md が不完全 | 全Step（1-A/1-B/1-C/Step 2）の結果を個別に明記する（「該当なし」も記録） |
system-spec-update-summary.md を未作成で完了扱い | Phase 12成果物一覧と outputs/phase-12/ 実体を1対1で突合し、不足ファイルは完了前に作成する |
| LOGS.md が1ファイルのみ更新 | 必ず aiworkflow-requirements/LOGS.md と task-specification-creator/LOGS.md の両方 |
| 完了タスクセクションが簡略形式 | spec-update-workflow.md のテンプレート（テスト結果サマリー + 成果物テーブル）に従う |
