specstory-yak

Specstory ヤク剃り分析ツール

.specstory/history を分析し、コーディングセッションが当初の目標から逸れていないかを検出します。各セッションの「ヤク剃りスコア」を算出します。

仕組み

1. 日付範囲内（または直近のすべてのセッション）の Specstory 履歴ファイルを解析します
2. 最初のメッセージからユーザーの初期の意図を抽出します
3. ファイル参照、ツール呼び出しのパターン、目標の変更など、領域の移り変わりを追跡します
4. 各セッションを 0（集中できている）から 100（ヤク剃りが最大限）の範囲で採点します
5. 最も逸脱したセッションと傾向を要約します

ヤク剃りとは？

「アプリをデプロイする必要があるけれど、その前に CI を修正しないと。いや、その前に Node を更新して、その前にシェル設定を直さないと……」

ヤク剃りとは、目標 A から始めたのに、気付けば無関係なタスク Z に深く入り込んでしまうことです。このスキルは、AI コーディングセッションでそのパターンを検出します。

使い方

スラッシュコマンド

/specstory-yak で呼び出された場合は、ユーザーの自然言語を解釈します。

ユーザーの入力	スクリプト引数
/specstory-yak	--days 7（デフォルト）
/specstory-yak last 30 days	--days 30
/specstory-yak this week	--days 7
/specstory-yak top 10	--top 10
/specstory-yak january	--from 2026-01-01 --to 2026-01-31
/specstory-yak from jan 15 to jan 20	--from 2026-01-15 --to 2026-01-20
/specstory-yak by modification time	--by-mtime
/specstory-yak last 14 days as json	--days 14 --json
/specstory-yak save to yak-report.md	-o yak-report.md
/specstory-yak last 90 days output to report	--days 90 -o report.md

スクリプトを直接実行する

python /path/to/skills/specstory-yak/scripts/analyze.py [options]

引数：

• --days N - 直近 N 日間を分析します（デフォルト：7）
• --from DATE - 開始日（YYYY-MM-DD）
• --to DATE - 終了日（YYYY-MM-DD）
• --path PATH - .specstory/history へのパス（指定がない場合は自動検出）
• --top N - ヤク剃りがひどい上位 N 件を表示します（デフォルト：5）
• --json - JSON 形式で出力します
• --verbose - 詳細な分析を表示します
• --by-mtime - ファイル名の日付ではなく、ファイルの更新日時で絞り込みます
• -o, --output FILE - レポートをファイルに書き込みます（.md または .json 拡張子を自動で追加）

例：

# Analyze last 7 days
python scripts/analyze.py

# Analyze last 30 days, show top 10
python scripts/analyze.py --days 30 --top 10

# Analyze specific date range
python scripts/analyze.py --from 2026-01-01 --to 2026-01-28

# Filter by when files were modified (not session start time)
python scripts/analyze.py --days 7 --by-mtime

# JSON output for further processing
python scripts/analyze.py --days 14 --json

# Save report to a markdown file
python scripts/analyze.py --days 90 -o yak-report.md

# Save JSON to a file
python scripts/analyze.py --days 30 --json -o yak-data.json

出力

Yak Shave Report (2026-01-21 to 2026-01-28)
==========================================

Sessions analyzed: 23
Average yak shave score: 34/100

Top Yak Shaves:
---------------
1. [87/100] "fix button alignment" (2026-01-25)
   Started: CSS fix for button
   Ended up: Rewriting entire build system
   Domain shifts: 4 (ui -> build -> docker -> k8s)

2. [72/100] "add logout feature" (2026-01-23)
   Started: Add logout button
   Ended up: Refactoring auth system + session management
   Domain shifts: 3 (ui -> auth -> database)

3. [65/100] "update readme" (2026-01-22)
   Started: Documentation update
   Ended up: CI pipeline overhaul
   Domain shifts: 2 (docs -> ci -> testing)

Most Focused Sessions:
----------------------
1. [5/100] "explain auth flow" (2026-01-26) - Pure analysis, no drift
2. [8/100] "fix typo in config" (2026-01-24) - Quick surgical fix

Patterns Detected:
------------------
- You yak shave most on: UI tasks (avg 58/100)
- Safest task type: Code review/explanation (avg 12/100)
- Peak yak shave hours: 11pm-2am (avg 71/100)

採点方法

ヤク剃りスコア（0～100）は、以下の要素から算出されます。

要素	重み	説明
領域の移り変わり	40%	ファイル参照が異なる領域に移った回数
目標の達成	25%	当初に示された目標が達成されたか
セッションの長さの比率	20%	当初の依頼の複雑さに対するセッションの長さ
ツール種別の連鎖	15%	Read->Search->Edit->Create->Deploy という段階的な拡大

スコアの解釈：

• 0-20：集中できています
• 21-40：少し脱線しています
• 41-60：中程度に逸れています
• 61-80：大きくヤク剃りしています
• 81-100：壮大な迷路に入り込んでいます

ユーザーへの結果の提示

重要：分析スクリプトを実行した後、生のレポート出力を表示する前に、必ず LLM が生成したユーザーに合わせた要約を回答の最上部に追加してください。

LLM の要約ガイドライン

以下の内容を含む、3〜5文のパーソナライズされたコメントを生成します。

1. 評価から始める - 全体の状況について、気の利いた一言を添えます（例：「今週のコーディングセッションは……冒険でしたね。」または「見事に規律が保たれています！集中力のサプリメントを飲んでいる人がいるようです。」）

2. ハイライトを取り上げる - 最も注目すべきセッションに具体的に言及します。

   • 付随作業が多かった場合：「1月25日のボタン修正が、どういうわけか Kubernetes の移行に発展した件は？スコープクリープの極みですね。」
   • 付随作業が少なかった場合：「1月26日の認証フローの説明は、無駄がありませんでしたね。寄り道せず、さっと終わりました。」

3. パターンを特定する - 繰り返し見られる傾向に触れます。

   • 「UI タスクから始めると、付随作業が増えやすいようです」
   • 「深夜のセッションは要注意です」
   • 「リファクタリングのセッションは、集中を保てる傾向があります」

4. 実践的なアドバイスかジョークで締める - 次のどちらかを含めます。

   • 実践的なヒント：「『ちょっとした CSS の修正』には時間制限を設けることを検討してみてください。付随作業に発展する確率は73％です」
   • またはジョーク：「この調子だと、次のタイプミス修正で Linux カーネルを丸ごと書き直すことになりそうです」

LLM の要約例

## 🐃 Your Yak Shave Analysis

Well, well, well. You came to fix buttons and left having rewritten half the
infrastructure. Your average yak shave score of 47/100 puts you firmly in
"classic developer behavior" territory.

The standout? That January 25th session where a CSS alignment fix somehow
evolved into a full Kubernetes deployment overhaul. Four domain shifts later,
you probably forgot what a button even looks like.

Pattern I noticed: Your UI tasks have a 58% higher yak shave rate than your
code review sessions. Maybe start labeling those "quick UI fixes" as
"potential 3-hour adventures" in your calendar.

Here's the full breakdown:

次に、要約の下にレポートの生出力を表示します。

注目するポイント

要約の後、生の結果を提示する際は、次の点を取り上げます。

1. 修正前後の比較を含む、最も問題の大きいケース
2. いつ、何が付随作業を引き起こすかというパターン
3. 注意すべきタスクの種類に関する実践的な知見