Task Specification Creator

開発タスクを Phase 1〜13 の実行可能な仕様書へ落とし込む。SKILL.md は入口だけを持ち、詳細は references/ と LOGS.md に分離する。

設計原則

要件レビュー思考法

要件草案や設計草案を扱うときは、機能列挙のレビューで止めず、次の3系統を必ず通す。

• システム系: システム思考、因果関係分析、因果ループ、依存関係、責務境界、状態所有権
• 戦略・価値系: 価値提案、戦略的思考、why、トレードオン、プラスサム、価値とコストの均衡
• 問題解決系: 改善思考、仮説思考、論点思考、KJ法、優先順位付け

特に workflow / lane / UI統合 / runtime orchestration / verify 導入を含むタスクでは、次を明示してから Phase 1 へ進む。

1. 真の論点は何か
2. 依存関係・責務境界の問題点は何か
3. 価値とコストの不均衡箇所はどこか
4. 改善優先順位はどうあるべきか
5. 4条件の評価はどうか

真の論点の掘り方

• 現象ではなく主問題を1文で固定する。
• 1つの提案に複数案件が混ざっていないかを切り分ける。
• what / how だけでなく why now / why this way を仮説として書く。

因果と境界の確認

• 強化ループとバランスループを最低1本ずつ書く。
• 実行状態、phase 遷移、verify fail 後の意思決定権がどこにあるかを明記する。
• Facade / Engine / Service / Bridge / Store / UI の状態所有権を混在させない。

価値とコストの見方

• 初回スコープで得る価値と、導入コストが最も大きい部品を分けて書く。
• 将来拡張を初回価値と混同しない。
• verify / session persistence / UI統合のような高コスト項目は、初期層と将来層を分離する。

4条件の評価

4条件 は原則として次で評価する。

• 価値性: 誰のどのコストをどれだけ下げるかが定義されているか
• 実現性: 初回スコープで実装可能な厚みに収まっているか
• 整合性: 責務境界、依存関係、状態所有権が矛盾なく閉じているか
• 運用性: 導入後の verify、resume、spec sync、監査運用が破綻しないか

要件レビュー出力では、上の5項目を一次結論として先に示し、その後に補足として因果ループ、KJ法クラスタ、戦略仮説を足す。

クイックスタート

node scripts/detect-mode.js --request "{{USER_REQUEST}}"

Phase 1 前提確認チェック（P50チェック）

タスク仕様書作成を開始する前に、以下の P50 チェックを実施する。 upstream 実装済みタスクでは「差分確認 → 回帰確認」にシフトできるため、Phase 5 の実装フェーズが軽減される。

標準ルール: upstream マージ済みの場合は Phase 5 冒頭に「差分確認」セクションを設け、実装の代わりに回帰確認を行う。

implementation_mode の定義（[CANCEL-003-FB-1]）

P50チェック結果に基づき、タスク仕様書のメタ情報に implementation_mode を明記する。

implementationmode: "verifyexisting" を選択した場合、Phase 4 では既実装コードのカバレッジを確認する targeted test のみを設計し、Phase 5 では git diff によるdiff確認を主要作業とする。詳細は [references/phase-template-core.md](references/phase-template-core.md) の P50チェックセクションを参照。

verify_existing タスクタイプの典型的アウトカム:

verify_existing は「コードの暗黙知を明文化する」タスクタイプである。コード変更は原則ゼロまたは最小限にとどまり、以下が主な成果物となる:

| アウトカム | 例 | | ---------- | -- | | コメント追加 | 既存関数・型に JSDoc / インラインコメントを付与 | | テスト追加 | 既実装コードの動作を保証する regression test を新設 | | ドキュメント更新 | 仕様書・README・インターフェース定義の現行コードへの同期 |

コード変更なしで Phase 12 まで完了するケースが標準パターンであり、verify-all-specs が PASS しても仕様書反映が不完全な場合がある（→ [references/phase-template-phase12.md](references/phase-template-phase12.md) §verify-all-specs が PASS しても確認すべき項目 を参照）。

実行フロー

create

1. agents/decompose-task.md で責務を分解する。
2. agents/identify-scope.md で前提、制約、受入条件を固定する。

[Feedback 1 対応] Phase 1（要件定義）でタスク分類（UI task / docs-only task）を明示的に記録し、artifacts.json の artifact 命名 canonical 一覧を task root 生成時に先に確定させること。後回しにすると artifact 命名ドリフトが発生する。

