ln-310-story-validator

パス： ファイルパス（shared/、references/、../ln-*）は、skills リポジトリのルートからの相対パスです。CWD に見つからない場合は、この SKILL.md ディレクトリを見つけて、1 階層上をリポジトリのルートとして使用してください。

ストーリー検証スキル

明確な GO／NO-GO 判定、準備スコア、ハルシネーション防止検証を用いて、ストーリー／タスクを検証します。

入力

入力	必須	ソース	説明
storyId	はい	引数、git ブランチ、かんばん、ユーザー	処理するストーリー

解決方法： shared/references/input_resolution_pattern.md のストーリー解決チェーンに従います。 ステータスフィルター： Backlog

目的と範囲

• ストーリーと子タスクを、業界標準およびプロジェクトのパターンに照らして検証します
• 違反に対するペナルティポイントを算出し、ポイントが 0 になるまで自動修正します
• ドキュメント（ガイド、マニュアル、ADR、調査資料）の作成を ln-002-best-practices-researcher に委任します
• プランモードをサポートします。監査結果を提示して承認を待ってから、修正します
• 修正後に、表形式の出力サマリーを添えてストーリーを承認します（Backlog -> Todo）

使用する場面

• 承認前にストーリーをレビューする場合（Backlog -> Todo）
• ストーリーとタスク全体にわたる実装方針を検証する場合
• 標準、アーキテクチャ、ソリューションの適合性を確認する場合
• 提案されたアプローチを最適化または修正する場合

ペナルティポイントシステム

目標： ストーリー／タスクの品質を定量的に評価します。修正後の目標はペナルティポイント 0 です。

重大度	ポイント	説明
CRITICAL	10	RFC／OWASP／セキュリティ違反
HIGH	5	古いライブラリ、アーキテクチャ上の問題
MEDIUM	3	ベストプラクティス違反
LOW	1	構造上／外観上の問題

ワークフロー：

1. 監査：22 項目すべての基準についてペナルティポイントを算出します
2. 修正：自動修正してポイントをゼロにします
3. 報告：修正前の合計 -> 修正後の 0

モードの検出

起動時に動作モードを検出します。

プランモードが有効な場合：

• フェーズ 1～2：完全な監査（調査 + リサーチ + ペナルティ算出）
• フェーズ 3：結果と修正計画を提示 -> ユーザーの承認を待ちます
• フェーズ 4～6：承認後に修正を実行します

通常モード：

• フェーズ 1～6：中断せずに標準ワークフローを実行します
• 自動で修正し、承認します

プランモード：TodoWrite による進捗管理

どのモードで動作する場合でも、このスキルはすべてのフェーズと手順を追跡する詳細な Todo チェックリストを作成する必要があります。

ルール：

1. フェーズ 1 の前に、ただちに Todo を作成します
2. フェーズの各手順を、個別の Todo 項目にします
3. 手順の開始前に in_progress、完了後に completed に設定します

Todo テンプレート（約 21 項目）：

Phase 1: Discovery & Loading
  - Auto-discover configuration (Team ID, docs)
  - Load Story metadata (ID, title, status, labels)
  - Load Tasks metadata (1-8 implementation tasks)

Phase 2: Research & Audit
  - Extract technical domains from Story/Tasks
  - Delegate documentation creation to ln-002
  - Research via MCP Ref (RFC, OWASP, library versions)
  - Verify technical claims (Anti-Hallucination)
  - Calculate Penalty Points (22 criteria)

Phase 3: Audit Results & Fix Plan
  - Display Penalty Points table and fix plan
  - Wait for user approval (Plan Mode only)

