intent-to-spec

name	intent-to-spec
description	指定範囲の Intent・steering・packets を read-only で読み、指定フォーマットの読める自然言語 Spec を `.intent/nl-spec/` へ写像する外向き生成スキル。
allowed-tools	Read, Glob, Grep, Write, AskUserQuestion
argument-hint	<source 範囲・format>（範囲ヒントと体裁。format 無指定なら既定を用い、どの format で生成したかを出力に明示する）

intent-to-spec Skill

Core Mission

• Success Criteria:
  • 利用者が指定した範囲（source scope: Intent サブツリー / packet 群 / steering 制約 / 横断 requirements）の .intent/ 成果物のみを素材として read-only で読み、三層（Intent の why/不変則/判断基準 / steering 級の制約 / requirements の個別要求）を横断的に束ねている（R1.1 / R1.2）
  • source scope が曖昧、または該当する成果物が不在のとき、自然言語 Spec を生成せず、何が曖昧か（利用可能な範囲）または不足している成果物（用意する該当スキル）を利用者に示して止まっている（R1.3）
  • 射影元（intent-tree / compass / packets / steering）を read-only で扱い、作成・変更・削除していない（R1.4）
  • 指定された target format（why 前面の上流向け / requirements 横断の統合仕様書 / その中間）に従って自然言語 Spec を構成し、format が無指定なら既定を用い、どの format で生成したかを出力に明示している（R2.1 / R2.4）
  • 各記述のトレース付与・inferred 標識・不変則保持・補完箇所の一覧提示を満たしている（Step 4 で実施。R3.1 / R3.2 / R3.3 / R3.4）
  • 生成物を派生（derived・再生成可能）として .intent/nl-spec/ 配下へ全置換で出力し、canonical な成果物（intent-tree / compass / packets）を作成・変更・削除していない。派生・正本・Git 管理・内部パスを説明する運用上の定型文を生成文書へ出力していない（R4.1 / R4.2 / R4.3）
  • 意図計画フェーズにおいてアプリケーションコードを変更していない（R4.4）。命名規約 intent-* に従い、外部 spec ツール・kiro-* 開発環境を変更せず、map-cc-sdd.md を呼ばず /intent-export-cc-sdd の振る舞いを変更していない（R5.5）

Execution Steps

Step 1: source 解釈（範囲・詳細度を確定する。曖昧/不在なら生成しない）

