القائمة
Analyze your SpecStory AI coding sessions in .specstory/history for yak shaving - when your initial goal got derailed into rabbit holes. Run when user says "analyze my yak shaving", "check for rabbit holes", "how distracted was I", or "yak shave score".
| name | specstory-yak |
| description | Analyze your SpecStory AI coding sessions in .specstory/history for yak shaving - when your initial goal got derailed into rabbit holes. Run when user says "analyze my yak shaving", "check for rabbit holes", "how distracted was I", or "yak shave score". |
| license | Apache-2.0 |
| metadata | {"author":"specstory","version":"1.0.0","argument-hint":"[days|date-range]"} |
Analyzes your .specstory/history to detect when coding sessions drifted off track from their original goal. Produces a "yak shave score" for each session.
"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.
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 |
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
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)
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:
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.
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:
Identifies a pattern - Note any recurring theme:
Ends with actionable advice or a joke - Either:
## 🐃 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.
After your summary, when presenting the raw results:
Analyzes, generates, and enhances CLAUDE.md files for any project type using best practices, modular architecture support, and tech stack customization. Use when setting up new projects, improving existing CLAUDE.md files, or establishing AI-assisted development standards.
Create, review, and iterate on Claude Code skills using Anthropic's official best practices and latest API documentation. Use when creating skills, reviewing existing skills, writing skill descriptions, designing skill architecture, or when user says "create a skill", "review my skill", "skill best practices", "skill description help". Do NOT use for creating plugins, commands, agents, or hooks - use plugin-dev skills for those.
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.
Install a pre-commit hook that scans .specstory/history for secrets before commits. Run when user says "set up secret scanning", "install specstory guard", "protect my history", or "check for secrets".
Use when the user asks to "audit my codebase", "act as a project architect", "find open source alternatives", "enhance this project", "scale the architecture", or "generate missing documentation". Use when the user needs structural improvements, security audits, paradigm shifts, or broad ecosystem enhancements beyond simple refactoring.
Automate macOS tasks using AppleScript, shell scripts, Shortcuts, and system commands. Use when working with macOS automation, AppleScript, Finder operations, system preferences, app automation, file management, or macOS-specific workflows.