Tech doc structuring

Tech Doc Structuring

ADR をはじめとする技術ドキュメントを、次の 3 原則に基づくハイブリッド構造で生成・整形する。文書を機械可読にしたいが全文の JSON / YAML 化は説明力を壊す — その中間解を標準形として自動化するスキル。

3 原則（このスキルの核）

1. メタデータは YAML frontmatter — status・date・tags・文書間リンクなど、横断検索・フィルタ・自動チェックに使う情報だけを機械可読にする
2. 章構成は文書タイプ別の固定見出し — 構造の強制は見出しテンプレートで行う。必須章の欠落が「見出しの欠落」として目視・grep で検出できる
3. 本文は自然言語の散文 — 決定の理由・因果・トレードオフ（検討したが却下した案と却下理由）は文章のまま書く。キーバリューや箇条書きへ機械的に圧縮しない

してはいけないこと: 文書全文の JSON / YAML / 表形式化、本文散文の箇条書きへの一括変換、「なぜ」の接続（〜のため・〜を優先して）を落とす要約。

引数の解析

$ARGUMENTS を以下のルールで解析する:

• --type <値> がある場合 → 文書タイプ（adr / design-doc / spec / runbook / postmortem）として保持する。ない場合は内容・ファイル名から自動判定する（判定表: references/doc-types.md）
• 残りのトークンのうち存在するファイル / ディレクトリのパス → 整形モードの対象（ディレクトリは直下の .md を対象）
• パス以外のテキスト → 新規作成モードの内容説明
• 引数なし → 直近の会話に文書化すべき決定・設計があればそれを対象に新規作成する。なければ AskUserQuestion で対象を確認する（使えないエージェントではテキストで確認する。以降の AskUserQuestion も同様）

手順

1. モード・タイプの確定とゲート表示

対象と文書タイプを確定し、作業前に以下のブロックを 1 回表示する:

モード: <新規作成 / 整形>
文書タイプ: <adr / design-doc / spec / runbook / postmortem / その他>
対象: <生成先パス or 整形対象パス>

• 整形モードで対象が複数ファイルの場合は一覧を提示し、処理対象をユーザーに確認してから進める
• 日付は TZ=Asia/Tokyo date +%Y-%m-%d で取得する（JST）

2A. 新規作成モード

1. 内容の収集: 会話・引数の説明・参照された Issue / diff から「決定（または文書の主題）・背景・検討した代替案・影響」を洗い出す（ADR ではさらに決定に至る経緯 — いつ・誰と誰が・どのようなやり取りを経たか — を含める）。不足があれば AskUserQuestion で確認する。確認手段がない環境では、不明項目を TODO: 未確定 として本文に明記した上で生成する（事実を創作して埋めない）
   • 経緯のやり取りが Slack / Gmail / Confluence 上にある場合（URL や言及があるとき）は、MCP コネクタ経由で本文を取得して要約する: references/deliberation-sources.md。コネクタが無い環境では素材の貼り付けを依頼する
2. 配置先の決定（ADR の場合）: docs/adr/・docs/adrs/・docs/decisions/・adr/ の順で既存ディレクトリを Glob で探す。見つかった場所の既存規約（ファイル名形式・見出し言語）が本スキルの標準と異なる場合は既存規約を優先する。どれも無ければ docs/adr/ の新設を AskUserQuestion で確認する
   • ADR 以外は既存の類似文書と同じディレクトリ（無ければ docs/ 配下）に置き、生成前にパスを提示する
