playbooks

home / skills / shipshitdev / library / session-documenter

session-documenter skill

/bundles/session/skills/session-documenter

This skill documents session work with explicit commands, tracking decisions, file changes, and context for continuity across daily sessions.

npx playbooks add skill shipshitdev/library --skill session-documenter

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.9 KB
---
name: session-documenter
description: Document session work with explicit commands. Use /start to begin tracking, /end to finalize session, /clear to reset. Tracks decisions, file changes, and context for continuity.
triggers:
  - /start
  - /end
  - session start
  - session end
  - document session
  - what did we do
  - track this decision
---

# Session Documenter Skill

Document work, decisions, and context with explicit commands.

## Commands

| Command | Action |
|---------|--------|
| `/start` | Begin new session - creates/appends to today's file, loads context |
| `/end` | Finalize session - writes entry with all tracked work, updates related files |

## How It Works

1. **`/start`** - Creates `.agents/SESSIONS/YYYY-MM-DD.md` if missing, or loads existing context
2. **During session** - You tell me what to track: decisions, files changed, mistakes
3. **`/end`** - I write the full session entry with flowcharts, decisions, next steps

## Critical Rules

### Session File Naming (ONE FILE PER DAY)

```
✅ CORRECT: .agents/SESSIONS/2025-11-15.md
❌ WRONG:   .agents/SESSIONS/2025-11-15-feature-name.md
```

Multiple sessions same day → Same file, Session 1, Session 2, etc.

### Flowcharts (MANDATORY for features)

Include flowchart for:

- New features
- Feature modifications
- Multi-component bug fixes

## Session Entry Structure

1. **Session number and title**
2. **System flow diagram** (mermaid or text)
3. **Affected components** (frontend, backend, data, external)
4. **What was done** (task checklist)
5. **Key decisions** (with rationale)
6. **Files changed**
7. **Mistakes and fixes**
8. **Next steps**

## Related Files to Update

- `.agents/SESSIONS/README.md`
- `.agents/SYSTEM/SUMMARY.md`
- `.agents/TASKS/*/TODO.md`
- `.agents/SYSTEM/ARCHITECTURE.md` (if architectural decisions)

## References

- [Full guide: Phases, automation, validation, examples](references/full-guide.md)

Overview

This skill documents session work with explicit commands to create consistent daily session records. Use /start to begin tracking, /end to finalize an entry, and /clear to reset the current session. It captures decisions, file changes, mistakes, and next steps to maintain continuity across work sessions.

How this skill works

When you run /start the skill creates or loads today's session file in .agents/SESSIONS/YYYY-MM-DD.md and begins collecting context. During the session you report decisions, files changed, and mistakes; the skill appends these notes and keeps a running checklist. When you run /end it composes a full session entry including a system flow diagram, affected components, tasks completed, files changed, mistakes and fixes, and recommended next steps. /clear resets the in-memory tracking if you need to abandon or restart the current session.

When to use it

  • Beginning a focused development or design session to ensure traceability
  • Working across multiple components where decisions must be recorded
  • Fixing multi-component bugs that require flow diagrams and rationale
  • Handing off work between team members to preserve context
  • Tracking iterative sessions across a single day (Session 1, Session 2, etc.)

Best practices

  • Start every work block with /start so entries are consistently timestamped
  • Keep one file per day in .agents/SESSIONS/YYYY-MM-DD.md; append multiple sessions to that file
  • Include a flowchart for new features, feature changes, or multi-component fixes
  • Record decisions with brief rationale to support future reviews
  • List files changed and mistakes with the applied fixes for auditability

Example use cases

  • Implementing a new feature that touches frontend and backend: document flow, decisions, and changed files
  • Refactoring a module: track steps, mistakes, and rollbacks so others can follow the process
  • Investigating and resolving a cross-service bug: include a system diagram and next steps
  • Handing off partial work at end of day: finalize the session so the next person has context

FAQ

What happens if I start multiple sessions the same day?

All sessions for the same date append to the same daily file as separate session entries (Session 1, Session 2, etc.).

Is a flowchart always required?

Flowcharts are mandatory for new features, feature modifications, and multi-component bug fixes; use text diagrams for smaller changes.