specstory-yak

Specstory Yak Shave 分析器

分析你的 .specstory/history，检测编码会话是否偏离了最初的目标。为每个会话生成一个“剃牦牛分数”。

工作原理

1. 解析 指定日期范围内的 specstory 历史文件（或所有近期会话）
2. 提取 第一条消息中的初始用户意图
3. 跟踪 领域变化：文件引用、工具调用模式、目标变更
4. 评分 每个会话，范围从 0（专注如激光）到 100（剃牦牛程度最高）
5. 总结 最严重的偏离情况及其模式

什么是剃牦牛？

“我需要部署应用，但首先得修复 CI；但首先得更新 Node；但首先得修复 shell 配置……”

剃牦牛指的是从目标 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 生成的个性化总结。

大模型总结指南

生成一段 3-5 句的个性化点评：

1. 以结论开篇 - 用一句风趣的话概括整体情况（例如：“你这周的编码时光真是……一场冒险。”或“真是令人惊叹的自律！看来有人一直在补充专注力维生素。”）

2. 点出亮点 - 具体提及最值得关注的会话：

   • 如果范围蔓延严重：“1 月 25 日那个按钮修复，怎么就变成 Kubernetes 迁移了？范围蔓延堪称绝妙之作。”
   • 如果范围蔓延轻微：“你 1 月 26 日对身份验证流程的说明干净利落——直奔主题，没有绕路。”

3. 找出规律 - 指出反复出现的主题：

   • “你似乎在开始处理 UI 任务时，最容易越修越多”
   • “深夜会话是你的危险时段”
   • “你的重构会话通常都很专注”

4. 以可执行建议或笑话结尾 - 二选一：

   • 实用建议：“可以给那些‘快速修复 CSS’的任务设定时间上限——它们有 73% 的概率会越修越多。”
   • 或者开个玩笑：“照这样下去，你下次修复一个错别字，就会导致 Linux 内核被彻底重写。”

大模型总结示例

## 🐃 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. 可执行的见解——哪些任务类型需要留意