• 重要判断の開始時確認: 自然言語 Spec の生成開始時に確認する。対象範囲の Intent Tree、Intent Compass、packet とそこから参照される Open Questions を読み、CONTRACT.md の共通契約に従って人の決定が必要な重要判断かを分類する。重要判断には、少なくとも1つの暫定回答案、理由、推奨を変える条件を示す。利用者から決定、今回の範囲外、範囲限定の明示続行のいずれかを得るまで、影響範囲だけは自然言語 Spec の生成を開始しない。停止範囲に含まれない作業は継続でき、重要判断ではない通常の Open Question は従来どおり継続できる。許された結果を得た後は、影響する成果物を更新または再確認してから、その範囲だけを再開する。
• 利用者が /intent-to-spec を実行したとき、まず引数の範囲ヒント・format 指定・詳細度指定を rules/source-scope.md に従って解釈する。範囲が引数だけで一意に定まらない軸は、AskUserQuestion で利用者に問い、回答を待ってから確定する（推測で埋めない）。
• 詳細度（output depth）の確認（rules/source-scope.md の「詳細度の軸」に従う）: どこまで詳しく書くか（概要 / 標準 / 詳細）を、範囲軸と同じ対話補完に相乗りして確定する。引数で詳細度が明示されているとき（例:「詳細」「概要で」等）は問わない（不要な問いを足さない）。明示されていないときは、生成前に1問 AskUserQuestion で確認する（3段を対等に提示し「妥当な既定値」を先に置かない＝anchoring 回避）。これは体裁（format）無指定時に黙って既定を使う扱いとは意図的に非対称である（厚みの不足は読み手から見えないため生成前に確認する・詳細は source-scope の当該節）。
• 出力形（output form）の確認（DR189・複数選択可）: どの形で出すか（Markdown / 自己完結 HTML / Marp スライド用 Markdown）を、詳細度確認と同じ位置に相乗りして確定する。引数で形が明示されているとき（例:「HTML で」「Marp も」等）は問わない（不要な問いを足さない）。明示されていないときは、生成前に1問 AskUserQuestion で確認する（複数選択可・3形を対等に提示）。無指定・無回答・対話不能のときは既定の Markdown のみ（従来互換・既定形は暫定）。選ばれた形だけを Step 5 で書く。
• 画面素材の扱いの確認（DR190・画面ラフ記録が無い案件のみ発火）: 生成体裁が画面・接点を扱い（統合設計書等）、かつ intent-tree の ## 画面ラフ参照 が**「無い」（対象外でない・パス/リンクも無い）案件のときだけ、生成前に1問 AskUserQuestion で「推測（inferred）標識付きの画面遷移図を導出する / 『画面素材なし』と明示するだけ」を利用者に選ばせる。画面ラフが「パス/リンク」で在る案件・「対象外」の案件では発火しない（在れば射影・対象外なら画面節を立てない）。引数で扱いが明示されていれば問わない。規約の本体は rules/format-integrated.md の「画面・接点節の素材」に従う（推測図は inferred 標識必須・捏造しない）。 source scope が曖昧（引数でも対話でも軸が一意に定まらない）、または該当成果物が不在（指定された intent-tree / compass / packet / steering が存在しない・未記入）のときは、自然言語 Spec を生成せず**、.intent/nl-spec/ 配下に一切書き込まない。何が曖昧か（利用可能な範囲: 実在するサブツリー・packet 一覧・steering の有無）、または不足している成果物（用意する該当スキル: discover / compass / packets 等）を名指しして提示し、止まる。
• 範囲・詳細度が確定したら Step 2 へ進む。

Step 2: 三層読取（read-only で三層を読む・詳細度で読み分ける）

