intent-db-design

name	intent-db-design
description	永続データモデルを設計する責務を負う packet に対し、意図（packet）・invariant（compass）・既存スキーマ/migration の三層を read-only で読み、テーブル定義/制約/インデックス/命名を射影元へトレースしながら（射影元に無いものは inferred / unverified 標識）`.intent/db-design/` 配下へ派生出力する射影スキル。出力は設計の叩き台であって要件ではなく、canonical な成果物を一切変更しない。

intent-db-design Skill

Core Mission

• Success Criteria:
  • 永続データモデルを設計する責務を負う対象 packet 1つを起点に、対象 packet の意図 / Scope・compass の Invariants/Anti-direction・既存スキーマ/migration（Grep）の三層を read-only で読み込んでいる（R1.1）
  • 入力範囲を対象 packet 1つ・compass の Invariants/Anti-direction・既存スキーマ/migration に限定し、Intent Tree 全文および対象外の packet を読み込んでいない（R1.3）
  • 三層入力からテーブル定義・制約・インデックス・命名を含む DB 設計（叩き台）を生成している（R1.2）。既存スキーマが Grep で同定できないとき（新規 DB 等）は既存スキーマ入力を空のまま意図と invariant のみから射影している（R1.4）
  • 生成 DB 設計の各記述に射影元（対象 packet / compass invariant / 既存スキーマ）への帰属を示すトレース注記を付与し、いずれにも帰属しない記述を inferred、既存スキーマを同定しきれず確認できない記述を unverified として標識し、確定（射影元由来）と混在させていない（R2.1 / R2.2）。すべての記述を 対象 packet / compass invariant / 既存スキーマ / inferred / unverified のいずれかに帰属させている（トレース率 100%・R2.3）
  • 出力を後続の intent-validate が実装スキーマ（migration/DDL）と項目単位で突合できる構造化された形式（## テーブル: 見出し＋カラム表）で出力し、テーブル定義・制約・インデックス・命名を突合可能な単位で識別できる形にしている（R4.1 / R4.2）
  • 出力を .intent/db-design/<packetスラッグ>/ 配下の派生物としてのみ書き込み、canonical な成果物（intent-tree・intent-compass・packets）・既存スキーマ・export 下書きを一切変更していない。出力を .intent/cc-sdd/・.intent/openspec/・.intent/speckit/（export 物）に書き込んでいない（R3.1 / R3.2 / R3.3）
  • 対象 packet が引数または利用者確認で一意に特定できるときその packet のみを対象とし、特定できないときは推測で対象を補わず対象指定を求めて停止している（R5.1 / R5.2）。既存スキーマの一部が同定できないときは同定できた範囲のみを入力に用い、同定できなかった旨を報告している（R5.3）
  • 自動起動・状態機械・他スキルを起動する仕掛けを持たず、発動を人間の手動操作に限り、永続ストアを導入せず実行時に外部サービスへ接続していない（R6.4 / R6.5）

Execution Steps

Step 1: 対象 packet 特定・三層入力（曖昧/不在なら停止する）

• 利用者が /intent-db-design <対象 packet> を実行したとき、まず対象 packet の特定と三層（意図 / invariant / 既存スキーマ）の read-only 読み取りを rules/db-design-input.md に従って行う。
• 対象特定（曖昧ゲート・R5.1 / R5.2）: 引数で対象 packet が一意に定まるならその packet のみを対象にする。引数で一意に定まらないときは .intent/packets/index.md から候補を提示し、利用者に自然言語で問うて確定する（回答を待つ）。引数でも対話でも一意化できないとき、または指定された packet が存在しないときは、推測で対象を補わず停止し、何が曖昧か（または不在か）を名指しして対象指定を求める。停止中は書き込みを行わない。
• 三層読取（入力範囲限定・R1.1 / R1.3）: 対象 packet 1つの意図 / Scope / Expected Behavior / Safety・.intent/intent-compass.md の Invariants/Anti-direction・既存スキーマ/migration（Grep 同定）に限定して読む。Intent Tree 全文・対象外 packet は読まない。
• 既存スキーマ同定（網羅でなく同定範囲＋報告・R1.4 / R5.3）: migration/DDL/ORM スキーマを Grep で素直に探し、同定できた範囲のみを既存スキーマ入力に採用する。一部が同定できないときは同定できなかった旨を報告し、捏造で埋めない。既存スキーマがまったく同定できないとき（新規 DB 等）は既存スキーマ入力を空のままにし、意図と invariant のみから射影する。
• 範囲と素材が確定したら Step 2 へ進む。

Step 2: DB 設計を射影（テーブル/制約/インデックス/命名）

• Step 1 が読み取った三層素材を、rules/db-design-projection.md の出力形式に従って DB 設計の叩き台へ写像する。
• 後続 validate が実装スキーマと項目単位で diff できる machine-diffable な Markdown 構造（frontmatter＋## テーブル: <name> 見出し＋| カラム | 型 | 制約 | 由来 | の4列固定表＋インデックス＋命名規則）で組み立てる。テーブル＝見出し、カラム＝表の行が突合単位である。
• 構造に埋め込むのは突合可能な識別子と帰属までであり、正規化妥当性・欠落インデックス・命名一貫性などの意味判断は構造に落とさない（INV2）。本形式は凍結された契約ではなく最小限の突合可能性を満たす暫定形式である。

