172 lines
4.2 KiB
Markdown
172 lines
4.2 KiB
Markdown
---
|
|
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.0"
|
|
---
|
|
|
|
# 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
|