tech-doc-structuringlisted

# 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](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 コネクタ経