specstory-yak

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Specstory Yak Shave Analyzer

SpecStory Yak Shave 分析工具

Analyzes your

.specstory/history

to detect when coding sessions drifted off track from their original goal. Produces a "yak shave score" for each session.

分析你的

.specstory/history

文件，检测编码会话何时偏离了最初目标。为每个会话生成一个“Yak Shave分数”。

How It Works

工作原理

Parses specstory history files from a date range (or all recent sessions)
Extracts the initial user intent from the first message
Tracks domain shifts: file references, tool call patterns, goal changes
Scores each session from 0 (laser focused) to 100 (maximum yak shave)
Summarizes your worst offenders and patterns

解析指定日期范围（或所有近期会话）的SpecStory历史文件
提取第一条消息中的用户初始意图
追踪领域转移：文件引用、工具调用模式、目标变更
为每个会话打分，分数范围0（高度专注）到100（完全偏离目标）
总结你最严重的偏离案例和常见模式

What Is Yak Shaving?

什么是Yak Shaving？

"I need to deploy my app, but first I need to fix CI, but first I need to update Node, but first I need to fix my shell config..."

Yak shaving is when you start with Goal A but end up deep in unrelated Task Z. This skill detects that pattern in your AI coding sessions.

“我需要部署我的应用，但首先我得修复CI，然后得更新Node，接着又得修复我的shell配置……”

Yak Shaving指的是你从目标A开始，最终却深陷无关的任务Z中。本工具可以检测你在AI编码会话中的这种模式。

Usage

使用方法

Slash Command

斜杠命令

When invoked via

/specstory-yak

, interpret the user's natural language:

User says	Script args
`/specstory-yak`	`--days 7` (default)
`/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`

通过

/specstory-yak

调用时，可理解用户的自然语言：

用户指令	脚本参数
`/specstory-yak`	`--days 7` （默认值）
`/specstory-yak 过去30天`	`--days 30`
`/specstory-yak 本周`	`--days 7`
`/specstory-yak 前10名`	`--top 10`
`/specstory-yak 一月`	`--from 2026-01-01 --to 2026-01-31`
`/specstory-yak 从1月15日到1月20日`	`--from 2026-01-15 --to 2026-01-20`
`/specstory-yak 按修改时间`	`--by-mtime`
`/specstory-yak 过去14天以JSON格式输出`	`--days 14 --json`
`/specstory-yak 保存到yak-report.md`	`-o yak-report.md`
`/specstory-yak 过去90天输出到报告`	`--days 90 -o report.md`

Direct Script Usage

直接运行脚本

bash

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

Arguments:

```
--days N
```
- Analyze last N days (default: 7)
```
--from DATE
```
- Start date (YYYY-MM-DD)
```
--to DATE
```
- End date (YYYY-MM-DD)
```
--path PATH
```
- Path to .specstory/history (auto-detects if not specified)
```
--top N
```
- Show top N worst yak shaves (default: 5)
```
--json
```
- Output as JSON
```
--verbose
```
- Show detailed analysis
```
--by-mtime
```
- Filter by file modification time instead of filename date
```
-o, --output FILE
```
- Write report to file (auto-adds .md or .json extension)

Examples:

bash

undefined

bash

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扩展名）

示例：

bash

undefined

Analyze last 7 days

分析过去7天的会话

python scripts/analyze.py

Analyze last 30 days, show top 10

分析过去30天的会话，显示前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

输出JSON格式用于后续处理

python scripts/analyze.py --days 14 --json

Save report to a markdown file

将报告保存为Markdown文件

python scripts/analyze.py --days 90 -o yak-report.md

Save JSON to a file

将JSON数据保存到文件

python scripts/analyze.py --days 30 --json -o yak-data.json

undefined

python scripts/analyze.py --days 30 --json -o yak-data.json

undefined

Output

输出示例

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)

Yak Shave 报告（2026-01-21 至 2026-01-28）
==========================================

分析的会话数量：23
平均Yak Shave分数：34/100

严重偏离会话TOP榜：
---------------
1. [87/100] "修复按钮对齐"（2026-01-25）
   初始目标：修复按钮的CSS样式
   最终结果：重写整个构建系统
   领域转移次数：4次（UI -> 构建 -> Docker -> K8s）

2. [72/100] "添加登出功能"（2026-01-23）
   初始目标：添加登出按钮
   最终结果：重构认证系统 + 会话管理
   领域转移次数：3次（UI -> 认证 -> 数据库）

3. [65/100] "更新README"（2026-01-22）
   初始目标：更新文档
   最终结果：全面整改CI流水线
   领域转移次数：2次（文档 -> CI -> 测试）

最专注会话：
----------------------
1. [5/100] "解释认证流程"（2026-01-26）- 纯分析，无偏离
2. [8/100] "修复配置文件中的拼写错误"（2026-01-24）- 快速精准修复

