BuildStory

BuildStory は何をしますか？

BuildStory は、人々がプロジェクトの「何が」納品されたかだけでなく、「どのように」構築されたかを理解するのに役立ちます。少数の転換点を再構成し、繰り返されるやり直しと可能性の高い時間の浪費を表面化させ、トランスクリプトが許可されている場合は証拠に基づいた人間と AI の連携をレビューし、その証拠を教訓やキャリア資料に変換します。

譲れない原則

• Git とセッションログを証拠として扱い、心を読もうとはしない。推論と確信度を明記すること。
• プロジェクトのストーリーを前面に出す。生のコミット数、全履歴、数値計算は補足証拠として残す。
• プロジェクトのリズムを観察可能な活動として示し、勤勉さや生産性の尺度としない。「最も働いた日」ではなく「最も活動的だった日」を使用する。
• デフォルトで最大 7 つの転換点を選択する。完全な Git ログは証拠であって、物語ではない。
• プロジェクトを単一のスコアにまとめない。複数の側面にわたる不均一なプロファイルを示す。
• 反復を無駄と同一視しない。疑わしいパターンは、証拠またはユーザーが確認するまで「ループ候補」と呼ぶ。
• ファイルレベルの統計よりもテーマレベルの旅の洞察を優先する。パスとチャーン率は証拠であり、結論ではない。
• 繰り返し作業は、暫定的に blocked-loop、necessary-exploration、direction-change のいずれかに分類し、その後ユーザーに原因を確認する。
• ビジネスインパクト、所有権、チーム規模、パフォーマンス向上、履歴書の指標をでっち上げない。
• やり取りをレビューし、ユーザーのコミュニケーション能力を評価または診断しない。プロンプト品質の合計スコアを計算しない。
• プロンプトの繰り返しは、不明確な表現の証拠ではない。コミュニケーションに関する洞察を作成するには、同じセッション内の ユーザー → アシスタント → ユーザーによる修正 という連鎖が必要。
• AI の実行ミス、用語の意味の不一致、要件の進化、証拠不十分を明確に区別する。デフォルトでユーザーに責任を帰さない。
• 明確化の近くにある Git コミットは、その明確化がコミットを引き起こした証拠ではなく、近くにある証拠として扱う。
• デフォルトでは現在のプロジェクトのみを読み取る。許可されたワークスペース外のセッションファイルを読む前に確認を取る。
• ユーザーが明示的に外部サービスを要求しない限り、分析をローカルに留める。
• 完全なトランスクリプトをアップロードまたは複製しない。結論を説明するために必要な短い抜粋のみを保持する。
• プロジェクトのソースファイルを変更しない。結果は専用の出力ディレクトリに書き込む。

デフォルトのワークフロー

1. スコープの確立

リポジトリルートとユーザーの目標を特定する。デフォルトでは現在のブランチと HEAD から到達可能な全 Git 履歴を使用する。

セッショントランスクリプトは、すでに提供されている場合、またはユーザーがパスを許可した場合にのみ使用する。Git のみのレポートも有用だが、時間見積もりや意図レベルの結論は低い確信度としてマークする必要がある。

2. 決定論的証拠の収集

バンドルされたアナライザーを実行する:

python3 <skill-dir>/scripts/build_story.py <repo-path> \
  --output <repo-path>/build-story-report \
  --language <zh|en>

許可された場合、1つ以上のトランスクリプトソースを追加する:

python3 <skill-dir>/scripts/build_story.py <repo-path> \
  --session <authorized-session-file-or-directory> \
  --output <repo-path>/build-story-report \
  --language <zh|en>

ユーザーが確認したコンテキストが利用可能な場合、それをレポート出力ディレクトリに保存し、--context を付けて再実行する:

{
  "zh": {
    "role": "你在项目中的真实职责",
    "outcome": "最终带来的真实结果",
    "key_decision": "最能代表能力的关键决定",
    "summary": "一句话项目故事",
    "resume_bullets": ["经过确认的简历要点"],
    "insight_confirmations": {
      "path:src/sync.py": {
        "classification": "direction-change",
        "reason": "自动同步违背了面向小白的简单性。",
        "lesson": "当一个功能持续引入恢复机制时，先重新判断它是否值得存在。"
      }
    },
    "communication_confirmations": {
      "communication:example-id": {
        "attribution": "ai-ignored-explicit-requirement",
        "reason": "原始要求已经明确说明必须保留语言切换。",
        "analysis": "这次更像 AI 执行遗漏，而不是用户需要把话说得更长。",
        "lesson": "明确边界仍被遗漏时，先检查 AI 执行。"
      }
    },
    "translations": {
      "Initialize project": "初始化项目",
      "Add the requested feature": "加入用户要求的功能"
    }
  },
  "en": {
    "role": "your real responsibility",
    "outcome": "the verified result",
    "key_decision": "the decision that best demonstrates your ability",
    "summary": "the one-line project story",
    "resume_bullets": ["a confirmed resume bullet"]
  }
}

python3 <skill-dir>/scripts/build_story.py <repo-path> \
  --context <repo-path>/build-story-report/context.json \
  --output <repo-path>/build-story-report \
  --language <zh|en>

スクリプトはデフォルトのレポートと、英語および中国語のバリアントを生成する:

• evidence.json: 機械可読な証拠と透明性のあるメトリクス
• report.md: 可搬性のあるテキストレポート
• report.html: 自己完結型のビジュアルレポート（EN / 中文 切り替え可能）
• evidence.en.json, report.en.md, report.en.html: 英語出力
• evidence.zh.json, report.zh.md, report.zh.html: 中国語出力

3. ナレーションの前に証拠を検査する

