docs-generator

テクニカルドキュメント

ACTION REQUIRED（読了後すぐに実行）

1. NOW：現在のタスクが本 skill の適用範囲に該当するか確認する
2. NOW：../tool-index.md を読み、ツールの可用性と実際のパスを検証する
3. NEXT：ツールが不足している場合は bootstrap を呼び出す。パスを推測しない
4. ACT：「ワークフロー」の最初のステップに進んで実行する。確認状態で止まらない

文章スタイル、トーン、ボイスのガイドラインについては、The Engineer ペルソナで Skill(ce:writer) を使用してください。

セキュリティ／リバースタスクのドキュメント出力

リバース／ペネトレーション／CTF／セキュリティ分析タスクが完了したら、本 skill はユーザーのプロジェクトディレクトリに正式な技術ドキュメントを生成する役割を担います。

トリガーのタイミング

1. リバースタスクが完了し、中核となる結論（アルゴリズムの復元、署名の破解、バイパス手法など）が得られている
2. ペネトレーションテストが完了し、脆弱性を発見・検証済みである
3. CTF 問題を解き、flag を取得済みである
4. ユーザーが明確に「レポート／ドキュメント／writeup を書いて」と要求した

テンプレートの選択

タスク種別	使用するテンプレート
APK／バイナリ／so リバース	references/security-report-templates.md → リバースエンジニアリングレポート
ペネトレーションテスト／脆弱性調査	references/security-report-templates.md → ペネトレーションテストレポート
CTF 解答	references/security-report-templates.md → CTF Writeup
JS／Web 署名リバース	references/security-report-templates.md → 署名リバースレポート
マルウェア／APT／ウイルス分析レポート	references/security-report-templates.md + references/vendor-report-rules.md
汎用技術ドキュメント	references/templates.md → README／API ドキュメント

ベンダーレポートの構造（Issue #65）

セキュリティ系の正式レポートは MUST references/vendor-report-rules.md を読むこと（構造のみを取り、ベンダーの原文を転用しない）。ベンダー flavor はタスクの証拠またはユーザーの明確な要求がある場合にのみ選択し、通常のリバースやその他のタスクでは flavor = null を使用します。

Flavor / Overlay	いつ使うか	主な参考骨子
malware	明確な悪意あるサンプル、トロイの木馬、白加黒、フィッシング投毒	火绒式：概要→フロー→サンプル分析→緊急対応→IOC
apt	APT／キャンペーン／グループ／多段階感染チェーン／業界標的型	カスペルスキー Securelist 式：要約→感染チェーン→調査ナラティブ→Interesting findings→技術分析→検知・緩和→IOC
flavor = null	通常の APK／ELF／PE／Mach-O リバース、アルゴリズム／ファームウェア分析、ペネトレーション／CTF／JS 署名	元タスクテンプレート + Base 汎用要素。malware／APT 専用セクションは適用しない
thin vuln	ユーザーが明確に脆弱性／パッチ／CVE の技術分析を要求	概要→影響／再現→クラッシュとパッチ分析→防御推奨（null に重ねるもので、第 3 のデフォルト全文 flavor ではない）

原則：テンプレートは数より精度 —— ベンダー全文 flavor はわずか 2 つ。vuln は任意の thin overlay にすぎず、第 3 のデフォルト全文テンプレートを別途作らない。 §0 Evidence→Finding→Path と同時に有効。衝突時は Evidence 契約が優先。

出力規範

• 出力場所：ユーザーの現在のプロジェクトディレクトリ（skill パッケージのディレクトリではない）
• ファイル名形式：YYYY-MM-DD_[種別]-[対象略称]-report.md
• プロジェクトに docs/ ディレクトリがある場合：docs/ 下を優先する
• エンコーディング：UTF-8
• 言語：ユーザーの会話言語に従う（中国語の会話なら中国語レポート、英語の会話なら英語レポート）

品質要件

• すべてのコードブロックは直接実行可能か、明確なコンテキストがあること
• placeholder／TODO を含めないこと
• 重要な発見には必ず証拠の裏付けがあること
• 再現手順は第三者が独立して再現できること
• 機密情報（実際の token、パスワード、内部 URL）はプレースホルダーで置き換えること
• MUST Evidence → Finding → Path チェーンを含めること（../ops/evidence-finding-path.md とテンプレート §0 を参照）
• MUST references/vendor-report-rules.md を読むこと：malware／apt または flavor = null を選択する（脆弱性タスクでは thin vuln を重ねてもよい）。flavor がない場合は元タスクテンプレートと該当する Base 要素のみを出力し、IOC／ATT&CK を強制しない
• SHOULD case の scope.md／timeline.md を参照すること（../scripts/case-init.ps1）