检测到的模式：
------------------
- 你最容易出现偏离的任务类型：UI任务（平均分数58/100）
- 最不易偏离的任务类型：代码评审/解释（平均分数12/100）
- 偏离高峰时段：23:00-02:00（平均分数71/100）

Scoring Methodology

评分机制

The yak shave score (0-100) is computed from:

Factor	Weight	Description
Domain shifts	40%	How many times file references jumped domains
Goal completion	25%	Did the original stated goal get completed?
Session length ratio	20%	Length vs. complexity of original ask
Tool type cascade	15%	Read->Search->Edit->Create->Deploy escalation

Score interpretation:

0-20: Laser focused
21-40: Minor tangents
41-60: Moderate drift
61-80: Significant yak shaving
81-100: Epic rabbit hole

Yak Shave分数（0-100）由以下因素计算得出：

影响因素	权重	说明
领域转移次数	40%	文件引用跨领域跳转的次数
目标完成度	25%	最初设定的目标是否完成？
会话时长占比	20%	会话时长与初始需求复杂度的比例
工具调用层级	15%	从读取->搜索->编辑->创建->部署的升级情况

分数解读：

0-20：高度专注
21-40：轻微偏离
41-60：中度偏离
61-80：严重偏离
81-100：完全偏离目标

Present Results to User

向用户展示结果

IMPORTANT: After running the analyzer script, you MUST add a personalized LLM-generated summary at the very top of your response, BEFORE showing the raw report output.

重要提示：运行分析脚本后，必须在响应最顶部添加由大语言模型生成的个性化摘要，再展示原始报告内容。

LLM Summary Guidelines

大语言模型摘要撰写指南

Generate a 3-5 sentence personalized commentary that:

Opens with a verdict - A witty one-liner about the overall state (e.g., "Your coding sessions this week were... an adventure." or "Remarkably disciplined! Someone's been taking their focus vitamins.")
Calls out the highlight - Reference the most notable session specifically:
- If high yak shave: "That January 25th button fix that somehow became a Kubernetes migration? Chef's kiss of scope creep."
- If low yak shave: "Your January 26th auth flow explanation was surgical - in and out, no detours."
Identifies a pattern - Note any recurring theme:
- "You seem to yak shave most when starting with UI tasks"
- "Late night sessions are your danger zone"
- "Your refactoring sessions tend to stay focused"
Ends with actionable advice or a joke - Either:
- A practical tip: "Consider time-boxing those 'quick CSS fixes' - they have a 73% yak shave rate"
- Or a joke: "At this rate, your next typo fix will result in a complete rewrite of the Linux kernel"

生成3-5句个性化评论，需包含：

开篇结论 - 一句风趣的总体评价（例如：“你本周的编码会话可谓是一场‘意外之旅’。” 或 “纪律性极佳！看来你最近一直在服用‘专注维生素’。”）
重点案例 - 特别提及最典型的偏离会话：
- 若严重偏离：“那项1月25日的按钮修复任务，最后居然演变成了Kubernetes迁移？这堪称‘范围蔓延’的典范。”
- 若高度专注：“你1月26日的认证流程解释会话精准利落，没有丝毫偏离。”
模式识别 - 指出重复出现的规律：
- “我发现你在处理UI任务时最容易出现目标偏离”
- “深夜会话是你的偏离高发时段”
- “你的重构会话通常能保持专注”
可行动建议或玩笑 - 二选一：
- 实用建议：“建议为那些‘快速UI修复’任务设置时间限制——它们有73%的概率演变成3小时的‘冒险’”
- 玩笑：“照这个趋势，你下次修复拼写错误可能会重写整个Linux内核”

Example LLM Summary

大语言模型摘要示例

undefined

undefined

🐃 Your Yak Shave Analysis

🐃 你的Yak Shaving分析结果

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:


Then show the raw report output below your summary.

好吧好吧，你本来是去修复按钮的，结果最后重构了半个基础设施。你的平均Yak Shave分数为47/100，完美契合“典型开发者行为”。

最突出的案例？1月25日的那场会话，从修复CSS按钮对齐，一路演变成了完整的Kubernetes部署重构。经过4次领域转移，你可能都忘了按钮长什么样了。

我发现一个规律：你处理UI任务时的偏离概率比代码评审会话高58%。或许你应该在日历里把那些“快速UI修复”标注成“潜在3小时冒险”。

以下是完整分析详情：


然后在摘要下方展示原始报告内容。

What to Highlight

展示重点

After your summary, when presenting the raw results:

The worst offenders with before/after comparison
Patterns in when/what causes yak shaving
Actionable insight - what task types to watch out for

在摘要之后，展示原始结果时需重点突出：

最严重的偏离案例，包含初始目标与最终结果的对比
引发偏离的时间/任务类型规律
可行动洞察 - 需要警惕哪些任务类型