3. 採番（ADR の場合）: 既存ファイルの最大番号 + 1（NNNN 4 桁ゼロ埋め、ファイル名 NNNN-<英語kebab-caseスラグ>.md）。書き込み直前に再度 Glob で番号の重複がないことを確認する
4. 生成: テンプレート（ADR: assets/adr-template.md / その他: assets/tech-doc-template.md）と文書タイプ別見出しセット（references/doc-types.md）に従って作成する
   • ADR の ## Deliberation（決定に至る経緯） は要点の時系列（- YYYY-MM-DD 参加者: 要点と帰結）に留め、やり取りの詳細ログを再録しない（ADR は横断検索・digest で高頻度に読まれるため、経緯の詳細で本体を肥大させない）
   • 経緯が長大（目安: 15 行超）な場合や詳細な記録を求められた場合は、同ディレクトリの NNNN-<スラグ>-deliberation.md へ切り出す（frontmatter は「5 タイプに該当しない文書」扱いで type なし・status / date / tags / related のみ。時系列の骨格は箇条書き、争点と収束の因果は散文で書く）。ADR 側の節は 3 行以内の要約に留め、双方の related で相互リンクする
5. リンクの整合（ADR の場合）: 旧 ADR を置き換える決定なら、新 ADR の supersedes に旧 ADR を記載し、旧 ADR 側も status: superseded と superseded_by を更新する（双方向を同時に維持する）

2B. 整形モード

既存文書を 3 原則の構造へ ロスレスで 正規化する。

1. 全文 Read: 対象を読まずに変更しない。frontmatter の有無・既存見出し・本文中に埋まったメタデータ（Status: Accepted 行・日付行など）を把握する
2. タイプ判定: --type 指定 > frontmatter の type > 内容からの判定（references/doc-types.md の判定表）
3. 変換（詳細規則: references/restructuring-rules.md）:
   • 本文中のメタデータ → frontmatter へ移動する（移動であって削除ではない。本文側の重複行のみ除去する）
   • 既存見出し → 標準見出しへマッピングする（例: 「なぜ」「Motivation」→ Context）。どの標準見出しにも対応しない節は ## 補足 の下へ原文のまま残す
   • 本文の散文はそのまま維持する。文体変換（散文⇔箇条書き）・要約・削除・追記をしない
4. 書き込み: 変更箇所を洗い出してから 1 ファイル 1 回の Edit / Write で完結させる
5. 差分要約: frontmatter へ移動した項目・見出しのマッピング結果・## 補足 へ退避した節を報告する

3. 完了報告

• 生成 / 変更したファイルのパスを表示する
• 新規作成では、埋められなかった項目（TODO のまま残した箇所）を明示する
• 生成物のコミットはしない（コミットするかどうかはユーザーの判断に委ねる）

frontmatter 標準キー（要約）

キー	対象	値
type	共通	adr / design-doc / spec / runbook / postmortem
status	共通	ADR: proposed / accepted / deprecated / superseded。その他: draft / active / deprecated
date	共通	作成日・決定日（JST・YYYY-MM-DD）
tags / related	共通	横断検索用タグ・関連文書への相対パス
supersedes / superseded_by	ADR	置き換え関係（相対パス。双方向に維持する）

完全な定義（任意キー・値域・記入規則）: references/frontmatter-keys.md

タイトルは frontmatter に持たず H1 を唯一の正とする（ADR は # ADR-NNNN: <タイトル>。整形時、番号はファイル名に既存の番号がある場合のみ H1 へ補完し、無ければ H1 は原文のままにする — 新規採番は整形の範囲外）。status は frontmatter を唯一の正とし、本文に Status 節を作らない（二重管理を避ける）。

エラーハンドリング

ケース	挙動
指定パスが存在しない	エラーを表示して終了
対象が特定できない（引数なし・会話にも決定の言及なし）	AskUserQuestion で対象を確認
ADR ディレクトリが無い	AskUserQuestion で docs/adr/ 新設を確認
既存 frontmatter のキーが標準キーと矛盾（state: と status: の併存など）	ユーザーに確認してからマージ
整形対象が既に標準構造	変更せず「整形不要」と報告

やらないこと

• 設計内容そのものの考案・レビュー（→ /software-architect、/code-reviewer）
• 文書全文の構造化言語（JSON / YAML / XML）への変換
• 整形時の内容の要約・削除・追記（構造の正規化のみ。内容の追加は新規作成モードでユーザーの入力に基づいて行う）
• ADR 番号の振り直し・ファイルのリネーム（既存の採番を変えない）
• 生成物の自動コミット