Step 3: 射影元トレース・inferred / unverified 標識（捏造照合）

• rules/db-design-fabrication-guard.md に従い、射影した DB 設計が射影元を超えて捏造していないかを照合する。
• 各記述（テーブル定義・カラム・制約・インデックス・命名規則）を射影元（対象 packet / compass invariant / 既存スキーマ）へ辿れる形でトレースする（R2.1）。
• いずれの射影元にも根拠が見当たらないことを確認した記述は inferred、既存スキーマを同定しきれず確認できていない記述は unverified として区別して標識し、確定（射影元由来）と混在させない（R2.2）。実在するものを同定漏れで inferred と誤標識しないよう、どちらとも確信が持てないときは unverified に倒す。
• すべての記述を 対象 packet / compass invariant / 既存スキーマ / inferred / unverified のいずれかに帰属させ、帰属不明の記述を残さない（トレース率 100%・R2.3）。補完した（inferred / unverified）箇所の一覧を出力末尾に確認用として提示する（警告であり射影を止めない）。

Step 3.5: DB 固有検査オラクル（warn-only・read-only）

• rules/db-inspect-oracle.md に従い、射影した DB 設計（叩き台そのもの）に DB 固有の品質検査を適用する。実装スキーマとの突合（落差検出）ではなく、叩き台そのものの品質検査である。
• 5検査軸: 正規化崩れ / 欠落インデックス（外部キー・頻出検索列）/ N+1 誘発スキーマ / 制約漏れ（NOT NULL・UNIQUE・FK・CHECK）/ 命名一貫性。各軸を機械軸（命名一貫性等・断定可）と意味軸（正規化妥当性等・検討喚起）に仕分け、意味判断を脆い grep に落とさない（INV2 / INV35(4)）。
• invariant 適合照合: compass の Invariants（および対象 packet の Safety）に DB 関連の意図（immutable・追記専用・論理削除等）があれば、射影出力スキーマがそれに適合しているか照合し、衝突を「invariant 違反候補」として標識する（INV35(3)）。該当 invariant が無ければスキップする。
• 不可逆性警告: 既存スキーマ（Step 1 の Grep 入力）と射影出力の差分のうち、データ投入後に migration コストが跳ねる変更（型変更・NOT NULL 追加・カラム削除・キー変更）を warn として標識する。既存スキーマが無い（新規 DB）ときは「比較対象なし」でスキップし、品質検査は実施する。
• 検査所見は深刻度付き（intent-validate の報告と同型）に、検査軸・深刻度・根拠（テーブル/カラム名）を添えて出す。データ整合性直結軸（FK/UNIQUE/NOT NULL 漏れ）は感度高め、主観的軸（正規化の是非）は検討喚起に留める。
• すべての検査は warn-only（gate ではない・誤検知前提・停止しない）・read-only（所見の提示に留め勝手に修正しない＝修正は提案）。情報不足で判定不能な軸は「判定保留＋理由」とし、合格と誤標識しない（Fail-Safe・捏造しない）。

Step 4: 派生 Write（.intent/db-design/<slug>/ へ）

