ce-explain

方法と理由を説明する

対象範囲を定めた質問に答え、想定される用途に必要な理解を読み手に提供する説明を作成します。対象と目的は、依頼者が人であるか別のワークフローであるかを問わず、依頼と利用可能なコンテキストから判断します。プロジェクトの動作はソースの証拠に基づいて説明し、文書化された根拠、推論、不明点を区別します。

完了条件： 裏付けとなる証拠と、重要な未回答の質問を添えて説明を提示するか、具体的な阻害要因を返します。成果物が求められた場合は、その成果物と保存先を提示します。公開は別のアクションであり、対象について説明を終えるための条件ではありません。

読み手とやり取り

想定される読み手と用途に合わせて、深さと提示方法を調整します。人には実用的な回答が必要な場合があり、呼び出し元のエージェントには、ほかの人に説明するための資料が必要な場合があります。呼び出し元の身元だけから出力を推測しないでください。進行中のワークフローに加わる場合は、求められた結果を提示し、続行は呼び出し元のワークフローの担当者に委ねます。その回答に、送付先の選択肢や追加の提案を加えないでください。

確認可能な事実を調べてから質問します。情報の不足が回答に重大な影響を及ぼし、依頼や証拠から解決できない場合に限り、質問してください。やり取りができない場合は、未解決の質問とその影響を返し、回答を待ったり、答えを作り上げたりしないでください。検証済みの動作を説明しつつ、その歴史的な根拠は不明だと報告してもかまいません。

根拠の確認、最初のブロッキング質問、またはサブエージェントの呼び出しを行う前に、references/orchestration.md を読んでください。 証拠の収集、ツールの使用、モデルのティア、およびその代替手段が定義されています。

成果物のルート

解説をリポジトリにアーカイブする場合に限り、解説は <root>/explainers/ に配置します。学びは <root>/solutions/ から参照できます。パスを作成するときに限り <root> を解決します。スクラッチのみの実行や外部概念に関する実行では、パスを作成しません。設定値ではなく、解決済みのパスをサブエージェントに渡してください。

成果物のパスを作成する前に、CE 成果物ルート <root> を解決してください。

• 読み取り： <repo-root>/.compound-engineering/config.yaml からのみ docs_root を読み取ります（<repo-root> は git rev-parse --show-toplevel で取得します）。config.local.yaml からは読み取らないでください。未設定の場合、従来どおり <root> は docs です。
• 検証： 値が設定されている場合、リポジトリ相対のディレクトリであり、シンボリックリンクを解決した実際のパスがリポジトリ内に収まり、リポジトリのルートでも .git/ の配下でもないことを確認します。条件を満たさない場合は、docs_root とその値を明記したエラーで停止し、docs にフォールバックしてはいけません。
• 使用： <root> を唯一の成果物の保存先として使用します。存在しない場合は作成し、各パスを <root>/<subdir> として作成します。<subdir> にはこのスキル固有のサブディレクトリを使い、docs も読み取らないでください。

実行フロー

フェーズ 1：質問と用途を確認する

今すぐ references/intake.md を読んでください。対象と期間の決め方、入力トークン、納品形式の選び方が定義されています。依頼された対象だけを説明してください。対象を特定できない呼び出しでは、対象や既定の成果物を作り上げず、上記のやり取りのルールに従って確認を求めてください。

フェーズ 2：根拠を集める

範囲を絞った根拠の確認では、references/orchestration.md に従ってください。既存の根拠が十分かつ最新であれば、それを使用してください。裏付けが不足している、見解が分かれている、または情報源の変更の影響を受けている主張を確認してください。

アーティファクトまたは根拠ドシエが必要な場合に限り、実行ディレクトリを作成してください。どちらかを書き込む前に、次のブロックを使用してください。このブロックは、シンボリックリンクや、別のユーザーが所有するスクラッチルートを拒否します。

SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)";
[ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") 2>/dev/null && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && [ -w "$SCRATCH_ROOT" ] || SCRATCH_ROOT="${TMPDIR:-/tmp}/compound-engineering-$(id -u)";
if [ -L "$SCRATCH_ROOT" ]; then echo "unsafe scratch root symlink: $SCRATCH_ROOT" >&2; exit 1; fi;
(umask 077; mkdir -p "$SCRATCH_ROOT") || exit 1;
if [ -L "$SCRATCH_ROOT" ] || [ ! -O "$SCRATCH_ROOT" ]; then echo "scratch root is not owned by the current user: $SCRATCH_ROOT" >&2; exit 1; fi;
chmod 700 "$SCRATCH_ROOT" || exit 1;
RUN_DIR="$SCRATCH_ROOT/ce-explain/$(date +%Y%m%d)-$(openssl rand -hex 3)";
(umask 077; mkdir -p "$RUN_DIR") || exit 1; chmod 700 "$RUN_DIR" || exit 1;
echo "$RUN_DIR";

動作のトレースが所有権の境界をまたぐ場合は、スカウトドシエを書き出します。スカウトをディスパッチする前に、この実行ディレクトリを作成してください。

• 差分モード。 空の範囲または件名の欠落がある場合は、別の内容を黙って説明しないでください。隣接する内容を説明する前に、その旨を報告してください。代替の使用がリクエストで許可されている場合、またはユーザーが同意した場合に限り、代替を使用してください。使用する場合は、結果と、存在する場合はアーティファクトの Subject に、代替であることを明記してください。それ以外の場合は、未解決の範囲を呼び出し元に返してください。
• 要約モード。 メインの会話では、対象期間を事前にスキャンしたり、件数を数えたり、特徴づけたりしないでください。代わりに、references/agents/work-recap-scout.md をシードとして渡し、解決済みの対象期間、リポジトリのルート、$RUN_DIR を指定して、抽出段階から汎用サブエージェントを直接ディスパッチしてください。対象期間が空の場合： アクティビティがないことを報告し、説明用アーティファクトを作成せずに終了してください。ハーネスがサブエージェントのプリミティブを公開していない場合： スカウトのプロンプトにある情報源と予算を使って、インラインでスカウトを実行してください。その場合も recap-evidence.md を書き込み、完了するまでは対象期間について見解を形成しないでください。ディスパッチに失敗した場合は、references/orchestration.md のフォールバックルールに従ってください。

フェーズ 3：説明をまとめる

根拠を使って質問に回答し、重要な制約と不確実性を保ってください。回答を提示する前に、すべての事実に関する主張を情報源と照合してください。関数呼び出しだけでは、未確認の実装について保証を示すことはできません。裏付けのない主張は削除するか、図や演習の回答も含め、該当箇所に不確実性を明記してください。理解を深めるために有効であれば、文章、コード、表、図を選んでください。特定の構成にする必要はありません。複数人の作業を説明する場合は、帰属を正確にしてください。依頼された範囲や深さに収まらないほど多くの根拠から選ぶ場合は、選択したことを明らかにしてください。一部の説明を、網羅的な説明であるかのように黙って提示してはいけません。

回答、または別のワークフローが取り込む資料については、その内容を直接返してください。各段落には、別途注記を参照しなくても正確に利用できるよう、必要な留保事項を含めてください。別のワークフローが回答を使用する場合、返す内容には根拠、引き続き適用される制約、未回答の質問を含めてください。意図された用途で必要な場合を除き、独立したアーティファクトを作成しないでください。

独立したアーティファクトを作成する場合は、選択した形式の互換性とメタデータの要件を、作成時に references/explainer-html.md または references/explainer-markdown.md で確認してください。教材用アーティファクトでは、references/check-in.md も確認してください。実行をチェックイン待ちで止めないでください。演習がある場合は、アーティファクト内の静的コンテンツとして扱います。$RUN_DIR/explainer.html または explainer.md を書き込み、インラインの要約とファイルパスを提示してください。

フェーズ 4：提示する

回答またはローカルアーティファクトを提示した時点で、説明は完了です。保存先の選択を求めたり、後続作業を作り出したりしないでください。保存先が指定されている場合は、実行前に references/destinations.md を読み、各保存先と公開に必要な同意について確認してください。呼び出し元のワークフローが周辺の文書を管理している場合は、自分で配置または公開せず、内容を呼び出し元に返してください。

ht-ml.app への公開は、ヘッドレスで行うことも、暗黙に推定することもできません。公開に関する警告の後で確認を得るのではなく、ht-ml.app の指定自体を保存先の選択として扱います。確認を得られない場合は公開せず、正規の HTML を保持し、ローカルの $RUN_DIR/explainer.html のパスを報告してください。

範囲

• アプローチを採用するか変更するかを判断するには、ce-pov を使用します。過去の選択について説明しても、現在それを支持することにはなりません。
• プロジェクトの長期的に役立つ学びを記録するには、ce-compound を使用します。説明を作成しても、リポジトリの記憶を維持する権限が与えられるわけではありません。
• 提供されたアイデアを説明します。代替案の作成と実装範囲の検討は、ce-ideate、ce-brainstorm、ce-plan の役割です。
• 報告された問題の診断や修正は ce-debug の役割です。現在の動作について事実に基づいて説明する場合は、ここで扱います。