evidence.json を読み、以下を確認する:

• journey_insights を最初に確認: そのトピック、暫定的な分類、証拠の連鎖、確信度、確認質問
• トランスクリプトが許可されている場合の communication_insights: 最大3枚のカードで、それぞれが順序付けられたユーザーリクエスト、アシスタントの応答、その後のユーザーによる修正に基づいていること
• すべてのコミュニケーション属性が明確に区別されていること: 後で明確化された情報、AI が明示的な要件を無視した、用語の意味が異なった、要件が進化した、または証拠が不十分
• データソースと記載された制限事項
• プロジェクトの日付、コミット数、作成者、ファイル数
• 最初の画面のストーリーが選択された転換点によって裏付けられているか
• プロジェクト期間、アクティブ日数、最長実行期間、最もアクティブだった日が、基礎となる日付付き証拠と一致しているか
• 明示的なリバートと推測される高チャーンループの区別
• 時間見積もりが Git から来たのか、タイムスタンプ付きセッションから来たのか
• すべての次元スコアの背後にある証拠と確信度

src/foo.py、コミット数、チャーンパーセンテージでチャットをリードしない。最も強い洞察を最初に平易な言葉に変換する:

1. ユーザーが何を試みたように見えるか
2. それが現在、ブロックされたループ、必要な探索、方向転換のいずれのように見えるか
3. どのコミットがその解釈を支持するか
4. 結論を変える可能性のある、欠落している人間の事実は何か

データがユーザーの説明と矛盾する場合は、矛盾点を示して尋ねる。黙って一方のバージョンを選択しない。

中国語レポートの場合、表示されている転換点のタイトルと会話の抜粋を検査する。ソース資料が別の言語の場合、zh.translations に正確なソースから中国語へのエントリを追加して再実行する。証拠データ内の元のテキストは保持するが、中国語インターフェース内で英語の開発ストーリーをユーザーに読ませない。

許可されたトランスクリプトが存在する場合、各転換点に付随する短いユーザーリクエストと AI の応答を使用する。コミットの件名だけをストーリー全体として提示するよりも、この人間が読める対話を優先する。

4. 成果を書く前に旅を確認する

合計で最大3つの確認質問をする。最も確信度の高い未確認の journey_insights から選択し、ユーザーがコミュニケーションレビューを要求した場合にのみ、1つまたは2つの communication_insights を追加する。確認オブジェクトを手動で編集するようユーザーに求めない。ユーザーが回答した後、旅の確認を insight_confirmations に、またはコミュニケーションの確認を communication_confirmations に書き込み、アナライザーを再実行し、レポートに確認された解釈が表示されていることを確認する。

旅が確認された後にのみ、残りのキャリアコンテキストを尋ねる。ワークフローを面接にしない。通常不足している事実は以下の通り:

1. ユーザーの実際の責任は何だったか？
2. プロジェクトはユーザーまたは自身にとってどのような結果を生み出したか？
3. ユーザーの能力を最もよく示す決定はどれか？

リポジトリにすでに文書化されている回答については質問をスキップする。

キャリア、ポートフォリオ、成果、面接の出力については、これらの回答をチャットのみのコンテキストとして残さない。context.json に保存し、アナライザーを再実行し、結果の再利用可能なマテリアルを確認する。HTML レポートは永続的な成果物であり、確認のための会話の代わりではない。

5. 要求されたストーリーを生成する

証拠を以下の1つ以上の出力に使用する:

• プロジェクト振り返り: タイムライン、転換点、摩擦、教訓、次回の変更点。
• コミュニケーションレビュー: 元の文言、アシスタントの解釈、後の修正、中立的な帰属、そして裏付けがある場合のみ、コピー可能な書き直しと再利用可能なパターン。最大3枚のカードを表示し、プロンプトスコアを決して与えない。
• ポートフォリオケーススタディ: 問題、制約、決定、実装、検証、結果。
• 履歴書の箇条書き: 行動 + 範囲 + 方法 + 検証済み結果。影響が不明な場合は明示的なプレースホルダーを残す。
• 面接ストーリー: コミット、差分、テスト、リリース、ユーザー確認済みコンテキストに基づいた STAR 構造。
• 実績記録: ユーザーが実際に何をしたかを説明する永続的な証拠カード。

キャリアまたはポートフォリオの文章を作成する場合は、references/narrative-guide.md を読む。スコア、時間見積もり、またはループ検出を説明する場合は、references/methodology.md を読む。

出力品質基準

完成した BuildStory レポートは、ユーザーが以下の質問に答えられるようにするべきである:

1. このプロジェクトの一文のストーリーは何か？
2. 観測可能な作業はどのカレンダー期間にわたって、何日間発生し、最も活動的だった日は何があったか？
3. どの5～7の転換点が、その方向性、リスク、理解、またはデリバリー状態を変えたか？
4. 作業が繰り返しループしたり逆戻りしたりした箇所はどこか？
5. 繰り返された各領域は、ブロックされたループ、必要な探索、方向転換のいずれであり、まだ確認が必要なことは何か？
6. 最も注意を吸収した領域はどこか、その見積もりの確信度はどの程度か？
7. ユーザーが実際に学んだり改善したりしたことは何か？
8. 履歴書、ポートフォリオ、面接、個人記録に再利用できる信頼できる成果は何か？
9. AI がすでに行動した後にのみ明らかになった詳細は何か、原因はどのように帰属されるべきか、次回は何をより早く言えるか？

利用可能な証拠がこれらのいずれかに答えられない場合、何が欠けているかを述べる。小さくても正直なストーリーは、印象的だが架空のストーリーよりも優れている。