trails

name	trails
description	This skill should be used when creating session handoffs, logging research findings, or reading previous trail notes. Triggers include handoff, session continuity, log note, trail notes, or when ending a session.
metadata	{"version":"1.0.2"}

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.

# 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.

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

# 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

# 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