run-system-spec-elicit

run-system-spec-elicit

システム構築の仕様を、まず 上位概念 (本質的目的/背景/ゴール/目標/成功基準/具体的やりたいこと U1-U9) を深掘りヒアリングで確定し (R0-foundation)、その上で カテゴリ×canonical platform id の収集マトリクスを往復ヒアリングで終端化する L1 skill。ユーザーが決めきれない項目は R5 が最新公式根拠付き2〜3案（無料/低コスト案を含む）を目的適合で比較し、AI推奨・理由・注意点を示してユーザー確認へ導く。foundation / decisions / matrix の書込は本 skill 所有の単一 transition writerのみ。

上位概念 anchor (要件 C9・spec drift 防止)

上位概念がブレると、仕様が整ってもブレる。技術マトリクス (下位概念) の手前で上位概念 (U1-U9) を最初にしっかり抽出して requirements_foundation に固定し、各技術決定 (確定セル) を serves_goals でそこへトレース (anchor) する。どのゴールにも資さない収集は drift として検出する。

• bootstrap サブコマンドが空のstate envelope ($CLAUDE_PROJECT_DIR/system-spec/spec-state.json) を作り、R0-foundation が set-foundation op で requirements_foundation (U1-U9) を確定してから R1-init (init サブコマンド) がtaxonomyをpopulateする。R1は既存foundation/decisionsを保持し、上位概念が曖昧なまま技術ヒアリングへ進まない。
• 各 確定 セルに serves_goals: [<goal_id>, ...] を付与 (confirm 同時付与 or set-serves op) し、どの上位概念に資するかを明示する。
• C03 (run-system-spec-compile) は requirements_foundation を system-spec/00-requirements-definition.md (要件定義書=憲法) として先頭章に生成し、各技術章 frontmatter に serves_goals を持たせて全章を貫通させる。
• 検証: ../../scripts/validate-coverage-matrix.py --require-foundation が U1-U5 非空・各確定セルの serves_goals トレース・drift 候補を機械検証する (opt-in)。

Purpose & Output Contract

入力: ヒアリング応答 (対話) / 既存 spec-state.json (resume 時) / C04 taxonomy。 出力: spec-state.json (references/spec-state-contract.md の形状。plugin 共有データ契約。上位概念 requirements_foundation を含む)。 完了条件: requirements_foundation が確定 (U1-U9 が値または明示 N/A+理由・ただし U1/U2/U3 は値必須で N/A 不可・U1-U9 要約のユーザー承認 approval_ref 付き・confirmed: true) し、全セルが 確定(qa_ref 付き) か 対象外(reason か approval_ref 付き) で、未収集0。validate-coverage-matrix.py --require-complete --require-foundation が exit0。加えて ../../scripts/validate-knowledge-graph.py --profile required-info --input references/required-info-catalog.json の coverage_certificate.blocking_items が空 (missing_effect=block の必須情報が全て確定に接地) である。

• platforms (6): web / mobile / tablet / desktop-windows / desktop-linux / desktop-macos。
• cell states (3値, loop 中): 未収集 / 対象外 / 確定。最終時は 未収集 を0にする。
• category_aggregate (4値): 真理値表から導出 (直接指定しない)。全セル未収集=未着手 / 未収集混在=収集中 / 全セル対象外=対象外 / それ以外で未収集0=確定。
• カテゴリ初期集合の正本: C04 plugins/system-spec-harness/skills/ref-system-design-knowledge/references/system-category-taxonomy.json を Read して得る (prompt へ直書き禁止)。

単一 transition writer 防御 (SSOT)

spec-state.json への状態書込は scripts/apply-spec-transition.py の一経路のみ。本 writer は以下を機械的に強制する:

1. 確定巻き戻しの拒否: 確定 セルを confirm / exclude で直接変更しようとすると TransitionError で拒否する。Bash や別 script から CLI を叩いても同じく拒否される (single-writer 防御)。
2. R4-reopen 経由のみ確定変更: 確定 セルの状態を動かせるのは action=reopen (要 reason) だけ。reopen は当該セルを 未収集 へ戻し reopen_log に根拠を残す。その後 confirm / exclude で再遷移できる。
3. 確定/対象外の付帯必須: confirm は qa_ref (qa_log entry 参照) 必須、exclude は reason か approval_ref (approval_log 参照) 必須。
4. 集約は導出のみ: category_aggregate は真理値表から再計算する。手書き代入を認めない。

本文・prompt・CLI いずれの経路でも、マトリクスの状態遷移は上記 writer を経由すること。直接 JSON 編集で 確定→未収集 を書くのは契約違反。

責務 (prompts/)

