trails

# Trail Session continuity through structured handoffs and freeform logs. <when_to_use> - End of session — create handoff for continuity - During research — capture findings in logs - Subagent work — preserve context with parent session linking - Any time you need to leave a trail for future sessions </when_to_use> ## Commands | Command | Purpose | | ----------------------- | ----------------------------------------------------- | | `/trail:handoff` | Create structured handoff note for session continuity | | `/trail:log <slug>` | Create freeform timestamped log note | | `/trail:read [options]` | Read recent trail notes | ## Handoff Format Handoffs are the atomic unit of session continuity. Create one at the end of each session. ```markdown # Handoff > YYYY-MM-DD HH:MM · Session `<short-id>` ## Done - Completed item 1 - Completed item 2 ## State Current state of work: - What's in progress - What's blocked - Key decisions made ## Next - [ ] First priority task - [ ] Second priority task - [ ] Lower priority item ``` ### Handoff Principles - **Done**: Past tense, concrete accomplishments - **State**: Present tense, current situation - **Next**: Checkboxes for actionable items - **Scannable**: Someone should grasp the session in 30 seconds - **Honest**: Note blockers, uncertainties, and open questions ## Log Format Logs are freeform notes for capturing anything worth preserving. ```markdown # Title Derived From Slug > YYYY-MM-DD HH:MM · Session `<short-id>` { freeform content — research findings, technical discoveries, meeting notes, ideas, observations, etc. } ``` ### Log Use Cases - Research findings and documentation - Technical discoveries and gotchas - Meeting notes and decisions - Ideas and observations - Debugging sessions and root causes ### Log Principles - **Descriptive slug**: Will become the title if none provided - **Tag liberally**: Use frontmatter tags for discoverability - **Link context**: Reference issues, PRs, or other notes - **Future-proof**: Write for someone (including future you) with no context ## Subagent Context When working as a subagent, pass the parent session ID to group related notes: ```bash # Handoff with parent context bun ${CLAUDE_PLUGIN_ROOT}/skills/trails/scripts/handoff.ts \ --session "$CHILD_SESSION" \ --parent "$PARENT_SESSION" # Log with parent context bun ${CLAUDE_PLUGIN_ROOT}/skills/trails/scripts/log.ts \ --slug "api-findings" \ --session "$CHILD_SESSION" \ --parent "$PARENT_SESSION" ``` This creates notes in a subdirectory: `.trail/notes/YYYY-MM-DD/<parent-session>/` ## Reading Notes ```bash # Today's notes (all types) /trail:read # Just handoffs /trail:read --type handoff # Just logs /trail:read --type log # Last 3 days /trail:read --days 3 # Limit output /trail:read --lines 100 ``` ## Directory Structure ``` .trail/ ├── notes/ │ └── YYYY-MM-DD/ │ ├── handoff-YYYYMMDDhhmm-<session>.md │ ├── YYYYMMDDhhmm-<slug>.md │ └── <parent-session>/ # Subagent notes │ ├── handoff-YYYYMMDDhhmm-<child>.md │ └── YYYYMMDDhhmm-<slug>.md ├── plans/ # Implementation plans └── artifacts/ # Research, ADRs, etc. ``` ## Filename Convention Pattern: `[prefix-]YYYYMMDDhhmm[-suffix].md` | Type | Prefix | Suffix | Example | | ------- | --------- | ---------- | ---------------------------------- | | Handoff | `handoff` | session ID | `handoff-202601221430-f4b8aa3a.md` | | Log | none | slug | `202601221430-api-research.md` | The timestamp (`YYYYMMDDhhmm`) is the anchor — files remain sortable and portable even if moved. ## Session Start Ritual When resuming work: 1. Run `/trail:read --type handoff` to see recent handoffs 2. Check the **Next** section for pending tasks 3. Continue where the previous session left off ## Session End Ritual Before ending a session: 1. Run `/trail:handoff` to create a handoff note 2. Fill in **Done**, **State**, and **Next** sections 3. Be specific enough that a fresh session can continue seamlessly