Specstory Yak Shave Analyzer

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

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

What Is 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.

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

Direct Script Usage

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:

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

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)

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

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"

Example LLM Summary

🐃 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:

Then show the raw report output below your summary.

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