• すべての読み取り・射影・照合・検査が終わってから、最後に 生成した DB 設計を .intent/db-design/<packetスラッグ>/db-design.md へ書き込み、Step 3.5 の検査所見を射影出力に併走させる（深刻度付き・別ファイル機構を増やさない）。スラッグは rules/db-design-projection.md のスラッグ規則（packet-format.md および export 系と同一）で対象 packet 名から決定的に導出する。
• 衝突規則（R3.4）: スラッグが既存ディレクトリと一致し、かつその db-design.md の source_packet が異なる packet を指す場合のみ衝突とし、-2 から始まる連番で別名を割り当て、対応を利用者に告知する（黙って上書きしない）。同一 packet 名を指す場合は再生成として同ディレクトリを更新する。
• 出力の冒頭に、本 DB 設計が派生（derived）・再生成可能・Git 非追跡であり、設計の叩き台であって要件ではないこと、および inferred / unverified として標識した記述は利用者の確認まで暫定であることを明示する。
• canonical な .intent/*.md（intent-tree / compass / packets）・既存スキーマ・export 下書き（.intent/cc-sdd/ / .intent/openspec/ / .intent/speckit/）・アプリケーションコードには一切書き込まない。書込み先は .intent/db-design/<packetスラッグ>/ 配下に限定する（R3.1 / R3.2 / R3.3）。

Output Description

出力先はターミナルである。 出力には raw HTML（<details> / <summary> 等の折りたたみ UI）を使わず、詳細は素の Markdown 見出しで区切る（ターミナルでは生タグがそのまま表示され読めなくなるため）。

• .intent/db-design/<packetスラッグ>/db-design.md（派生・再生成可能・Git 非追跡。設計の叩き台であって要件ではない旨を冒頭に明示）。構造は rules/db-design-projection.md に従い:
  • frontmatter: source_packet（対象 packet 名・正本キー）/ generated_at（ISO 8601）/ projection_sources（射影に用いた層）。
  • テーブルごとの ## テーブル: <name> 見出し: 由来・カラム表（| カラム | 型 | 制約 | 由来 |）・インデックス（列・種別・由来）・命名規則（規約・由来）。テーブル＝見出し、カラム＝行が突合単位。
  • inferred / unverified 一覧: 出力末尾に「確認対象」として、どの記述が・どの理由で射影元に帰属しないか（inferred＝根拠なしを確認 / unverified＝未同定ゆえ未確認・実在しうる）を区別して並べる。
  • トレース注記: 各カラムの「由来」列・各テーブル/インデックス/命名規則の由来注記が射影元帰属を持つ。
  • 検査所見（併走・深刻度付き）: rules/db-inspect-oracle.md に従う DB 固有検査（5検査軸・invariant 適合照合・不可逆性警告）の所見を、射影出力に併走する形で深刻度付き（intent-validate と同型）に出す。各所見は検査軸・深刻度・根拠（テーブル/カラム名）を持つ。すべて warn-only（停止しない）・判定不能は「判定保留＋理由」。
• 素材が無い層は省略し理由（未記入／未観測／未同定）を明示する（推測で埋めない）。
• 既存スキーマの一部が同定できなかったときは、同定できなかった旨を報告に含める（R5.3）。

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

利用者へ向けた報告（進捗・完了・確認事項の提示。ターン末尾の要約を含む）を出す直前に、次を点検する（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/db-design/<packetスラッグ>/ 配下限定である。canonical な .intent/*.md（intent-tree / compass / packets）・既存スキーマ・export 下書きは read-only であり、そこへは作成・変更・削除を一切行わない（frontmatter の Write は .intent/db-design/ 配下への書き込みのためにのみ許可される。R3.1 / R3.2）。
• export 物に混ぜない: 出力を .intent/cc-sdd/、.intent/openspec/、.intent/speckit/（export 物）に書き込まない。本スキルの出力は設計の叩き台であって要件ではないため、選んだ出口の export 物に混ぜない（R3.3）。
• 派生・正本ではない: 生成物は派生（derived）・再生成可能であり正本ではない。この旨を出力の冒頭に明示し、canonical との二重正本を作らない。
• 捏造抑制（load-bearing 課題）: トレースの付かない記述を確定として残さない（各記述は射影元へ辿れるか、さもなくば inferred / unverified 標識される）。inferred（根拠なしを確認）と unverified（未同定ゆえ未確認・実在しうる）を区別し、確定と混在させない。補完箇所は必ず確認用一覧として提示し、黙って本文へ溶かし込まない（R2.x）。
• 読み取りのみ: 射影元（対象 packet / compass / 既存スキーマ・migration）は read-only で扱い、作成・変更・削除しない（R3.2）。
• 検査は warn-only・read-only（rules/db-inspect-oracle.md）: DB 固有検査（5検査軸・invariant 適合照合・不可逆性警告）はすべて warn-only であり gate ではない（誤検知前提・停止しない）。検査は所見の提示に留め、勝手にスキーマを修正しない（修正は提案・intent-validate と同型）。検査も静的で永続ストア・外部 DB 接続を持たない（INV2）。enforcement の gate と混同しない。
• 永続ストア・外部接続なし: 永続ストア（データベース等）を導入せず、実行時に外部サービスへ接続しない。状態は frontmatter のスキーマ規律で持つ（INV2 / R6.5）。
• 手動発動・自動起動しない: 発動は人間の手動操作に限る。本スキルは (1) 能動的に自身を起動するループを持たず、(2) 他スキルを起動する仕掛けを持たず、(3) 状態機械を持たない（R6.4）。/intent-db-design は利用者が会話で起動する手動経路であり、intent-planner が自動で db-design を発火することはない。別 spec の status/packets が出す「おすすめ」はコマンド文字列を提示するテキストであって Skill を invoke しないことで自動起動しないことが担保される。
• 外部依存ゼロ（INV2）。外部パッケージ・AST パーサ・独自スキーマを導入せず、Node 標準と自然言語ヒューリスティクスに限定し、射影を自然言語のワークフロー内で完結させる。Grep と読み取りは LLM が成果物・スキーマを読んで解釈するものであり、判定ロジックを再実装しない（A1）。
• アプリケーションコードを変更しない（INV6）。
• 前提不在時: 対象 packet が曖昧、または不在のとき、何も書き込まず不在/曖昧を名指しして対象指定を求めて止まる（fail-fast。R5.2）。
• 部分欠落時: 既存スキーマの一部が同定できない層は「未同定」と明示し報告する。素材が読み取れない層は「未記入／未観測」と明示し省略する（推測で埋めない。R5.3）。