1. agents/design-phases.md と agents/generate-task-specs.md で index.md と phase-*.md を作る。
2. agents/output-phase-files.md と agents/update-dependencies.md で artifacts.json を整える。
3. agents/verify-specs.md、scripts/validate-phase-output.js、scripts/verify-all-specs.js で gate を通す。

execute

Task仕様ナビ

凡例: seq=順次実行, par=並列実行, cond=条件分岐

Phase 12 重要仕様

必須タスク（5タスク - 全て完了必須）

Task 1: 実装ガイドの2パート構成

Part 1（中学生レベル）の必須要件:

• 日常生活での例え話を必ず含める
• 専門用語は使わない（使う場合は即座に説明）
• 「なぜ必要か」を先に説明してから「何をするか」を説明

Part 2（技術者レベル）の必須要件:

• インターフェース/型定義（TypeScript）を含める
• APIシグネチャと使用例を記載
• エラーハンドリングとエッジケースを説明
• 設定可能なパラメータと定数を一覧化
• VISUAL タスクでは Phase 11 の screenshot references と capture metadata を implementation-guide.md へ必ず明記する
• NON_VISUAL タスク（UI/UX変更なし） では ## 視覚証跡 セクションに UI/UX変更なしのため Phase 11 スクリーンショット不要 と明記し、screenshots/.gitkeep を削除する。代替証跡として phase-10/final-review-result.md と phase-11/manual-test-result.md（Preload API / 型定義テスト結果を記録）を参照する

Task 2: システム仕様更新【4サブステップ + 条件付きStep 2】

⚠️ Task 1（実装ガイド作成）との境界に注意

| 活動 | Task 1（実装ガイド） | Task 2（仕様更新） |
| -------------------------------- | -------------------- | ------------------ |
| Part 1/2 実装ガイド作成 | ✅ メイン責務 | ❌ 対象外 |
| aiworkflow-requirements 仕様更新 | ❌ 対象外 | ✅ Step 2 |
| タスク完了記録（仕様書内） | ❌ 対象外 | ✅ Step 1-A 必須 |
| LOGS.md更新（2ファイル） | ❌ 対象外 | ✅ Step 1-A 必須 |

Step 2 更新が必要な場合:

• 新規インターフェース/型の追加
• 既存インターフェースの変更
• 新規定数/設定値の追加
• API仕様の変更

Step 2 更新が不要な場合:

• 内部実装の詳細変更のみ
• リファクタリング（インターフェース不変）
• バグ修正（仕様変更なし）

spec_created UI task の Phase 12 close-out ルール

spec_created ステータスの UI task でも Phase 12 実行時は Step 1-A〜1-C を N/A にせず same-wave sync で閉じる。

docs-only task に後からコード実装が入った場合の再判定ルール

当初 docs-only / spec_created だった task に後から code 変更が入った場合:

