task-specification-creator
タスクを単一責務原則で分解しPhase 1-13の実行可能な仕様書を生成。Phase 12は中学生レベル概念説明を含む。 Anchors: • Clean Code / 適用: SRP / 目的: タスク分解基準 • Continuous Delivery / 適用: フェーズゲート / 目的: 品質パイプライン • DDD / 適用: ユビキタス言語 / 目的: 用語統一 Trigger: タスク仕様書作成, タスク分解, ワークフロー設計, Phase実行, IPC Bridge API統一, Preload APIパターン, safeInvoke, safeOn
5 stars
Best use case
task-specification-creator is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
タスクを単一責務原則で分解しPhase 1-13の実行可能な仕様書を生成。Phase 12は中学生レベル概念説明を含む。 Anchors: • Clean Code / 適用: SRP / 目的: タスク分解基準 • Continuous Delivery / 適用: フェーズゲート / 目的: 品質パイプライン • DDD / 適用: ユビキタス言語 / 目的: 用語統一 Trigger: タスク仕様書作成, タスク分解, ワークフロー設計, Phase実行, IPC Bridge API統一, Preload APIパターン, safeInvoke, safeOn
Teams using task-specification-creator should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
$curl -o ~/.claude/skills/task-specification-creator/SKILL.md --create-dirs "https://raw.githubusercontent.com/daishiman/AIWorkflowOrchestrator/main/.agents/skills/task-specification-creator/SKILL.md"
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/task-specification-creator/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How task-specification-creator Compares
| Feature / Agent | task-specification-creator | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
タスクを単一責務原則で分解しPhase 1-13の実行可能な仕様書を生成。Phase 12は中学生レベル概念説明を含む。 Anchors: • Clean Code / 適用: SRP / 目的: タスク分解基準 • Continuous Delivery / 適用: フェーズゲート / 目的: 品質パイプライン • DDD / 適用: ユビキタス言語 / 目的: 用語統一 Trigger: タスク仕様書作成, タスク分解, ワークフロー設計, Phase実行, IPC Bridge API統一, Preload APIパターン, safeInvoke, safeOn
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Task Specification Creator
開発タスクを Phase 1〜13 の実行可能な仕様書へ落とし込む。`SKILL.md` は入口だけを持ち、詳細は `references/` と `LOGS.md` に分離する。
## 設計原則
| 原則 | 説明 |
| ------------------------- | ----------------------------------------------------------- |
| Script First | 決定論的処理は `scripts/` で固定する |
| LLM for Judgment | 判断、設計、レビューだけを LLM が担う |
| Progressive Disclosure | 必要な reference だけを段階的に読む |
| 1 File = 1 Responsibility | 大きくなった guide は family file へ分離する |
| `.claude` Canonical | 正本は `.claude/skills/...`、`.agents/skills/...` は mirror |
## 要件レビュー思考法
要件草案や設計草案を扱うときは、機能列挙のレビューで止めず、次の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法クラスタ、戦略仮説を足す。
## クイックスタート
| モード | 用途 | 最初に読むもの |
| ------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
| `create` | 新規 workflow を作る | [references/create-workflow.md](references/create-workflow.md) |
| `execute` | Phase 1〜13 を順番に実行する | [references/execute-workflow.md](references/execute-workflow.md) |
| `update` | 既存仕様書を修正する | [references/phase-templates.md](references/phase-templates.md) |
| `detect-unassigned` | Phase 12 の残課題を formalize する | [references/phase-12-documentation-guide.md](references/phase-12-documentation-guide.md) |
```bash
node scripts/detect-mode.js --request "{{USER_REQUEST}}"
```
## Phase 1 前提確認チェック（P50チェック）
タスク仕様書作成を開始する前に、以下の P50 チェックを実施する。
upstream 実装済みタスクでは「差分確認 → 回帰確認」にシフトできるため、Phase 5 の実装フェーズが軽減される。
| 確認項目 | Yes → 対応 | No → 対応 |
| ---------------------------------- | ---------------------------------------------- | ------------------------------ |
| current branch に実装が存在する | 差分確認・回帰テストを Phase 5 とする | 通常の実装 Phase とする |
| upstream（main等）にマージ済み | worktree に cherry-pick または再実装不要を明記 | 未マージとして扱う |
| 前提タスク（依存タスク）が完了済み | 完了済みを記録し依存チェックを省略 | Phase 1 に依存解消タスクを追加 |
> **標準ルール**: upstream マージ済みの場合は Phase 5 冒頭に「差分確認」セクションを設け、実装の代わりに回帰確認を行う。
### implementation_mode の定義（[CANCEL-003-FB-1]）
P50チェック結果に基づき、タスク仕様書のメタ情報に `implementation_mode` を明記する。
| モード | 値 | 説明 |
| ---------- | ------------------- | --------------------------------------------------------------- |
| 通常実装 | `"new"` | RED/GREEN サイクルで新規実装を行う |
| 既実装確認 | `"verify_existing"` | Phase 4 = targeted test 設計、Phase 5 = diff check に切り替える |
`implementation_mode: "verify_existing"` を選択した場合、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 命名ドリフトが発生する。
3. `agents/design-phases.md` と `agents/generate-task-specs.md` で `index.md` と `phase-*.md` を作る。
4. `agents/output-phase-files.md` と `agents/update-dependencies.md` で `artifacts.json` を整える。
5. `agents/verify-specs.md`、`scripts/validate-phase-output.js`、`scripts/verify-all-specs.js` で gate を通す。
### execute
| Phase | 名称 | 目的 |
| ----- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | 要件定義 | scope、受入条件、inventory を固定する。**既存コードの命名規則（camelCase / kebab-case 等）を分析し記録する**。**[FB-UI-02-2]** 全件 `pnpm test` が SIGKILL 終了するリスクがある場合は、targeted run ファイルリストを Phase 1 で事前列挙する（たとえば、メモリ制約が厳しい環境では vitest の対象ファイル指定が必須となる）。**[carry-over確認]** 前タスクの成果物（`git log --oneline -5` で確認）を棚卸しし、今タスクの新規作業との差異を明確化すること |
| 2 | 設計 | topology、SubAgent lane、validation path を設計する。**[FB-SDK-07-1]** 「既存コンポーネント再利用可否」を必ず確認する。新規 UI 実装ゼロで品質・アクセシビリティ・HIG準拠を既存レベルで担保できる場合は再利用を優先する |
| 3 | 設計レビュー | Phase 4 へ進めるかを判定する |
| 4 | テスト作成 | command suite と expected result を作る。**TDD Red 前に、テストパターンが Phase 1-3 で確認した命名規則と整合しているかを検証する**。**[Feedback P0-09-U1]** private method のテストは `(facade as unknown as FacadePrivate)` キャストまたは public callback 経由を使う方針を Phase 4 仕様書に明記する。**[FB-MSO-002]** テスト実行前に依存関係整合（`pnpm install` + `pnpm --filter @repo/shared build`）を確認する。esbuild darwin バイナリ mismatch は worktree 直後に多発するため、Phase 4 開始前チェックを必須とする |
| 5 | 実装 | `.claude` 正本を更新し、mirror を同期する。**[Feedback RT-03]** 実装計画に「新規作成」「修正」ファイルパス一覧を必須記載する（見落とし防止）。**[Feedback P0-09-U1]** `improve()` フローで SDK callback が不適用な場合（`llmAdapter.sendChat()` 経由など）は「canUseTool 適用可能範囲と制約」を仕様書に明記する |
| 6 | テスト拡充 | fail path、回帰 guard、補助 command を追加する |
| 7 | カバレッジ確認 | concern と dependency edge の coverage を可視化する。**[EMB-005-FB]** NON_VISUAL + 単一クラス追加タスクでは Phase 6 に統合可能（coverage が Phase 6 テストで既に担保できる場合）。**[EVALS-DOC-001]** docs-only タスクでは `totalTests=0 / avgCoverage=0` で EVALS.json taskMetrics を閉じ、カバレッジ確認は「対象コードなし（N/A）」として記録する |
| 8 | リファクタリング | duplicate と navigation drift を削る。**[Feedback RT-03]** 変更内容を `対象/Before/After/理由` テーブル形式で記録する |
| 9 | 品質保証 | line budget、link、mirror parity を一括判定する |
| 10 | 最終レビュー | acceptance criteria と blocker を判定する |
| 11 | 手動テスト | 3層評価（Semantic / Visual / AI UX）を実行し、フィードバックループで HIGH 問題を `unassigned-task/` へ自動生成する。shared path alias 系は build config と test config の parity を同時確認する。**[FB-MSO-003]** 画面証跡取得スクリプトには `try { ... } finally { browser.close(); server.close(); }` パターンを標準化し、ポート解放を確実にする。**[FB-LLM-MOD-05-001]** screenshot ファイル名は phase spec / capture script / metadata / implementation-guide の 4 か所でセマンティック canonical 名（`<component>-<state>.png`）を一致させる（TC-XX 番号はメタデータ内 `tc` フィールドのみ）。詳細: `references/phase-11-screenshot-guide.md` |
| 12 | ドキュメント更新 | implementation guide、spec sync、未タスク、feedback を完了する |
| 13 | PR作成 | user の明示承認後のみ実施する |
## Task仕様ナビ
| Task | 責務 | パターン | 入力 | 出力 |
| ------------------------ | -------------------------- | -------- | ---------------- | --------------------- |
| decompose-task | タスクを単一責務に分解 | seq | ユーザー要求 | タスク分解リスト |
| identify-scope | スコープ・前提・制約を定義 | seq | タスク分解リスト | スコープ定義 |
| design-phases | Phase構成を設計 | seq | スコープ定義 | フェーズ設計書 |
| generate-task-specs | タスク仕様書を生成 | seq | フェーズ設計書 | タスク仕様書一覧 |
| output-phase-files | 個別Markdownファイルを出力 | par | タスク仕様書一覧 | phase-\*.md |
| update-dependencies | Phase間の依存関係を設定 | par | タスク仕様書一覧 | 依存関係マップ |
| verify-specs | 全13仕様書の品質検証 | seq | 検証レポート | PASS/FAIL判定 |
| update-system-specs | システム仕様書を更新 | seq | 実装サマリー | 更新完了チェック |
| generate-unassigned-task | 未完了タスク指示書を生成 | cond | レビュー課題 | unassigned-task/\*.md |
凡例: `seq`=順次実行, `par`=並列実行, `cond`=条件分岐
---
## Phase 12 重要仕様
### 必須タスク（5タスク - 全て完了必須）
| Task | 名称 | 必須 | 詳細参照 |
| ---- | -------------------------------- | ---- | ------------------------------------------- |
| 1 | 実装ガイド作成（2パート構成） | ✅ | 下記参照 |
| 2 | システム仕様書更新（2ステップ） | ✅ | 下記参照 |
| 3 | ドキュメント更新履歴作成 | ✅ | scripts/generate-documentation-changelog.js |
| 4 | 未タスク検出レポート作成 | ✅ | **0件でも出力必須** |
| 5 | スキルフィードバックレポート作成 | ✅ | **改善点なしでも出力必須** |
---
### Task 1: 実装ガイドの2パート構成
| パート | 対象読者 | 内容 |
| ---------- | ------------------------ | ------------------------------------------ |
| **Part 1** | **初学者・中学生レベル** | **概念説明（日常の例え話、専門用語なし）** |
| **Part 2** | **開発者・技術者** | **技術的詳細（スキーマ・API・コード例）** |
**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】
| Step | 必須 | 内容 |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| Step 1-A | ✅ | タスク完了記録（「完了タスク」セクション追加 + 関連ドキュメントリンク + 変更履歴 + LOGS.md×2 + topic-map.md） |
| Step 1-B | ✅ | 実装状況テーブル更新（実装完了:「未実装」→「完了」 / 仕様書作成のみ: `spec_created`） |
| Step 1-C | ✅ | 関連タスクテーブル更新（仕様書内の「関連タスク」「未タスク候補」テーブルのステータス更新） |
| Step 1-D | ✅ | EVALS.json taskMetrics追記（関連スキルの `qualityInsights.taskMetrics.{TASK_ID}` に `completedPhases` / `totalTests` / `avgCoverage` / `systemSpecsUpdated` / `unassignedTasksDetected` を記録。docs-only タスクは `totalTests=0 / avgCoverage=0` で固定） |
| 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 で閉じる。
| Step | `spec_created` での扱い |
| -------- | ------------------------------------------------------------------------- |
| Step 1-A | 完了タスク記録 + LOGS.md x2 + SKILL.md x2 + topic-map を same-wave で更新 |
| Step 1-B | 実装状況テーブルに `spec_created` を記録（`completed` ではない） |
| Step 1-C | 関連タスクテーブルのステータスを current facts へ更新 |
| Step 2 | 新規インターフェース追加がなければ N/A（ただし下記の再判定ルールを確認） |
#### 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件でも出力必須）
| ソース | 確認項目 |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| 元タスク仕様書 | 「スコープ外」として明示された項目 |
| Phase 3/10レビュー結果 | MINOR判定の指摘事項 |
| Phase 11手動テスト | スコープ外の発見事項・改善提案 |
| コードコメント | TODO/FIXME/HACK/XXX |
| `describe.skip` ブロック | 削除したtestid/要素名が旧参照として残存していないか（残存時はcleanupタスクをbacklogに登録） |
```bash
# 未タスク検出スクリプト
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）。
---
## 変更履歴
| Version | Date | Changes |
| ---------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **v10.09.61** | **2026-04-21** | **TASK-RALLY-002 Phase-12 skill-feedback 反映**: `implementation_mode: "verify_existing"` 定義に典型的アウトカム（コメント追加/テスト追加/ドキュメント更新）と false negative 注記を追記。`phase-template-phase12.md` に §verify-all-specs が PASS しても確認すべき項目（false negative 対策）セクションを新設（LOGS.md・lessons-learned・task-workflow・resource-map・skill-feedback の5項目）。`.agents` mirror を同波更新。 |
| **v10.09.60** | **2026-04-21** | **TASK-SC-IMPROVE-PROMPT-IMPL-001 close-out sync**: NON_VISUAL + headless substitute evidence を task-local Phase 11 正本として反映し、Phase 11/12 completed 同期、`artifacts.json` / `outputs/artifacts.json` parity、unassigned follow-up 1件 formalize を同波で記録。 |
| **v10.09.60** | **2026-04-22** | **UNASSIGNED-EVALS-SPEC-QUALITY-INSIGHTS-DOCUMENT-001 skill-feedback 反映**: Phase 12 Task 2 に Step 1-D（EVALS.json taskMetrics追記を必須ステップ化）を追加。Phase 7 実行表に **[EVALS-DOC-001]**（docs-only タスクの `totalTests=0 / avgCoverage=0` 固定ルール）を追記。LOGS.md 同波更新。 |
| **v10.09.59** | **2026-04-21** | **TASK-SW-TODO-001 close-out sync**: `verify_existing + NON_VISUAL` task の Phase 11 evidence を `{TASK-ID}-manual-test-report.md` へ統一しつつ、`manual-test-result.md` に fixed phrase / 実施情報 / 仕様判断根拠 / 実行記録を集約する current pattern を close-out 実例へ反映。Phase 12 compliance-check は Task 12-1〜12-6 / Step 1-A〜1-G / Step 2 を root evidence として確認する運用を usage log に追記。 |
| **v10.09.58** | **2026-04-19** | **UT-IMP-WORKFLOW-CLOSEOUT-PARITY-GUARD-001 parity guard実装**: validate-closeout-parity.js新規追加、complete-phase.js/verify-all-specs.js拡張。Phase 12 close-out parity 必須ゲート化。 |
| **v10.09.57** | **2026-04-19** | **TASK-EVALS-CONSUMER-AUDIT-001 PROPOSAL-TSC-01〜05 反映**: `references/phase-template-audit-task.md` 新設（NON_VISUAL / 監査タスク用 Phase 再解釈マップ、185行）。`phase-12-documentation-guide.md` に固定フレーズ + primary evidence ルールを格上げ。`phase-template-phase11.md` に NON_VISUAL 分岐追加。`phase-template-phase12.md` に canonical N vs 必須 6 成果物分離、未タスク配置先決定フロー図、誤植修正（Task 12-1〜12-5 行削除）を反映。SKILL.md Anchors phase templates に audit-task.md 追加。LOGS.md 同波更新。 |
| **v10.09.55** | **2026-04-21** | **TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001 Phase12 skill-feedback 反映**: `Lessons Learned` セクション新設（FB-01〜FB-04）。Phase 1 仕様書vsクラス名ズレ検出の必須化、Phase 11 NON_VISUAL証跡ファイル名固定、Phase 12正本仕様更新の必須ゲート化、Phase 2クラス名衝突検査を追記。`.agents` mirror を同波更新。 |
| **v10.09.54** | **2026-04-17** | **UT-9I-001 current reference sync**: `phase-12-documentation.md` / `phase-12-completion-checklist.md` / `phase12-checklist-definition.md` / `phase-12-guide.md` / `phase-12-tasks-guide.md` を 6タスク / 6成果物 / current filename へ同期し、`phase-12-docs.md` 旧表記を `phase-12-documentation.md` へ是正。`task-workflow` / `api-ipc` / `interfaces` / `topic-map` / `keywords` / `LOGS.md` の same-wave 更新を記録。 |
| **v10.09.51** | **2026-04-15** | **TASK-CRON-CUSTOM-VALIDATION-001 skill-feedback 反映**: 「よくある漏れ」テーブルに **[VSCPKR-03]**（Phase 4 でコンポーネントテスト設計時に外部 props か内部 state かを Phase 2 で確認せず TDD RED が誤前提になる）を追記。`phase-template-core.md` の Phase 2 セクションに「UI コンポーネントテスト設計時の Props vs internal state 確認」サブセクションを追加。LOGS.md 同波更新。 |
| **v10.09.50** | **2026-04-15** | **TASK-SC-IMP-CREATE-WORKFLOW-001 phase 12 close-out sync**: Phase 12 の 6 成果物（implementation-guide / system-spec-update-summary / documentation-changelog / unassigned-task-detection / skill-feedback-report / phase12-task-spec-compliance-check）を同波で揃え、Part 1 / Part 2 分割、63件 Green、screenshot N/A、`outputs/artifacts.json` parity を current facts に反映。planned wording 直書きを排除し、`runCreateWorkflow` の戻り値観測を guard する方針を明文化。 |
| **v10.09.50** | **2026-04-14** | **UT-W3-ANALYTICS-HTTP-PROVIDER-001 phase12 current facts sync**: `AnalyticsHttpProvider` / `analytics:get-stats` / `sentCount` / `failedCount` を Phase 12 current facts として追記し、`implementation-guide.md` / `system-spec-update-summary.md` / `documentation-changelog.md` / `unassigned-task-detection.md` / `skill-feedback-report.md` / `phase12-task-spec-compliance-check.md` の 6 成果物を current facts へ固定。`LOGS.md` 2ファイルと `.agents` mirror を同波更新。 / **TASK-CI-OPT-001 phase 12 close-out sync**: `docs/30-workflows/task-ci-optimization-001/index.md` の Phase 1-12 を `完了` に同期し、トップステータスを `Phase 12 完了（PR未着手）` に更新。`artifacts.json` を `phase12_completed` へ是正し、`LOGS.md` / `SKILL-changelog.md` / `.agents` mirror を same-wave で閉じる current facts を追加。 |
| **v10.09.49** | **2026-04-14** | **TASK-SW-FIX-STATE-DETAIL-001 skill-feedback / current facts 反映**: `SkillCreateWizard` の stale guard、`ConversationRoundStep` の `answers` prop 再同期、`generationLockRef` の `finally` 解放、Phase 11 evidence の指し直しを current facts として追記。「Phase 12 実行時によくある漏れ」に **[FB-STATE-DETAIL-001]**〜**[FB-STATE-DETAIL-004]** を追加し、`LOGS.md` 同波更新。 |
| **v10.09.50** | **2026-04-15** | **UT-SKILL-WIZARD-NOTION-SPECIAL-CASE-ELIMINATE-001 skill-feedback / current facts 反映**: `SemanticLabelEntry` / `SemanticLabelResult` / `resolveLabelEntry()` / `resolveSemanticLabel()` の current facts を raw fallback 保持へ更新し、`notion` 特別ケース削除を Phase 12 漏れパターンへ昇格。`manual-test-result.md` / `implementation-guide.md` / `phase12-task-spec-compliance-check.md` と `LOGS.md` 同波更新。 |
| **v10.09.48** | **2026-04-13** | **TASK-SW-FIX-FEEDBACK-001 skill-feedback 反映**: 「よくある漏れ」テーブルに **[FB-FEEDBACK-001]**（LLM モード成功後に `fetchSkills()` 明示呼び出しを省略するとスキル一覧が未更新になる / template モードは `createSkill` 内部で自動呼び出し済みのためモード差異に注意）を追記。LOGS.md 2ファイル同波更新。 |
| **v10.09.47** | **2026-04-13** | **UT-SKILL-WIZARD-FB-05-TEST-EVIDENCE-CONSOLIDATION-001 skill-feedback 反映**: Phase 11 テスト証跡テンプレートに EC-NNN / SD-NNN 採番ルール・edge case 一覧表・仕様判断根拠テーブルを導入。テスト件数サマリーを PASS/FAIL/SKIP 5列構成に改訂。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| **v10.09.47** | **2026-04-13** | **UT-W3-ANALYTICS-STORE-INTEGRATION-001 close-out sync**: `analyticsSlice.ts` を helper 化し、`agentSlice.ts` に lifecycle wiring を追加。`packages/shared/src/types/index.ts` / `packages/shared/index.ts` で `SkillAnalyticsEventType` / `SkillAnalyticsEvent` を再公開し、`task-workflow-completed`・`LOGS`・Phase 12 outputs を current facts に同期。 |
| **v10.09.46** | **2026-04-13** | **TASK-UI-SCHEDULE-CRON-MONTHLY-GUARD-001 current facts sync**: 「よくある漏れ」テーブルに **[Feedback 5]**（Phase 12 close-out で `index.md` / `artifacts.json` / `outputs/artifacts.json` を別 wave で更新し、phase table と台帳が一時的に不一致になる）を追記。`outputs/phase-12/` current facts を monthly 逆変換の custom fallback と NON_VISUAL manual-test evidence まで反映し、LOGS.md 2ファイル同波更新。 / **TASK-SW-FIX-DATAFLOW-001 current facts 反映**: `SkillCreationContext` 導入後の dataflow（`buildSkillContext` / `buildSkillGenerationPrompt` / `skill.create(..., context)`）を Phase 12 close-out 観点で知見化。`Phase 12 実行時によくある漏れ` テーブルへ context bridge 同期漏れ（shared型・renderer store・preload/main IPC 契約の同一wave更新漏れ）を追記し、仕様と実装の乖離を防止。 |
| **v10.09.45** | **2026-04-13** | **TASK-UI-SCHEDULE-CRON-SEMANTIC-001 skill-feedback 反映**: 「よくある漏れ」テーブルに **[FB-CRONVL-001]**（Phase 2 ライブラリ採用時の複合フィールド AND/OR semantics 実測確認漏れ）・**[FB-CRONVL-002]**（NON_VISUAL renderer utility の opt-in フラグ追加時に UI 統合経路を別タスク化することを Phase 1 で明示する）を追記。`aiworkflow-requirements/SKILL.md` Trigger キーワードに `ValidateCronOptions` / `cron-parser` / `semantic（cronバリデーション）` 等を追加。LOGS.md 2ファイル同波更新。 |
| **v10.09.44** | **2026-04-12** | **UT-W3-ANALYTICS-ADAPTER-001 skill-feedback 反映**: 「よくある漏れ」テーブルに **[UT-W3]** 3件（`implementation-guide.md` の current contract 旧方針記述 / `artifacts.json` parity 未確認 / `generate-index.js` 省略によるインデックス stale）を追記。 |
| **v10.09.44** | **2026-04-12** | **TASK-CRON-SEMANTIC-VALIDATION-001 Phase 12完了・non-visual task判定基準追加**: 「必須タスク」テーブルを5タスク→6タスクに修正（Task 12-6コンプライアンスチェック追加）。non-visual task判定基準テーブル（Phase 11スクリーンショットN/A・Phase 12-2 Step 2 N/A条件）を追加。未タスク0件判定ソース一覧テーブルを追加。LOGS.md 2ファイル同波更新。 |
| **v10.09.43** | **2026-04-12** | **UT-W3-ANALYTICS-ADAPTER-001 Phase 12 close-out sync**: `outputs/phase-12/` canonical 6成果物の欠落を解消し、`implementation-guide.md` を Part 1/Part 2 構成で current facts に再構成。`artifacts.json` と `outputs/artifacts.json` を `phase12_completed` + `phase13 blocked` で同期し、`index.md` phase status との同値性を回復。`aiworkflow-requirements` 側の analytics / trackEvent / IPC 契約 / task-workflow completed 記録を同 wave で更新し、Phase 12 root evidence を `phase12-task-spec-compliance-check.md` に集約。 |
| **v10.09.43** | **2026-04-11** | **UT-SKILL-WIZARD-W1-DESCRIBE-SKIP-CLEANUP-001 skill-feedback 反映**: 「よくある漏れ」テーブルに **[FB-TASK-01/02]**（testid 削除後の `describe.skip` 内残存参照 CI 非検出問題）を追記。`patterns-lessons-and-pitfalls.md` に describe.skip 内 testid 残存 pitfall を追加。`aiworkflow-requirements/references/lessons-learned-skill-wizard-redesign.md` に L-SKIP-001/002 を追加。LOGS.md 2ファイル同波更新。 |
| **v10.09.42** | **2026-04-11** | **UT-SKILL-WIZARD-W0-CATEGORY-LABEL-MAPPING-001 skill-feedback 反映**: Phase 12 と Phase 13 の境界テーブルに Task 12-6（`phase12-task-spec-compliance-check.md` を root evidence として残す）を追加し Task 12-5 の責務を分離。`SKILL_CATEGORY_LABELS satisfies Record<SkillCategory, string>` パターンによるコンパイル時ラベルドリフト防止を lessons-learned に記録。台帳3点同期（workflow spec / artifacts.json / outputs/artifacts.json）を Phase 12 標準チェックリストに追加。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| **v10.09.41** | **2026-04-11** | **UT-SKILL-WIZARD-FB-04-WORKFLOW-LEDGER-SYNC skill-feedback 反映**: 「よくある漏れ」テーブルに **[FB-04]**（Phase 12 close-out 時の ledger / lane index / artifacts 三者同期漏れ）を追記し、Step 1-A での5ファイル同一wave同期チェックを明文化。mirror (`.agents`) 側にも同差分を反映。 |
| **v10.09.41** | **2026-04-11** | **UT-SKILL-WIZARD-W0-CATEGORY-LABEL-MAPPING-001 skill-feedback 反映**: Phase 12 と Phase 13 の境界テーブルに Task 12-6（`phase12-task-spec-compliance-check.md` を root evidence として残す）を追加し Task 12-5 の責務を分離。`SKILL_CATEGORY_LABELS satisfies Record<SkillCategory, string>` パターンによるコンパイル時ラベルドリフト防止を lessons-learned に記録。台帳3点同期（workflow spec / artifacts.json / outputs/artifacts.json）を Phase 12 標準チェックリストに追加。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| **v10.09.40** | **2026-04-08** | **TASK-SC-13-VERIFY-CHANNEL-IMPLEMENTATION skill-feedback 反映**: 「よくある漏れ」テーブルに Feedback SC-13-1（`ALLOWED_INVOKE_CHANNELS` 追記漏れ対策）・SC-13-2（公開 surface と内部エンジン名衝突時の DTO 変換表必須化）を追記。`api-ipc-system-skill-creator-part2.md` に `skill-creator:verify` チャンネル仕様・DTO 型定義・設計注意点を追加。`lessons-learned-ipc-preload-runtime-2026-04.md` に L-SC13-IPC-001/002 を追加。LOGS.md 同波更新。 |
| **v10.09.39** | **2026-04-08** | **UT-SKILL-WIZARD-W0-RUNTIME-VALIDATION-001 skill-feedback 反映**: 「よくある漏れ」テーブルに Feedback W0-RV-001（境界値テスト文字列の実文字数確認）を追記。`aiworkflow-requirements/references/lessons-learned-current-2026-04.md` に L-RV-001・L-RV-002 を追加。LOGS.md 2ファイル + SKILL.md 同波更新。 |
| **v10.09.38** | **2026-04-08** | **UT-SKILL-WIZARD-W1-par-02b skill-feedback 反映**: `patterns-lessons-and-pitfalls.md` に renderer node-only import pitfall を追加。`phase-template-phase11.md` に UI task VISUAL デフォルトガイドを追加。`phase-12-documentation-guide.md` Task 12-6 に identifier consistency check を追加。「よくある漏れ」テーブルに Feedback W1-02b-1〜4 を追記。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| **v6.18.12〜v6.18.27** | **2026-03-26〜2026-04-07** | 詳細履歴はアーカイブへ移管済み。内容は [LOGS.md](LOGS.md) / [references/logs-archive-2026-march.md](references/logs-archive-2026-march.md) を参照 |
---
### Task 5: スキルフィードバックレポート（改善点なしでも出力必須）
| 観点 | 記録内容 |
| ---------------- | -------------------------------------- |
| テンプレート改善 | Phaseテンプレートの漏れや曖昧さ |
| ワークフロー改善 | 機械検証や手順分岐の改善余地 |
| ドキュメント改善 | 再利用しやすい横断ガイドライン化の候補 |
出力:
- `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 実行時によくある漏れ
| 漏れパターン | 防止方法 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[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 のテンプレート（テスト結果サマリー + 成果物テーブル）に従う |
| `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 は `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", ...)` は使用禁止 |
| **[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 になる | shared 型追加タスクでは `definition + types/index + package index + consumer wiring` を同 wave で揃え、`outputs/artifacts.json` と root artifacts の parity も同時に確認する |
| **[UT-W3-HTTP]** Phase 4 でガード条件（`if (!url)`）の全 falsy パターンを列挙せず、空文字 URL（TC-E04）が Phase 6 でしか検出されなかった | ガード節を設計する際は `undefined` / `null` / `""` / スペースのみの4パターンを同時に列挙し、`!url` が網羅するケースを Phase 4 テスト仕様に明記する |
| 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 は `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-FEEDBACK-001]** LLM モード成功後に `fetchSkills()` の明示呼び出しを省略すると、スキル一覧がリアルタイム更新されず UX が壊れる。template モードは `createSkill`（agentSlice）内部で `fetchSkills` を呼ぶため自動解消されるが、LLM モードの `handleExecutePlan` は明示呼び出しが必要 | `handleExecutePlan` の成功パス末尾に `await fetchSkills()` を追加し、失敗時は遷移を阻害しないよう独立した `try/catch` でswallow する。`TC-FEEDBACK-001` のような LLM モード専用 regression test case を設けて再発を防ぐ |
| **[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宣言」（タスク種別・非視覚的理由・代替証跡）を明記する。空欄や略記はレビューアの混乱を招く |
| **[FB-IPC-SNAP-001]** Electron `ipcMain` の snapshot test で `vi.spyOn(ipcMain, "handle")` を直接使うと、`vi.hoisted` タイミング問題で capture が不安定になる | `vi.hoisted(() => ({ mockIpcMainHandle: vi.fn() }))` + `vi.mock("electron", ...)` + `mockImplementation((ch) => { handles.push(ch) })` のパターンで実装する。`vi.spyOn` を `ipcMain` に直接適用する前提はずらすこと（UT-IPC-HANDLER-CI-001 Pitfall） |
| **[FB-IPC-SNAP-002]** Phase 5 の「実行タスク」に `--updateSnapshot` の初回生成と既存スナップショットとの比較確認が別ステップとして明示されておらず、更新許可条件が曖昧になる | test/CI ガード系タスクの Phase 5 に「初回スナップショット生成（`--updateSnapshot` を明示許可）」と「既存スナップショットとの diff 確認（変更前後の内容比較）」を別ステップとして記載する。更新が許可される条件（新規追加・意図的チャンネル追加）と禁止される条件（未承認のチャンネル増減）を明文化する |
| **[FB-CANCEL-004-1]** `AbortSignal` のような「partial fix しやすい契約ズレ」（Renderer が signal を初期化したが consumer wiring が未完）を完了判定前に発見できず、次タスクで同じ課題が再浮上する | Phase 10 レビュー時に「実装済みの contract が consumer side まで通っているか」を確認する。Renderer/Store/API の3層で断絶がある場合は「partial fix」と明記し、残存部分を residual issue として `unassigned-task-detection.md` に格下げ登録する。格下げテンプレート: `状態: partial_fix / 残存部位: consumer wiring / 対象ファイル: <path>` |
| **[FB-CANCEL-004-2]** `unassigned-task-detection.md` に関連済みタスクとの差分確認欄がなく、重複起票が起きやすい | `unassigned-task-detection.md` のテンプレートに「関連タスク差分確認」セクションを設け、既存タスク ID（`TASK-SC-ABORT-SIGNAL-*` 等）との重複チェックを Phase 12 着手前に実施する。重複している場合は「統合先タスク ID」を明記して未タスク登録を省略可能とする |
### Phase 12 苦戦防止Tips
> UT-STORE-HOOKS-COMPONENT-MIGRATION-001の経験に基づく（2026-02-12）
| Tips | 説明 |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **事前に空欄チェックリストを作成** | documentation-changelog.mdにStep 1-A〜1-D + Step 2の各欄を空欄で事前作成し、逐次消化する |
| **spec-update-workflow.mdを常に参照** | Phase 12開始時に必ず [spec-update-workflow.md](references/spec-update-workflow.md) を開き、チェックリストを確認 |
| **「全Step確認前に完了と記載しない」厳守** | P4パターン。全Stepの結果を個別に記録してから「Phase 12完了」とする |
| **LOGS.md/SKILL.md は4ファイル更新** | aiworkflow-requirements/LOGS.md, task-specification-creator/LOGS.md, aiworkflow-requirements/SKILL.md, task-specification-creator/SKILL.md |
| **topic-map.md再生成はセクション変更時も** | 新規追加だけでなく、セクション更新・削除時も `node .claude/skills/aiworkflow-requirements/scripts/generate-index.js` と `node .claude/skills/task-specification-creator/scripts/generate-index.js --workflow docs/30-workflows/{{FEATURE_NAME}} --regenerate` を実行 |
| **worktree環境でも `.claude` 正本を実更新する** | worktree を理由に LOGS.md / SKILL.md / backlog / workflow の更新を先送りしない。`.agents/skills/` は `rsync` / `diff` で mirror parity を確認する |
| **並列エージェント完了後はファイルシステムで検証** | P43/P59対策。エージェントがコンテキスト制限で応答不能になった場合、`git diff --stat` + `ls outputs/phase-*/` + `artifacts.json` のPhaseステータスで成果物の存在を確認する |
| **NON_VISUAL判定時は `screenshots/.gitkeep` を削除する** | `screenshots/` ディレクトリが空（PNG 0件）のまま残るとvalidator errorになる。NON_VISUAL判定で実スクリーンショットが不要な場合は `screenshots/.gitkeep` を削除してディレクトリごと除外する |
| **worktree作成後は `pnpm install` を確認する** | `esbuild` host/binary version drift により Vitest 起動前に停止することがある。worktree作成後は必ず `pnpm install` を実行してバイナリの整合を確保する |
---
## 重要ルール
### 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 の境界
| Task | 完了条件 | 詳細 |
| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Task 12-1 | `implementation-guide.md` が Part 1/2 を満たす | [references/phase-12-documentation-guide.md](references/phase-12-documentation-guide.md) |
| Task 12-2 | Step 1 と Step 2 の判定が記録される | [references/spec-update-workflow.md](references/spec-update-workflow.md) |
| Task 12-3 | `documentation-changelog.md` と artifacts が同期される | [references/spec-update-validation-matrix.md](references/spec-update-validation-matrix.md) |
| Task 12-4 | 0件でも `unassigned-task-detection.md` を出し、`current/baseline` を分離して記録する | [references/unassigned-task-guidelines.md](references/unassigned-task-guidelines.md) |
| Task 12-5 | 改善点なしでも `skill-feedback-report.md` を出す | [references/patterns-phase12-sync.md](references/patterns-phase12-sync.md) |
| Task 12-6 | `phase12-task-spec-compliance-check.md` を root evidence として残す | [references/patterns-phase12-sync.md](references/patterns-phase12-sync.md) |
| Phase 13 | commit と PR は user の明示承認後だけ | [references/review-gate-criteria.md](references/review-gate-criteria.md) |
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)
## システム観点チェック
| 観点 | aiworkflow-requirements 側の参照先 |
| ------------------ | ---------------------------------- |
| セキュリティ | `security-*.md` |
| UI/UX | `ui-ux-*.md` |
| アーキテクチャ | `architecture-*.md` |
| API/IPC | `api-*.md` |
| データ整合性 | `database-*.md` |
| エラーハンドリング | `error-handling.md` |
| インターフェース | `interfaces-*.md` |
Electron desktop task では Renderer、Main、IPC、Preload、ローカルストレージの境界を都度明記する。詳細は [references/quality-standards.md](references/quality-standards.md) を参照。
## 検証コマンド
```bash
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 を作ること。
## 変更履歴
| Version | Date | Changes |
| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **v10.09.60** | **2026-04-22** | **UNASSIGNED-EVALS-SPEC-QUALITY-INSIGHTS-DOCUMENT-001 skill-feedback 反映**: Phase 12 Task 2 に Step 1-D（EVALS.json taskMetrics 追記を Phase 12 必須ステップとして標準化）を追加。Phase 7 実行表に **[EVALS-DOC-001]**（docs-only タスクでは `totalTests=0 / avgCoverage=0` で固定し「対象コードなし（N/A）」として記録するルール）を追記。LOGS.md 同波更新。 |
| **v10.09.59** | **2026-04-21** | **UNASSIGNED-EVALS-SPEC-QUALITY-INSIGHTS-DOCUMENT-001 close-out sync**: `aiworkflow-requirements/references/evals-schema-spec.md` §6 qualityInsights 定義を実装実態（タスク ID キー辞書）に修正。docs-only タスク Phase 1-12 all PASS（NON_VISUAL / mirror sync 差分ゼロ / AC-1〜7 全達成）。`task-specification-creator/EVALS.json` の `taskMetrics` に本タスク完了エントリを追加（completedPhases=12 / totalTests=0 / avgCoverage=0 / systemSpecsUpdated=2 / unassignedTasksDetected=0）。 |
| **v10.09.58** | **2026-04-20** | **TASK-SC-CANCEL-LOGS-SYNC-001 review-closeout sync**: Phase 11 `manual-test-result.md` を 4 セクション正本へ是正し、Phase 12 `implementation-guide.md` に Part 1/Part 2/`視覚証跡` を追加、`phase12-task-spec-compliance-check.md` の future tense を除去。子 task root `index.md` / `artifacts.json` / `outputs/artifacts.json` を Phase 1-12 completed / Phase 13 blocked へ同期し、`aiworkflow-requirements` completed ledger 追記、unassigned task 2 件起票、`.agents` mirror parity を同波で閉じる手順を current facts に反映。 |
| **v10.09.57** | **2026-04-19** | **TASK-EVALS-CONSUMER-AUDIT-001 PROPOSAL-TSC-01〜05 反映**: (1) PROPOSAL-TSC-01: `references/phase-template-audit-task.md` 新設（NON_VISUAL / 監査タスク向け Phase 再解釈マップ、primary evidence 棲み分け、完了ステータス判断、canonical vs 必須6成果物区別、PR12-R1〜R5 落とし穴集約、185行）。(2) PROPOSAL-TSC-02: `phase-12-documentation-guide.md` Task 12-1 直下に `UI/UX変更なしのため Phase 11 スクリーンショット不要` 固定記載ルールと primary evidence = manual-test-result.md を明記。`phase-template-phase11.md` にタスク種別判定テーブル NON_VISUAL 行追加 + NON_VISUAL / 監査タスク分岐セクション新設。(3) PROPOSAL-TSC-03: `phase-template-phase12.md` 出力テンプレに canonical N 成果物 vs 必須 6 成果物の分離 + P12-R2 リスク対策ルール追加。(4) PROPOSAL-TSC-04: 未タスク配置先決定フロー（If-Then-Else ASCII）を `phase-template-phase12.md` §P38 再発防止セクションに集約。(5) PROPOSAL-TSC-05: `phase-template-phase12.md` の `Task 12-1〜12-5` 誤植行を削除し `Task 12-1〜12-6` に統一。SKILL.md Anchors phase templates に audit-task.md を追加。LOGS.md 同波更新。 |
| **v10.09.57** | **2026-04-19** | **TASK-LOGS-ARCHIVE-POLICY-001 skill-feedback 反映**: docs-only タスクへの Phase 13 フレームワーク適用が機能確認済み。Phase 6〜9（テスト拡充・カバレッジ・リファクタリング・QA）の docs-only 向け読み替え定義が各 Phase に分散しているため、docs-only 専用テンプレートの新設を検討項目として記録。NON_VISUAL Phase 11 の証跡を `manual-test-result.md` チェックリストで代替するパターンを `references/` に追記予定。 |
| **v10.09.57** | **2026-04-19** | **TASK-AGENTS-SKILLS-FULL-SYNC-001 impl-spec-to-skill-sync**: 検証コマンドに `bash .claude/scripts/verify-skills-parity.sh` と `bash .claude/scripts/sync-skills-mirror.sh` を追加（pre-push hook と同一ロジック）。「worktree環境でも `.claude` 正本を実更新する」行を書き換え、`sync-skills-mirror.sh` による同期と `verify-skills-parity.sh` による parity 0 確認を明示。避けるべきことに「pre-push を `--no-verify` でスキップ」を追加。 |
| **v10.09.56** | **2026-04-18** | **UT-IPC-HANDLER-CI-001 skill-feedback 反映**: 「Phase 12 実行時によくある漏れ」テーブルに **[FB-IPC-SNAP-001]**（Electron ipcMain snapshot test で vi.spyOn 直接適用が不安定になる / vi.hoisted + vi.mock パターンを使う）・**[FB-IPC-SNAP-002]**（Phase 5 に --updateSnapshot 初回生成と比較確認を別ステップとして明示する）を追記。LOGS.md 2ファイル同波更新。 |
| **v10.09.55** | **2026-04-17** | **TASK-UT-9I-001 Phase-12 検証完了**: Phase-12成果物全6ファイルPASS確認。implementation-guide.md / system-spec-update-summary.md / documentation-changelog.md / unassigned-task-detection.md / skill-feedback-report.md / phase12-task-spec-compliance-check.md の存在・内容を検証し全87項目PASS。Phase 11 BLOCKED（API_KEY未設定）でも Phase 12 ドキュメントは作成可能な非依存性を記録。 |
| **v10.09.53** | **2026-04-16** | **TASK-LLM-MOD-05-RENDERER-DESC-DISPLAY current facts sync**: Phase 11 screenshot canonical 名を `inline-model-selector-description-hidden.png` / `inline-model-selector-tooltip-visible.png` に統一し、`phase11-capture-metadata.json` / `manual-test-result.md` / `implementation-guide.md` / completed ledger を同波で更新。`TASK-LLM-MOD-05` completed 化に合わせ、`Phase 12 実行時によくある漏れ` に **[FB-VISUAL-CAP-001]** を追加。 |
| **v10.09.52** | **2026-04-16** | **TASK-SC-PLAN-CONNECT-GENERATE-SKILL-MD-001 phase 12 close-out sync**: `.claude` canonical を先に更新し、`.agents` mirror を同内容で追従する接続順序を固定。`LOGS.md` に 2026-04-16 の close-out sync を追記し、Phase 12 current facts を最新化。 |
| **v10.09.52** | **2026-04-16** | **TASK-SC-LLM-PURPOSE-WIRE-001 phase 12 close-out sync**: Phase 2 で `Result<T,E>` の `success` / `data` 判別子と `@repo/shared/services/llm/types` alias を先に固定しないと、旧 TC-04 の影響を見落としやすいことを feedback 化。Phase 12 の 6 成果物と `LOGS.md` 2ファイル同波更新を記録。 |
| **v10.09.50** | **2026-04-15** | **TASK-SC-IMP-CREATE-WORKFLOW-001 phase 12 close-out sync**: Phase 12 の 6 成果物と current facts を同波で固定し、`outputs/artifacts.json` parity、63件 Green、screenshot N/A を反映。`runCreateWorkflow` の戻り値観測を guard する方針と、planned wording の直書き排除を反映。 |
| **v10.09.50** | **2026-04-15** | UT-SKILL-WIZARD-NOTION-SPECIAL-CASE-ELIMINATE-001 フィードバック反映: `SemanticLabelEntry` / `resolveLabelEntry()` / raw fallback 保持を current facts に追加し、`Phase 12 実行時によくある漏れ` に **[FB-NOTION-001]** を追加。 |
| **v10.09.46** | **2026-04-13** | TASK-UI-SCHEDULE-CRON-MONTHLY-GUARD-001 フィードバック反映: (1) `Number.isInteger` ガードを先頭に置くパターンを標準化 (2) 双方向ガード（converter + parser）セット実装を推奨事項に追加 (3) switch-case ガードのブロック構文対称パターンを記録 |
| **v10.09.22〜v10.09.33** | **2026-03-04〜2026-04-03** | 詳細履歴はアーカイブへ移管済み。内容は [LOGS.md](LOGS.md) / [references/logs-archive-2026-march.md](references/logs-archive-2026-march.md) を参照 |
> 補足: v9.89.0 以前の履歴は `LOGS.md` に保持（監査証跡を維持）。
詳細な履歴と usage log は [LOGS.md](LOGS.md) と [references/logs-archive-index.md](references/logs-archive-index.md) を参照。Related Skills
skill-creator
5
from daishiman/AIWorkflowOrchestrator
スキルを作成・更新・プロンプト改善するためのメタスキル。 **最初のアクションは必ず AskUserQuestion**（インタビュー深度確認）。 **collaborative**モードでユーザーと対話しながら共創し、 抽象的なアイデアから具体的な実装まで柔軟に対応する。 **orchestrate**モードでタスクの実行エンジン（Claude Code / Codex / 連携）を選択。 Anchors: • Continuous Delivery (Jez Humble) / 適用: 自動化パイプライン / 目的: 決定論的実行 • The Lean Startup (Eric Ries) / 適用: Build-Measure-Learn / 目的: 反復改善 • Domain-Driven Design (Eric Evans) / 適用: 戦略的設計・ユビキタス言語・Bounded Context / 目的: ドメイン構造の明確化 • Clean Architecture (Robert C. Martin) / 適用: 依存関係ルール・層分離設計 / 目的: 変更に強い高精度スキル • Design Thinking (IDEO) / 適用: ユーザー中心設計 / 目的: 共感と共創 Trigger: 新規スキルの作成、既存スキルの更新、プロンプト改善を行う場合に使用。 スキル作成, スキル更新, プロンプト改善, skill creation, skill update, improve prompt, Codexに任せて, assign codex, Codexで実行, GPTに依頼, 実行モード選択, どのAIを使う, IPC Bridge統一, API統一パターン, safeInvoke/safeOn, Preload API標準化, IPC handler registration, Preload API integration, contextBridge, Electron IPC pattern, extractPurposeWithLlm, ILLMClient, AnthropicProvider, normalizePurposeResponse, LLM purpose extraction, LLM DI pattern, extract-purpose agent wiring
malformed-skill
5
from daishiman/AIWorkflowOrchestrator
This YAML has a syntax error
test-skill
5
from daishiman/AIWorkflowOrchestrator
E2Eテスト用のスキル
another-skill
5
from daishiman/AIWorkflowOrchestrator
別のテスト用スキル
fixture-partial-skill
5
from daishiman/AIWorkflowOrchestrator
テスト用部分構成スキル
fixture-orchestration-skill
5
from daishiman/AIWorkflowOrchestrator
テスト用オーケストレーションスキル
missing-fields-skill
5
from daishiman/AIWorkflowOrchestrator
No description provided.
fixture-minimal-skill
5
from daishiman/AIWorkflowOrchestrator
テスト用最小構成スキル
fixture-invalid-skill
5
from daishiman/AIWorkflowOrchestrator
This is invalid: because of unquoted colon
fixture-invalid-schema-skill
5
from daishiman/AIWorkflowOrchestrator
Skill with invalid JSON schema for testing
Invalid_Name_With_Uppercase
5
from daishiman/AIWorkflowOrchestrator
Skill with invalid non-kebab-case name
fixture-forbidden-files-skill
5
from daishiman/AIWorkflowOrchestrator
Skill with forbidden files for testing