id	prompt	責務
R0-foundation	prompts/R0-foundation.md	マトリクス収集の手前で上位概念 (U1-U9) を深掘りヒアリング (5 Whys で U1・JTBD で U6) し set-foundation で requirements_foundation を確定。未確定は再質問し放置しない。
R1-init	prompts/R1-init.md	C04 taxonomy を Read し、カテゴリ×6必須platform の全存在(対象外は理由付き)を検証して初期化。カテゴリ軸の拡張発見もここ。
R2-interview	prompts/R2-interview.md	未収集セルを対象に 質問→回答→仕様反映 の往復で各セルを 確定 か 対象外+理由 へ遷移。
R3-reask	prompts/R3-reask.md	未確定セルを再質問。1 invocation の 5 loop 到達時は未完了状態と next_question を保存し resumable な結果を返す。未収集を完了扱いしない。
R4-reopen	prompts/R4-reopen.md	確定済みセルを根拠付きで再オープンし追加質問サイクルへ戻す。reopen 非経由の確定直接変更は writer が遮断する。
R5-decision-guide	prompts/R5-decision-guide.md	needs_guidance を最新公式情報とC04 deep knowledgeから2〜3案へ展開し、無料/低コスト案を含めgoal fit/TCO/security/operations/lock-inで比較。AI推奨はrecommended_pending_confirmation、ユーザー選択だけをconfirmedにする。加えて ../../scripts/validate-knowledge-graph.py --profile required-info --input references/required-info-catalog.json の coverage_certificate.blocking_items (missing_effect=block の未充足 item) が空になるまで当該 domain の確定セルの confirmed を禁じる収集ゲートを課し、--profile knowledge --order の topo_order (上位概念→下位概念) 順で知識を消費する。

ゴールシーク実行

• engine=inline / fork=subagent / max_loops=5 / loop_semantics = per-invocation chunk limit。
• 1 invocation で最大 5 loop (質問→回答→反映) を回す。5 loop 到達で未収集が残れば hearing_progress.complete=false と next_question を保存し、resumable に返す (--resume で続行)。
• 未収集0を満たしたときだけ complete=true・next_question=null。未収集セルを完了扱いしない。
• ループの各周回は「未達 = 未収集セル」を最小化する手順を都度立案→ writer で適用→ validate-coverage-matrix.py で検証、を繰り返す (固定手順を持たない)。

feedback-contract (with-feedback-contract)

• IN1 (inner / script): python3 ../../scripts/validate-coverage-matrix.py --matrix spec-state.json が exit0 (loop 中の網羅性)。R0-foundation 完了後は --require-foundation を付けて python3 ../../scripts/validate-coverage-matrix.py --matrix spec-state.json --require-foundation も exit0 とし、上位概念 U1-U9・decisions 契約・serves_goals トレースを段階的に課す (foundation 未確定の R0 完了前には課さない)。
• OUT1 (outer / test): 最終 spec-state.json を --require-complete が exit0 で受理し、受入テスト (tests/) が resume 保存を含めて再現する。
• 収集ゲート (C16 / IN1 補完): ../../scripts/validate-knowledge-graph.py --profile required-info --input references/required-info-catalog.json が exit0 かつ coverage_certificate.blocking_items が空。missing_effect=block の必須情報 (product-goal / target-platforms / domain-model / auth-model / security-posture) が確定に接地するまで当該 domain の確定セルの confirmed を許さない (R5 が prose ゲートとして施行し、決定論 writer=apply-spec-transition への block 検査組込は follow-up)。

使い方 (ゴールへ向けた反復)

spec-state.json の正本位置は $CLAUDE_PROJECT_DIR/system-spec/spec-state.json。以下のパス例はこの正本を指す (別ディレクトリに二重生成しない)。

1. bootstrap: apply-spec-transition.py bootstrap --out $CLAUDE_PROJECT_DIR/system-spec/spec-state.json で空foundation/decisions/targets/logsを持つstate envelopeを用意する (init は taxonomy から matrix を初期化する別subコマンドで、envelope 生成は bootstrap)。
2. R0-foundation: 技術ヒアリングの手前で上位概念 U1-U9 を深掘りし、U1/U2/U3 は値必須・U4-U9 は値または明示N/A理由で埋め、U1-U9 要約をユーザーへ提示して承認 approval_ref を得て確定する。
3. R1-init: taxonomy を Readしてmatrixをpopulateする。既存foundation/decisionsを保持する。
4. R2/R3/R5: 未収集セルをヒアリングし、不明・未決定ならR5で根拠付き候補と推奨を提示する。確定セル/decisionはgoalへトレースし、5 loop超でresume保存。
5. R4-reopen: 確定セルの見直しが要るときのみ reopen。
6. 検証: 各周回でvalidator、最終で--require-complete --require-foundation。

Gotchas

1. カテゴリを prompt へ直書きしない。必ず C04 taxonomy が正本。
2. 確定→未収集 の直接書換は禁止 (reopen を使う)。
3. 5 loop 到達で未収集が残るなら未完了として保存する。未収集を勝手に確定/対象外にしない。
4. category_aggregate は writer が真理値表から再計算する (手書きしない)。
5. platform id は canonical 6 種のみ (別名を作らない)。

Additional Resources

• references/spec-state-contract.md — spec-state.json 形状 + 真理値表 + writer 契約の正本。
• references/elicit-question-bank.md — カテゴリ×platform 質問テンプレ集。
• references/resource-map.yaml — Progressive Disclosure 索引。
• scripts/apply-spec-transition.py — 単一 transition writer (init/apply/chunk/aggregate)。
• ../../scripts/validate-coverage-matrix.py — 網羅性の決定論ゲート (IN1/OUT1)。
• references/required-info-catalog.json — C16 必須情報カタログ (domain 別 block/degrade/warn item・収集順序 depends_on・coverage certificate の正本)。
• ../../scripts/validate-knowledge-graph.py — 知識グラフ / required-info の決定論ゲート (--profile required-info が domain 被覆・item 形状・blocking_items を、--profile knowledge --order が topo_order を検証)。
• C04: ../ref-system-design-knowledge/references/system-category-taxonomy.json — カテゴリ初期集合の正本。