Use CLAUDE.md session rules as primary mechanism → Dropped. Wastes tokens every session. Skill-only approach instead.
Show in-progress FRs in recap? → Yes, show all in-progress FRs with their next-step.
Session handoff file? → No. Git log + vault state is sufficient. Revisit only if proven inadequate.
What does “recently modified” mean? → Changes in last 24h, via git log --since="24 hours ago" --name-only.
User Tasks
Test /recap skill after implementation
Summary
A /recap skill that shows recent changes and active work at session start, so the user never loses overview.
Problem / Motivation
Changes accumulate across sessions and the repo/vault grows. Without a recap, the user has to manually piece together what happened. This creates anxiety about losing control.
Proposed Solution
A /recap skill that shows six sections — each answering one question:
Recent commits (last 5, oneline) — what happened?
In-progress FRs + next-step — what’s active?
Your todos (Now / Next from vault/my-todos.md) — what did I promise myself?
Pending proposals (count + titles from vault/90_inbox/proposals/) — what did Claude suggest?
Inbox flag (unprocessed content in quick-notes.md: yes/no) — anything captured I forgot?
Suggested next (top 2-3 FRs from 03_planned/ by priority, fallback to 02_new/) — what should I pick up?
No persistent state needed — all data is derived live from git and vault.
Phase Overview
Phase
Description
Status
Phase 1
/recap skill + auto-trigger
—
Phase 1: /recap Skill + Auto-trigger — —
Goal: Build a /recap skill and auto-trigger it at session start.
File / Feature
Details
Owner
Status
Skill SKILL.md
Prompt template for /recap
opus
done
Recent commits
Last 5 commits, oneline format
opus
done
In-progress FRs
Glob 04_in-progress/, extract title + next-step (all)
opus
done
User todos
Read vault/my-todos.md, show Now + Backlog sections
opus
done
Pending proposals
Count + titles from vault/90_inbox/proposals/
opus
done
Inbox flag
Check quick-notes.md for unprocessed content
opus
done
Suggested next
Top 2-3 FRs from 03_planned/ by priority, fallback 02_new/
opus
done
CLAUDE.md trigger
Add “Run /recap at the start of each session” to CLAUDE.md
opus
proposal
Test
Verify recap runs automatically in fresh sessions
mv
—
Note: Claude Code has no “on session start” hook. The only way to auto-trigger is a one-line instruction in CLAUDE.md (~10 tokens). The skill itself contains all logic — CLAUDE.md just triggers it.
Prerequisites / Gap Analysis
Requirements
Requirement
Description
REQ-1
Skill infrastructure available (.claude/skills/)
Current State
Component
Status
Details
Skill infrastructure
done
.claude/skills/ ready
/recap skill
—
Not yet created
Gap (What’s missing?)
Gap
Effort
Blocker?
/recap skill
Low
No
Test
Manual tests
Test
Expected
Actual
Last
Start fresh session (no user input)
/recap runs automatically, shows recap
pending
-
Run /recap manually
Shows all 6 sections with real data
pending
-
Run /recap with no activity
Handles empty sections gracefully
pending
-
AI-verified tests
Test
Expected
Actual
Last
In-progress FRs shown with next-step
All FRs from 04_in-progress/, each with next-step
pending
-
Pending proposals counted
Count + titles from proposals/ subdirs
pending
-
Suggested next picks from planned/new
Top 2-3 by priority from 03_planned/, fallback 02_new/
pending
-
Test
Expected
Actual
Last
/recap completes without error
No crashes, all sections render
pending
-
E2E tests
Scenario
Assertion
…
…
Integration tests
Component
Coverage
…
…
Unit tests
Component
Tests
Coverage
…
…
…
History
Date
Event
Details
2026-02-26
Created
Born from user’s concern about losing overview
2026-02-26
Phase 1 attempted
CLAUDE.md session rules — later found missing
2026-03-16
Review + pivot
Dropped CLAUDE.md rules approach. Simplified to single-phase skill-only. All decisions resolved.
2026-03-16
Scope expanded
Added pending proposals, inbox flag, and suggested next sections based on user input. Dropped “files changed in 24h” (redundant with commits).
References
Origin: user’s concern about losing overview across sessions