図表の統合

レポート生成時は、適切な箇所で diagram-generator skill を呼び出して可視化図表を生成すべきです。

レポート種別	推奨図表	図表タイプ
リバースエンジニアリングレポート	関数呼び出し関係図、データフロー図	Mermaid flowchart / sequenceDiagram
ペネトレーションテストレポート	攻撃経路図、ネットワークトポロジ図	Mermaid flowchart / Graphviz
CTF Writeup	解答アプローチのフローチャート	Mermaid flowchart
JS 署名リバースレポート	リクエストチェーンのシーケンス図、アルゴリズムフローチャート	Mermaid sequenceDiagram / flowchart

図表は Mermaid コードブロックとしてレポートの markdown に埋め込み、GitHub／GitLab で直接レンダリングできるようにします。

---

中核原則

1. 段階的開示

情報をレイヤーで明らかにします：

レイヤー	内容	ユーザーの疑問
1	一文での説明	それは何か？
2	クイックスタートのコードブロック	どう使うのか？
3	完全な API リファレンス	どんなオプションがあるのか？
4	アーキテクチャの深掘り	どう動作するのか？

警告、破壊的変更、前提条件は先頭に置きます。

2. タスク指向のライティング

## AuthService Class
The AuthService class provides authentication methods...


## Authenticating Users
To authenticate a user, call login() with credentials:

3. 語らず示す

あらゆる概念には具体的な例が必要です。

フォーマット標準

• 見出しはセンテンスケース：「Getting Started」ではなく「Getting started」
• 見出しレベルは最大 3 段階：それより深い場合はドキュメントを分割する
• コードブロックには必ず言語を指定する
• 内部リンクには相対パスを使用する
• 属性が 3 つ以上ある構造化データには表を使用する

品質チェックリスト

• コード例がテスト済みで実行可能
• プレースホルダーテキストや TODO がない
• 実際のコードの挙動と一致している
• すべて読まなくても拾い読みできる
• 読者が次に何をすべきか分かる

アンチパターン

問題	修正
テキストの壁	見出し、箇条書き、コード、表で分割する
重要な情報が埋もれている	警告／破壊的変更は先頭に置く
エラードキュメントの欠落	起こりうる問題を必ずドキュメント化する

テンプレート

README、API エンドポイント、ファイル構成のテンプレートについては、references/templates.md を参照してください。

関連スキル

• Skill(ce:writer) - 文章スタイル、トーン、ボイス（The Engineer ペルソナをロード）
• Skill(ce:visualizing-with-mermaid) - アーキテクチャ図とフロー図

---

オンデマンドブートストラップ（On-Demand Bootstrap）

本スキルは外部ツールに依存せず、純粋なテキスト生成です。bootstrap は不要です。

レンダリングした図をレポートに埋め込む必要がある場合は、diagram-generator/ スキルを呼び出します。

---

ルーティングコンテキスト

上流エントリ: すべてのセキュリティ/リバースエンジニアリングスキルは、タスク完了後に本スキルを自動的に呼び出します トリガー方法:

• 自動：タスク完了後に行動チェーンの第 9 ステップとして実行
• 手動：ユーザーが「レポートを書いて」「ドキュメントを出して」「writeup」と言ったとき

同階層の関連モジュール:

• apk-reverse/ — APK リバース完了後にリバースレポートを生成
• ida-reverse/ — バイナリ分析完了後にリバースレポートを生成
• radare2/ — CLI 分析完了後にリバースレポートを生成
• js-reverse/ — JS 署名リバース完了後に署名レポートを生成
• reverse-engineering/ — 汎用リバース完了後にリバースレポートを生成
• field-journal/ — レポート内容は同時に進化ログのデータソースとしても機能

セキュリティレポートテンプレート: references/security-report-templates.md ベンダーレポートルール: references/vendor-report-rules.md（flavor: malware | apt | null；optional overlay: vuln） 汎用ドキュメントテンプレート: references/templates.md

タスク完了セルフチェック（完了を主張する前に MUST で合格すること）

• ワークフローの各ステップを（読むだけでなく）実際に実行しましたか？
• tool-index に基づいて実際のツールパスを使用しましたか？
• 再現可能な証拠（コマンド/スクリプト/スクリーンショット/レポート）を出力しましたか？
• レポートに Evidence / Finding / Path（ops 契約）が含まれていますか？
• RULES が要求する Checklist 項目を完了し、書き戻しましたか？