1. Step 2 再判定: source workflow と outputs/phase-12/*.md を同一ターンで current facts へ戻す
2. Screenshot 再判定: N/A / NON_VISUAL だった Phase 11 evidence の reclassification を検討する
3. 新規未タスク 0 件固定より current gap formalize を優先: code wave で生じた gap は即座に未タスク化する

Task 4: 未タスク検出（0件でも出力必須）

# 未タスク検出スクリプト
node scripts/detect-unassigned-tasks.js --scan packages/shared/src --output .tmp/unassigned-candidates.json

📖 [references/phase-11-12-guide.md](references/phase-11-12-guide.md) 📖 [references/spec-update-workflow.md](references/spec-update-workflow.md) 📖 [agents/generate-unassigned-task.md](agents/generate-unassigned-task.md)

Lessons Learned（実装事例からのFB）

FB-01: Phase 1 仕様書vs実装クラス名ズレ検出（必須）

Phase 1冒頭で仕様書に記載されたクラス名とcurrentコードベースのクラス名が一致するか確認する。 不一致の場合は命名方針をPhase 2設計より前に確定させること。

事例: LateChunkingService（仕様書記述）vs ChunkingLateChunkingAdapter（実装クラス名）のズレがPhase 1で早期検出できれば、後続フェーズの手戻りを防げた（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。

FB-02: Phase 11 NON_VISUAL証跡ファイル名の固定

Phase 11のNON_VISUALテンプレートでは証跡ファイル名を事前に宣言・固定すること。 後からファイル名が変わるとPhase 12のartifacts parity確認で矛盾が発生する。

事例: evidence-collection.md などのcanonical名を強制することで、manual-test-result.md 単独では不明瞭だった証跡範囲をdrift防止できる（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。

FB-03: Phase 12 正本仕様更新を必須ゲート化

Phase 12で「system-spec-update: 更新要」と判定した場合、 summaryファイル作成だけでなく正本仕様ファイルの実際の更新まで完了条件とする。

事例: Phase 12がsummaryファイル作成で完結せず、正本仕様の更新まで完了条件にする必要がある（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。

FB-04: Phase 2 クラス名衝突検査

新規クラスを設計する際は同一パッケージ内の既存クラス名と照合する。 衝突する場合はPrefix/Suffix（Adapter, Service, Handler等）で区別すること。

事例: token-levelのLateChunkingServiceと同名になりそうだったため、Phase 2でChunkingLateChunkingAdapterに改名した。早期検査が必要（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。

変更履歴

Task 5: スキルフィードバックレポート（改善点なしでも出力必須）

出力:

• outputs/phase-12/skill-feedback-report.md

TASK-SW-FIX-STATE-DETAIL-001 current facts

• SkillCreateWizard の template error は stale guard を入れないと、キャンセル後の遅延 reject で古いエラーが再表示される。
• ConversationRoundStep は answers prop 変更時に内部 state を再同期しないと、前回回答が残ったまま次のラウンドに混入する。
• generationLockRef は finally で必ず解放しないと、次回生成がロックされたままになる。
• Phase 11 の evidence は outputs/phase-11/ の実物と current facts を一致させ、スクリーンショット参照先の指し直しを同波で更新する。

Phase 12 実行時によくある漏れ

| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [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 し、phase12completed + phase13blocked が同値であることを確認する | | [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 のテンプレート（テスト結果サマリー + 成果物テーブル）に従う | | artifacts.json と outputs/artifacts.json が不一致 | Phase 12完了前に2ファイルを同期し、completed成果物の参照切れを0件にする | | [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 は implementationready、completed ledger は speccreated に分離する | | Phase 10 MINOR指摘を未タスク化せず進行 | Phase 10レビュー前に unassigned-task-guidelines.md を読み、MINOR判定→未タスク化ルールを確認 | | 未タスク検出レポートで0件判定のまま未修正 | Phase 10 MINOR指摘は必ず未タスク化の対象。「機能に影響なし」は不要判定の理由にならない | | task-workflow.md の未タスクリンクが参照切れ | Step 1-E後に verify-unassigned-links.js を実行して ALLLINKSEXIST を確認する | | [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 NONVISUAL のとき manual-test-result.md の証跡メタが薄い | Phase 11 が NONVISUAL の場合、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 が speccreated / inprogress のまま放置される | 実装 Phase（Phase 5 or 最終実装 Phase）完了時に complete-phase.js を必ず実行し、status を completed に更新する。実装完了と仕様書ステータス更新は同一 wave で行う（後回しは乖離蓄積の主因）。有効値: speccreated / inprogress / completed / phase12completed | | [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: "NONVISUAL" のまま 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 の ALLOWEDINVOKECHANNELS への追記が漏れる | IPC surface 追加タスクでは Phase 2 成果物のチェックリストに「ALLOWEDINVOKECHANNELS への追記」を必須項目として記載する。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", ...) は使用禁止 | | [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 として明記する。NONVISUAL タスクでは特に「将来の UI 統合経路 = 未タスク化候補」を Phase 1 成果物に書き残す | | [FB-TASK-01/02] testid 削除・改名後に describe.skip ブロック内の旧参照が残存し CI に検出されない（スキップ済みテストは実行されないため型エラーも発生しない） | testid 削除タスクでは Phase 5 完了チェックとして grep -rn "<削除testid>" apps/ を実行し、describe.skip 内を含む全残存参照をゼロにする。同一 wave で削除しないと cleanup タスクが積み残される | | [WEEKGRD-01] NONVISUALタスクのPhase 11では、source-level PASSと環境ブロッカーを混在させて記録してしまい、後からブロッカーの性質が判断できなくなる | source-level PASSと環境ブロッカー（esbuild mismatch等）を別カテゴリで記録する。製品コードの問題と環境起因の問題は分離しないと、次回タスクで同じ混乱が起きる | | [WEEKGRD-02] 純粋関数ガードの実装方針として「例外スロー」を選択してしまい、呼び出し元への影響が広がる | 純粋関数ガードのデフォルト戦略は「例外なし・無効値返却（空文字等）」とする。入力バリデーションは呼び出し元（UIレイヤ等）に委ね、関数自体は防御的な値返却に徹する | | [WEEKGRD-03] NONVISUALタスクの ui-sanity-visual-review.md に非該当理由が明記されず、reviewerがNONVISUAL判断の根拠を読み取れない | NONVISUALタスクでは ui-sanity-visual-review.md` の冒頭に「NONVISUAL宣言」（タスク種別・非視覚的理由・代替証跡）を明記する。空欄や略記はレビューアの混乱を招く |

Phase 12 苦戦防止Tips

UT-STORE-HOOKS-COMPONENT-MIGRATION-001の経験に基づく（2026-02-12）

重要ルール

Phase完了時の必須アクション

1. タスク完全実行: Phase内で指定された全タスクを完全に実行
2. 成果物確認: 全ての必須成果物が生成されていることを検証
3. artifacts.json更新: complete-phase.js でPhase完了ステータスを更新
4. 完了条件チェック: 各タスクを完遂した旨を必ず明記

PR作成に関する注意

PR作成は自動実行しない。必ずユーザーの明示的な許可を得てから実行すること。

📖 [references/commands.md](references/commands.md) - コマンド一覧

agent 導線

• [agents/decompose-task.md](agents/decompose-task.md)
• [agents/identify-scope.md](agents/identify-scope.md)
• [agents/design-phases.md](agents/design-phases.md)
• [agents/generate-task-specs.md](agents/generate-task-specs.md)
• [agents/output-phase-files.md](agents/output-phase-files.md)
• [agents/update-dependencies.md](agents/update-dependencies.md)
• [agents/verify-specs.md](agents/verify-specs.md)
• [agents/update-system-specs.md](agents/update-system-specs.md)
• [agents/generate-unassigned-task.md](agents/generate-unassigned-task.md)

Phase 12 と Phase 13 の境界

UI/UX 実装を含む task では Phase 11 で screenshot と Apple UI/UX 視覚検証を行う。手順は [references/phase-11-screenshot-guide.md](references/phase-11-screenshot-guide.md) と [references/screenshot-verification-procedure.md](references/screenshot-verification-procedure.md) を使う。

リソース導線

core workflow

• [references/resource-map.md](references/resource-map.md)
• [references/create-workflow.md](references/create-workflow.md)
• [references/execute-workflow.md](references/execute-workflow.md)
• [references/commands.md](references/commands.md)
• [references/quality-standards.md](references/quality-standards.md)
• [references/coverage-standards.md](references/coverage-standards.md)
• [references/review-gate-criteria.md](references/review-gate-criteria.md)
• [references/artifact-naming-conventions.md](references/artifact-naming-conventions.md)
• [references/evidence-sync-rules.md](references/evidence-sync-rules.md)
• [references/self-improvement-cycle.md](references/self-improvement-cycle.md)

phase templates

• [references/phase-templates.md](references/phase-templates.md)
• [references/phase-template-core.md](references/phase-template-core.md)
• [references/phase-template-execution.md](references/phase-template-execution.md)
• [references/phase-template-audit-task.md](references/phase-template-audit-task.md) — NON_VISUAL / 監査タスク用 Phase 再解釈マップ
• [references/phase-template-phase11.md](references/phase-template-phase11.md)
• [references/phase-template-phase12.md](references/phase-template-phase12.md)
• [references/phase-template-phase13.md](references/phase-template-phase13.md)

Phase 11/12 guides

• [references/phase-11-12-guide.md](references/phase-11-12-guide.md)
• [references/phase-11-screenshot-guide.md](references/phase-11-screenshot-guide.md)
• [references/phase-12-documentation-guide.md](references/phase-12-documentation-guide.md)
• [references/phase12-checklist-definition.md](references/phase12-checklist-definition.md)
• [references/technical-documentation-guide.md](references/technical-documentation-guide.md)
• [references/screenshot-verification-procedure.md](references/screenshot-verification-procedure.md)
• [assets/phase12-task-spec-compliance-template.md](assets/phase12-task-spec-compliance-template.md)

spec update

• [references/spec-update-workflow.md](references/spec-update-workflow.md)
• [references/spec-update-step1-completion.md](references/spec-update-step1-completion.md)
• [references/spec-update-step2-domain-sync.md](references/spec-update-step2-domain-sync.md)
• [references/spec-update-validation-matrix.md](references/spec-update-validation-matrix.md)

pattern family

• [references/patterns.md](references/patterns.md)
• [references/patterns-workflow-generation.md](references/patterns-workflow-generation.md)
• [references/patterns-validation-and-audit.md](references/patterns-validation-and-audit.md)
• [references/patterns-phase12-sync.md](references/patterns-phase12-sync.md)

logs and archives

• [LOGS.md](LOGS.md)
• [references/logs-archive-index.md](references/logs-archive-index.md)
• [references/logs-archive-2026-march.md](references/logs-archive-2026-march.md)
• [references/logs-archive-2026-feb.md](references/logs-archive-2026-feb.md)
• [references/logs-archive-legacy.md](references/logs-archive-legacy.md)
• [references/changelog-archive.md](references/changelog-archive.md)

システム観点チェック

Electron desktop task では Renderer、Main、IPC、Preload、ローカルストレージの境界を都度明記する。詳細は [references/quality-standards.md](references/quality-standards.md) を参照。

検証コマンド

node scripts/validate-phase-output.js docs/30-workflows/{{FEATURE_NAME}}
node scripts/verify-all-specs.js --workflow docs/30-workflows/{{FEATURE_NAME}}
node ../skill-creator/scripts/quick_validate.js .claude/skills/task-specification-creator
node ../skill-creator/scripts/validate_all.js .claude/skills/task-specification-creator
diff -qr .claude/skills/task-specification-creator .agents/skills/task-specification-creator
node scripts/log-usage.js --result success --phase "Phase {{N}}"

Phase 12 では追加で detect-unassigned-tasks.js、audit-unassigned-tasks.js、verify-unassigned-links.js、validate-phase12-implementation-guide.js を実行する。

ベストプラクティス

すべきこと

• 仕様、テスト、実装、検証、同期の順序を崩さない。
• outputs/phase-N/ を phase ごとに実体化し、artifacts.json と同時更新する。
• SubAgent 相当の lane は 3 並列以下に抑え、validation lane は直列で締める。
• detail を増やしたくなったら references/ へ逃がし、SKILL.md は入口に保つ。
• Phase 12 は implementation-guide、system-spec-update-summary、documentation-changelog、unassigned-task-detection、skill-feedback-report、phase12-task-spec-compliance-check を必ず揃える。
• shared 型を追加したら definition / types/index / package index / consumer wiring を同 wave で同期する。
• [Feedback P0-09-U1-3] 小規模タスク（Phase 1〜3 で設計が自明）の outputs 必須度は規模（小/中/大）で tier 分けを検討する。ドキュメント作成コストが実装コストを上回るリスクを Phase 1 スコープ固定時に評価する。
• [Feedback STATE-DETAIL-01] UI state machine でエラー・キャンセル・正常完了の 3 経路すべてでロック変数（ref）を解放できていないと、2 回目以降の操作が無応答になる。Phase 2 設計で「ロック変数の解放経路テーブル（正常/エラー/キャンセル）」を必須セクションとして設ける。
• [Feedback STATE-DETAIL-02] template recovery（「最初からやり直す」）と通常エラーリトライ（「再試行」）は意味が異なる。Phase 2 設計でボタンのラベル・遷移先・state リセット範囲を明確に分けて記載する。retry は formData 保持 + answers リセット、start over は全 state クリアが標準パターン。
• [Feedback STATE-DETAIL-03] マルチステップウィザードで子コンポーネントが local state を持つ場合、親の state が変わっても子の local state が古いままになる（stale）。useEffect(() => { setInternal(prop) }, [prop]) で親から子への再同期ポイントを明示する必要がある。Phase 4 テスト仕様に「props 変更 → internal state 再同期」のテストケースを必須化する。
• [Feedback IPC-MERGE-001] IPC ハンドラーでオブジェクト（Record<string, unknown> 等）を扱う場合、Phase 2 設計でシャロー/ディープマージ戦略を明示すること。配列・null・undefined の扱いもマージルールとして設計書に記載する。IPC 経由の設定更新は plain object のみに制限し、proto / constructor / prototype を無視して prototype pollution を防ぐ。発見元: UT-FIX-STORE-SETTINGS-DEEP-MERGE-001

避けるべきこと

• .agents 側だけ先に更新して canonical root を残すこと。
• outputs/ を後回しにして phase 完了だけ先に付けること。
• current と baseline の監査結果を混ぜること。
• UI task で screenshot を自動テスト代替として扱うこと。
• user の明示承認なしに commit や PR を作ること。

変更履歴

補足: v9.89.0 以前の履歴は LOGS.md に保持（監査証跡を維持）。

詳細な履歴と usage log は [LOGS.md](LOGS.md) と [references/logs-archive-index.md](references/logs-archive-index.md) を参照。