• rules/source-scope.md の「三層の読み取り（正確な参照・固定・詳細度で読み分ける）」表に従い、確定した範囲について三層を横断的に read-only で読み取る。読む深さは確定した詳細度に従う（概要=packet は frontmatter＋Evidence まで／標準=＋Expected Behavior の要点／詳細=packet 本文の全セクションまで。表の「詳細度で読む深さ」列が正）。概要・標準では packet 本文の全読みをしない（詳細度に必要な節だけを読む＝全ロードしない・DR6）。
• Intent の why/不変則/判断基準（.intent/intent-tree.md の L0–L4 / .intent/intent-compass.md の North Star・Invariants・Anti-direction・Decision Rules）、steering 級の制約（指定時のみ tech.md 等）、requirements の個別要求（.intent/packets/index.md ＋ .intent/packets/active/*.md）を、ひとつの文書の素材として束ねる。
• canonical 由来の素材と inferred 由来の素材（intent-tree の Assumptions / Open Questions）は、読み取りの段階で区別したまま保持し、混在させない。範囲外の成果物は読まない。射影元は read-only で扱い変更しない（R1.4）。

Step 3: target format 写像（既定なら format を明示する・詳細度で厚みを変える）

• 確定した target format に従って、Step 2 が束ねた三層の素材を、どの層・どの見出し・どの packet 由来かの由来を保ったまま、ひとつの自然言語 Spec へ写像する。
• **上流向け（why 前面）**のときは rules/format-upstream.md、**統合仕様書（requirements 横断）**のときは rules/format-integrated.md、**ステークホルダー一枚もの（結論先行）**のときは rules/format-stakeholder-onepager.md、**定例報告（結論先行）**のときは rules/format-status-report.md、**意思決定メモ（選択肢×基準の比較・採否先行）**のときは rules/format-decision-memo.md に委譲する。中間 format は上流／統合の度合い調整として表現し、別ルールを増やさない（読み手別プリセットは別ルールとして持つ）。
• 詳細度で厚みを変える（DR111）: 上流向け・統合仕様書・非プログラム向けの3体裁は、確定した詳細度（概要 / 標準 / 詳細）に応じて各セクションの厚みを変える（各 format ルールの「詳細度ごとの厚み」節に従う）。詳細度は体裁と直交する軸で、新しい format を増やさない。厚くするのは素材を書き下す密度であって、素材に無い記述を補って厚く見せない（INV73＝Step 4 の捏造照合はどの詳細度でも不変）。
• 厚み固定の読み手プリセット（適用外体裁の告知）: ステークホルダー一枚もの・定例報告・意思決定メモは、特定の読み手向けに情報量を絞る型そのものが体裁の核であり、詳細度による厚みの変更は適用しない（厚み固定）。これらに詳細度が指定されたときは、黙って無視も黙って適用もせず、「この体裁は厚み固定のため詳細度は適用しない」と一言告げてから、当該体裁の構成どおり生成する。
• format 無指定のとき（R2.4）: 既定の format を用い、どの format で生成したか（既定として上流向け / 統合仕様書のいずれを用いたか）を出力に明示する。黙って既定を選ばない。
• 読み手別の語彙開き: 読み手が非当事者（顧客・経営・営業・非開発の当事者＝コードや .intent/ を読まない読み手。一枚もの format の既定・または利用者が「顧客向け」等と指定したとき）と判別されるときは、rules/reader-vocabulary.md に従い、記号（INV/DR）を台帳 scripts/symbol-labels.json で言い換え・台帳に無い識別子（packet id・スキル名等）を本文から省く。当事者向けのときは従来どおり記号を辿るための参照として残す（読み手の判別は既存の source scope 解釈に相乗りし、新しい状態機構を足さない）。
• 写像は本スキルの format 系ルールに委譲する。map-cc-sdd.md は呼ばない（cc-sdd 写像は export-cc-sdd の所有であり、本スキルは touch しない）。

Step 4: 捏造照合（トレース付与・inferred 標識・不変則保持）

• rules/fabrication-guard.md に従い、format 写像が組み上げた自然言語 Spec が射影元を超えて捏造していないかを照合する。
• 各記述を射影元（どの Intent の L層 / どの compass 節 / どの packet / どの制約）へ辿れる形でトレースする（R3.1）。射影元に根拠のない記述は inferred として標識し、確定と混在させない（R3.2）。射影元の不変則・制約を省略・改変せず保持する（R3.4）。補完した（inferred）箇所の一覧を、利用者が確認できる形で提示する（R3.3。警告であり生成を止めるものではない）。

Step 5: 派生 Write（.intent/nl-spec/ へ全置換・選ばれた出力形だけ）

• すべての読み取り・写像・照合が終わってから、最後に 生成した自然言語 Spec を、Step 1 で確定した出力形（DR189）に応じて .intent/nl-spec/ 配下へ全置換で書き込む（同 scope+format+形 の再実行は全置換で冪等・R4.2）。選ばれた形だけを書く（選ばれなかった形の既存ファイルは削除しない）:
  • Markdown（既定）→ .intent/nl-spec/<format>.md（従来）
  • 自己完結 HTML → .intent/nl-spec/<format>.html。CSS を埋め込んだ1ファイルとし、外部リソース（CDN・外部フォント・外部画像・外部スクリプト）を一切参照しない（INV2 の外部依存ゼロを出力物にも適用）。配色テーマは読みやすさ優先の固定1種を同梱する（暫定・差し替え機構は持たない・DR189）。
  • Marp スライド用 Markdown → .intent/nl-spec/<format>.marp.md。Marp の frontmatter/ディレクティブを付与し、体裁の節見出し単位でスライドに分割する。分割は配置の変換であって内容の増減ではない（削る・足すをしない・Anti-539）。
• 複数形は同一素材の兄弟射影で内容等価（INV100・Anti-539）: 複数の形を同時に書くとき、確定内容（見出し・要求・受入条件・inferred 標識の集合）を形の間で等価に保つ。特定の形にだけ内容を足したり落としたりしない。図（意図の階層マップ図等）は Markdown/Marp ではコードブロックのまま（読み手環境が描画）、HTML では外部 JS を入れずに読める形で保持する。
• 描画・変換ツールを実行時に呼ばない（生成はファイル Write のみ・INV2）。描画は読み手のブラウザ（HTML）・利用者の Marp 環境（Marp）に委ねる。
• 本 Spec は内部管理上、派生（derived）・再生成可能・正本ではない・Git 非追跡として扱う。ただし、内部運用の注記は既定では出力しない。「これは正本ではありません」、正本の所在、.intent/ の内部パス、Git 管理、派生物であることを説明する定型文は、冒頭・末尾を含めどの出力形にも置かない。利用者が内部運用情報を明示的に求めた場合だけ、顧客向けではない内部版へ含めてよい。実際に inferred の記述がある場合は、内部注記の有無と切り離し、Step 4 に従ってその記述の個別標識と確認用一覧を残す（R4.3）。
• canonical な .intent/*.md（intent-tree / compass / packets）・steering（tech.md）・アプリケーションコードには一切書き込まない（R4.1 / R4.4）。書込み先は .intent/nl-spec/ 配下に限定する。

Output Description

出力先はターミナルである。 出力には raw HTML（<details> / <summary> 等の折りたたみ UI）を使わず、詳細は素の Markdown 見出しで区切って退避する（ターミナルでは生タグがそのまま表示され読めなくなるため）。[[...]]（memory / delta 用の wikilink 等）の内部記法は、delta / memory ファイルへの記録では正当だが、人向けのターミナル出力ではそのまま出さず普通の語に開く（リンク先の名前を自然文で綴る）。

• .intent/nl-spec/<format>.md（派生・再生成可能・Git 非追跡という保存属性は内部でのみ扱い、生成文書には記載しない）。出力形（DR189）が指定されていれば選ばれた形だけを併産する: Markdown=<format>.md（既定）／自己完結 HTML=<format>.html（CSS 埋め込み1ファイル・外部リソース不参照）／Marp スライド用=<format>.marp.md（節見出しでスライド分割・内容等価）。無指定なら Markdown のみ。内容は確定した target format に従い:
  • 上流向け: 目的（why）→ 守るべき不変則・制約 → 判断基準 → 個別の要求 → 前提・未確定（inferred 別枠、あれば）の順（rules/format-upstream.md の構成に従う）。
  • 統合仕様書: 概要 → 前提となる不変則・制約 → 統合要求と受入条件 → 前提・未確定（inferred 別枠、あれば）の順（rules/format-integrated.md の構成に従う）。
  • ステークホルダー一枚もの: 結論（何を作るか）→ なぜ作るか → やらないこと → 今どこまで来たか → 前提・未確定（あれば）の順。結論先行（BLUF）で、内部識別子（INV/DR/pkt-）を裸で読み手へ向けない（rules/format-stakeholder-onepager.md の構成に従う）。
  • 定例報告: 進んだこと → 決まったこと → 判断待ち の3節。各節とも結論先行（rules/format-status-report.md の構成に従う）。
  • 意思決定メモ: 結論（採否・未決の明示）→ 選択肢×判断基準の比較 → 不採用の理由 → 見直し条件 → まだ決めていないこと → 前提・未確定（あれば）の順。採否先行で、素材に無い評価・採否を補完しない（記録が無い欄は「記録なし」と明示。素材となる迷い・判断の記述が範囲に無ければ生成しない。rules/format-decision-memo.md の構成に従う）。
  • format 既定明示: 無指定なら既定 format を明示する（Step 3。R2.4）。
  • 詳細度の明示: どの詳細度（概要 / 標準 / 詳細）で生成したかを出力の冒頭に明示する。厚み固定の読み手プリセット（一枚もの・定例報告・意思決定メモ）に詳細度指定があったときは「厚み固定のため適用しない」旨も添える。
  • トレース・inferred 標識: 各記述に射影元への参照を付与し、射影元に根拠のない記述は inferred として確定と別枠・別標識で置く。
  • 補完箇所の確認用一覧: inferred として標識した記述を、どの記述が・どの理由で補完されたか名指しした一覧として併記する。
• 素材が無い層・セクションは省略し理由（未記入／未観測）を明示する（推測で埋めない）。

報告の平易さ点検（利用者向け報告・出力直前・共通）

利用者へ向けた報告（進捗・完了・確認事項の提示。ターン末尾の要約を含む）を出す直前に、次を点検する（INV105・DR208）。対象は利用者向けの報告文だけで、内部の記録（.intent/ 配下の canonical・ログ）の書き方には適用しない。

• 内部文書の文をそのまま転写しない: 直前に読んだ・書いた内部成果物（tree・compass・packet・Open Questions）の文面は内部の語彙で書かれている。報告では、その内容を初見の読み手に通じる言葉で言い直す（事実・意味は変えない）。
• 識別子を本文の主語にしない: 確認事項・作業単位を示すときは、まず「何を・なぜ」が単体で通じる一文を置き、識別子（Open Question 番号・packet 名・記号・工程名）はその後ろに参照として添える（例: 「…を確かめてから始めてください（整理番号: OQ-xxx-1）」）。平易化のために識別子・記録への参照を削らない（記録へ辿れなくなる）。
• 通じるかの合図: 1文に未説明の内部語が3つ以上並んだら詰め込みすぎの合図（機械カウントではなく意味の読みで）。単体で通じなければ、平易に書き直してから出す（事実・意味は変えない）。
• 比喩・曖昧な言い方だけで意味を渡さない: 報告の土台は正確さ（意味が一意に読める記述。平易さはそれを保ったまま易しく書く手段）。基準のない程度語（「かなり」「うまく」等）だけで結果を伝えず、観測できる事実で書く。比喩を使うなら直後に正確な言い直しを必ず併記する（確立された専門用語・世間の意味のままの一般語は無理に開かない）。
• この点検は事後の記録と対で働く（予防だけで閉じない）: 報告が通じなかった実例は、drift-watch が on のとき drift-log へ症例として残し、次の予防に使う。

Safety & Fallback

• 書込み境界: 書込み先は .intent/nl-spec/ 配下限定である。canonical な .intent/*.md（intent-tree / compass / packets / mode 等）・steering（tech.md）・アプリケーションコードは read-only であり、そこへは作成・変更・削除を一切行わない（frontmatter の Write は .intent/nl-spec/ 配下への書き込みのためにのみ許可される。R4.1）。
• 派生・正本ではない: 生成物は内部管理上、派生（derived）・再生成可能であり正本ではない。保存・更新の規律として守り、生成文書にはこの運用注記を出さない。canonical との二重正本を作らない（R4.3）。
• 捏造抑制（外向きの load-bearing 課題）: トレースの付かない記述を確定として残さない（各記述は射影元へ辿れるか、さもなくば inferred 標識される、のいずれか）。inferred を確定と混在させず、射影元の不変則・制約を省略・改変しない。補完箇所は必ず確認用一覧として提示し、黙って本文へ溶かし込まない（R3.x）。
• 写像の所有境界: format 写像は本スキルの rules/format-upstream.md / rules/format-integrated.md に委譲し、map-cc-sdd.md を呼ばない。/intent-export-cc-sdd（source/format 固定の特殊ケース）の振る舞いを変更しない（R5.3 / R5.5）。
• 読み取りのみ: 射影元（intent-tree / compass / packets / steering）は read-only で扱い、作成・変更・削除しない（R1.4）。
• 外部依存ゼロ（INV2 / R5.1）。外部パッケージ・AST パーサ・独自スキーマを導入せず、Node 標準と自然言語ヒューリスティクスに限定し、射影を自然言語のワークフロー内で完結させる。
• アプリケーションコードを変更しない（INV6 / R4.4）。
• 命名・外部非変更: 命名規約 intent-* に従い、外部 spec ツール・kiro-* 開発環境を変更しない（R5.5）。
• 前提不在時: source scope が曖昧、または該当成果物が不在のとき、何も書き込まず不在/曖昧を明示し、利用可能な範囲または不足成果物（用意する該当スキル）を案内して止まる（fail-fast。R1.3）。
• 部分欠落時: 素材が読み取れない層・セクションは「未記入／未観測」と明示し省略する（推測で埋めない）。