Phase 4: Auto-Fix (8 groups)
  - Fix Structural violations (#1-#4)
  - Fix Standards violations (#5)
  - Fix Solution violations (#6, #21)
  - Fix Workflow violations (#7-#13)
  - Fix Quality violations (#14-#15)
  - Fix Dependencies violations (#18-#19/#19b)
  - Fix Risk violations (#20)
  - Fix Traceability violations (#16-#17)

Phase 5: Agent Review (MANDATORY — delegated to ln-311)
  - [MANDATORY] Invoke ln-311-agent-reviewer with story_ref + tasks_ref
  - [MANDATORY] Process and apply accepted suggestions to Story/Tasks

Phase 6: Approve & Notify
  - Set Story/Tasks to Todo status in Linear
  - Update kanban_board.md with APPROVED marker
  - Add Linear comment with validation summary
  - Display tabular output to terminal

ワークフロー

フェーズ 0：ツール設定

必須の読み込み： shared/references/tools_config_guide.md、shared/references/storage_mode_detection.md、shared/references/input_resolution_pattern.md を読み込みます

docs/tools_config.md を読み込みます（見つからない場合は、tools_config_guide.md に従って初期化します）。 task_provider = Task Management → Provider（linear | file）を抽出します。

以降のすべてのフェーズでは、storage_mode_detection.md に従い、task_provider を使って操作を選択します。

フェーズ 1：調査と読み込み

手順 1：storyId の解決（input_resolution_pattern.md に従う）：

• 引数が指定されている場合 → その引数を使用します
• それ以外で git ブランチが feature/{id}-* に一致する場合 → id を抽出します
• それ以外で、かんばんに [Backlog] のストーリーがちょうど 1 件ある場合 → そのストーリーを提案します
• それ以外の場合 → AskUserQuestion：かんばんから [Backlog] で絞り込んだストーリーを表示します

手順 2：設定とメタデータの読み込み

• 設定を自動検出します：チーム ID（docs/tasks/kanban_board.md）、プロジェクトドキュメント（CLAUDE.md）、Story.project からエピックを特定します
• メタデータのみ読み込みます：ストーリーの ID／タイトル／ステータス／ラベル、子タスクの ID／タイトル／ステータス／ラベル
  • task_provider が linear の場合：get_issue(storyId) + list_issues(parentId=storyId)
  • task_provider が file の場合：Read story.md + Glob("docs/tasks/epics/*/stories/*/tasks/*.md")
• 実装タスクは 1～8 件を想定し、絞り込み用に parentId を記録します
• 理由：読み込みを軽量に保ち、完全な説明はフェーズ 2 で取得します

フェーズ 2：調査と監査

必ず読むこと： 調査と監査の手順全体を確認するため、references/phase2_research_audit.md を読み込みます。

• ストーリー／タスクからのドメイン抽出
• ln-002 へのドキュメント作成の委任（ガイド／マニュアル／ADR）
• MCP の調査（Ref + Context7 を使用した RFC／OWASP／ライブラリのバージョン）
• ハルシネーション防止の検証（根拠に基づく主張）
• ペナルティポイントの計算（22 項目。同じファイル内の自動修正アクションのリファレンスを参照）

すべてのストーリーで例外なく、必ず実行してください。

フェーズ 3：監査結果と修正計画

監査結果を表示します：

• ペナルティポイントの表（基準、重大度、ポイント、説明）
• 合計：X ペナルティポイント
• 修正計画：各基準に対する修正の一覧

モードの処理：

• 計画モードの場合： 結果を表示し、「承認後に変更を適用します」と伝えて、待機します
• それ以外（通常モード）の場合： 直ちにフェーズ 4 に進みます

フェーズ 4：自動修正

22 項目すべての修正をその場で実行します。

• 実行順序（8 グループ）：
  1. 構造（#1〜#4） — ストーリー／タスクのテンプレート準拠と、AC の完全性／具体性
  2. 標準（#5） — RFC／OWASP への準拠を最優先で対応します（YAGNI／KISS より先）
  3. ソリューション（#6、#21） — ライブラリのバージョン、代替ソリューション
  4. ワークフロー（#7〜#13） — テスト戦略、ドキュメントの統合、規模、クリーンアップ、YAGNI、KISS、タスクの順序
  5. 品質（#14〜#15） — ドキュメントの完全性、ハードコードされた値
  6. 依存関係（#18〜#19／#19b） — ストーリー／タスクの独立性（先行タスクへの依存なし）、並列グループの妥当性
  7. リスク（#20） — 実装リスクの分析（依存関係の解消後、トレーサビリティの確認前）
  8. 検証（#22） — すべてのタスク AC に対して AC の検証方法（テスト／コマンド／確認）が存在すること
  9. トレーサビリティ（#16〜#17） — ストーリーとタスクの整合性、AC のカバレッジ品質（すべての修正の後、最後に実行）
• 下記の自動修正アクション表を正式なチェックリストとして使用します
• 修正を適用するたびにペナルティポイントをゼロにします
• テスト戦略のセクションは必須ですが、空のままにします（テストは別途対応します）

フェーズ 5：エージェントレビュー（必須 — 省略禁止）

必須ステップ： このフェーズはフェーズ 4 の結果にかかわらず必ず実行します。エージェントレビューの省略はワークフロー違反です。エージェントを利用できない場合、ln-311 は SKIPPED を返します。これは許容されますが、呼び出しは必ず行ってください。

Skill(skill="ln-311-agent-reviewer", args="{storyId}") を呼び出します。

• ln-311 は Linear からストーリー／タスクの参照情報を取得し、参照情報を含むプロンプトを作成して、エージェントを並列実行し、プロンプトと結果を .agent-review/{agent}/ に保存します。
• 判定が SUGGESTIONS の場合 → 承認した提案をストーリー／タスクのテキストに適用します。
• 判定が SKIPPED（エージェントがいない、またはすべて失敗）の場合 → 変更を加えずにフェーズ 6 に進みます。
• 表示： ln-311 の出力からエージェント統計を表示します：「Agent Review: {agent_stats summary}」

フェーズ 6：承認と通知

• ストーリーとすべてのタスクを Todo に設定し、kanban_board.md を APPROVED マーカーで更新します。
  • task_provider = linear の場合：ストーリーと各タスクに対して save_issue({id, state: "Todo"}) を実行します
  • task_provider = file の場合：story.md と各タスクファイルの **Status:** 行を Todo に編集します
• 検証概要コメントを追加します：
  • task_provider = linear の場合：ストーリーに create_comment({issueId, body}) を実行します
  • task_provider = file の場合：コメントを docs/tasks/epics/.../comments/{ISO-timestamp}.md に書き込みます
  • 内容：ペナルティポイント表（修正前 -> 修正後 = 0）、適用した自動修正、作成したドキュメント（ln-002 経由）、標準への準拠を示す根拠
• ターミナルに表形式の出力（Unicode の罫線文字）を表示します
• 最終結果：合計ペナルティポイント = 0
• 次の推奨ステップ： ストーリーの実行を開始するために ln-400-story-executor を使用します

自動修正アクションのリファレンス

必ずお読みください： references/phase2_research_audit.md を読み込み、次の項目を含む21基準の全表を確認してください。

• 構造（#1-#4）：ストーリー／タスクのテンプレート準拠
• 標準（#5）：RFC／OWASP 準拠
• ソリューション（#6、#21）：ライブラリのバージョン、代替案
• ワークフロー（#7-#13）：テスト戦略、ドキュメント、規模、YAGNI／KISS、タスクの順序
• 品質（#14-#15）：ドキュメント、ハードコードされた値
• トレーサビリティ（#16-#17）：ストーリーとタスクの整合性、AC の網羅性
• 依存関係（#18-#19／#19b）：後続への依存関係がないこと
• リスク（#20）：実装リスク分析

最大ペナルティ： 88 ポイント（22 基準の合計。#20 は最大15ポイント）

最終評価モデル

すべての修正を適用した後の出力：

指標	値	意味
ゲート	GO / NO-GO	実行準備の最終判定
準備スコア	1-10	品質に対する確信度
ペナルティポイント	0（修正後）	検証の完全性
ハルシネーション防止	VERIFIED / FLAGGED	技術的な主張を検証済み
AC カバレッジ	100%（N/N）	すべての AC がタスクに対応付けられている

準備スコアの計算

Readiness Score = 10 - (Penalty Points / 5)

修正前／修正後の診断： フェーズ3で初期のペナルティポイントと準備スコア（修正前）を計算します。フェーズ4の自動修正によりペナルティが0になり、準備スコアは10（修正後）になります。透明性を確保するため、両方の値を最終評価に記載します。

ゲート	条件
GO	フェーズ4終了後のペナルティポイント = 0（準備スコア = 10）
NO-GO	修正不可能な基準が1つでも FLAGGED とされている（「重要なルール」を参照）

ハルシネーション防止の検証

技術的な主張に根拠があることを検証します。

主張の種類	検証
RFC／標準への言及	MCP Ref の検索で存在を確認
ライブラリのバージョン	Context7 のクエリでバージョンを確認
セキュリティ要件	OWASP／CWE への言及が存在する
パフォーマンスに関する主張	ベンチマーク／ドキュメントへの言及

ステータス： VERIFIED（すべての主張に出典あり）または FLAGGED（未検証の主張を列挙）

タスクと AC の対応マトリックス

明示的な対応付けを出力します。

| AC | Task(s) | Coverage |
|----|---------|----------|
| AC1: Given/When/Then | T-001, T-002 | ✅ |
| AC2: Given/When/Then | T-003 | ✅ |
| AC3: Given/When/Then | — | ❌ UNCOVERED |

カバレッジ： {covered}/{total} ACs（目標：100%）

セルフ監査プロトコル（必須）

フェーズ6に進む前に、自動修正アクションの全22基準（#1-#22）が、具体的な証拠（ドキュメントのパス、MCP の結果、Linear の更新）によって満たされていることを確認します。

重要なルール

• フェーズ6（セルフ監査プロトコル）に進む前に、全22基準を具体的な証拠（ドキュメントのパス、MCP の結果、Linear の更新）で検証する必要があります
• 修正の実行順序は厳守してください：構造 -> 標準 -> ソリューション -> ワークフロー -> 品質 -> 依存関係 -> リスク -> トレーサビリティ（YAGNI／KISS より先に標準へ対応）
• ペナルティポイントが0を超えた状態で承認してはいけません。違反はすべて自動修正して0にする必要があります。基準を自動修正できない場合（例：MCP Ref が利用できない、外部依存関係がある）は、理由とともに FLAGGED とし、ペナルティを残してください。この場合、ゲートは NO-GO となり、ユーザーが手動で解決する必要があります
• テスト戦略のセクションは必須ですが、空のままにしてください（テストは他のスキルが別途担当します）
• プランモードでは、フェーズ3の終了後に必ず停止し、修正を適用する前にユーザーの承認を待ってください

完了の定義

• フェーズ1〜6を完了していること：メタデータの読み込み、調査、ペナルティの計算、修正の適用、エージェントによるレビュー、ストーリーの承認。
• ペナルティポイント = 0（全22基準を修正済み）。準備スコア ≥ 5。
• ハルシネーション防止：VERIFIED（すべての主張に MCP 経由の出典あり）。
• AC カバレッジ：100%（各 AC が1つ以上のタスクに対応付けられている）。
• エージェントレビュー：ln-311 を実行し、提案を集約・検証し、承認された提案を適用する（エージェントがいない場合は SKIPPED）。
• ストーリー／タスクを Todo に設定し、カンバンを更新し、最終評価を記載した Linear コメントを投稿する。

ワークフローの例

ストーリー：「レート制限付きのユーザー管理 API を作成する」

1. **フェーズ 1：**メタデータを読み込む（タスク 5 件、ステータスは Backlog）
2. フェーズ 2：
   • ドメインの抽出：REST API、レート制限
   • ln-002 に委任：Guide-05（REST パターン）、Guide-06（レート制限）を作成
   • MCP Ref：RFC 7231 への準拠、OWASP API Security
   • Context7：Express v4.19（現在は v4.17）
   • ペナルティポイント：合計 18（バージョン=5、ドキュメント不足=5、構造=3、標準=5）
3. フェーズ 3：
   • ペナルティポイントの表を表示
   • IF Plan Mode：「ペナルティポイントが 18 件見つかりました。修正計画の準備ができました。承認しますか？」
4. フェーズ 4：
   • 修正 #6：Express v4.17 を v4.19 に更新
   • 修正 #5：RFC 7231 への準拠に関する注記を追加
   • 修正 #13：Guide-05、Guide-06 の参照を追加
   • 修正 #17：ドキュメントは ln-002 によってすでに作成済み
   • すべての修正を適用し、ペナルティポイントは 0
5. **フェーズ 5：**エージェントによるレビュー（ln-311-agent-reviewer に委任 → 承認された提案を適用）
6. **フェーズ 6：**ストーリー → Todo、表形式のレポート

テンプレートの読み込み

テンプレート： story_template.md、task_template_implementation.md

読み込みロジック：

1. 対象プロジェクトに docs/templates/{template}.md が存在するか確認
2. 存在しない場合： a. docs/templates/ ディレクトリがなければ作成 b. shared/templates/{template}.md → docs/templates/{template}.md にコピー c. ローカルコピー内のプレースホルダーを置換：
   • {{TEAM_ID}} → docs/tasks/kanban_board.md から取得
   • {{DOCS_PATH}} → 「docs」（標準）
3. すべての検証処理でローカルコピー（docs/templates/{template}.md）を使用

**理由：**初回使用時にテンプレートを対象プロジェクトにコピーすることで、以下を実現します。

• プロジェクトの独立性（スキルリポジトリに依存しない）
• カスタマイズ可能（プロジェクトでローカルテンプレートを変更できる）
• コピー時にプレースホルダーを一度だけ置換

参照ファイル

• ツール設定： shared/references/tools_config_guide.md
• ストレージモードの操作： shared/references/storage_mode_detection.md
• AC 検証ルール： shared/references/ac_validation_rules.md
• プランモードの動作： shared/references/plan_mode_pattern.md
• 最終評価： references/readiness_scoring.md（GO/NO-GO ルール、Readiness Score の計算）
• テンプレート（集中管理）： shared/templates/story_template.md、shared/templates/task_template_implementation.md
• ローカルコピー： docs/templates/（対象プロジェクト内）
• 検証チェックリスト（段階的開示）：
  • references/structural_validation.md（基準 #1～#4）
  • references/standards_validation.md（基準 #5）
  • references/solution_validation.md（基準 #6）
  • references/workflow_validation.md（基準 #7～#13）
  • references/quality_validation.md（基準 #14～#15）
  • references/dependency_validation.md（基準 #18～#19/#19b）
  • references/risk_validation.md（基準 #20）
  • references/traceability_validation.md（基準 #16～#17）
  • references/domain_patterns.md（ln-002 への委任用パターンレジストリ）
  • references/penalty_points.md（ペナルティシステムの詳細）
• 予防チェックリスト： shared/references/creation_quality_checklist.md（作成者向けの 22 基準対応表）
• Linear 連携： ../shared/templates/linear_integration.md
• 必読： shared/references/research_tool_fallback.md

---

バージョン： 7.0.0 最終更新日： 2026-02-03