Session Logger

Pre-Execution: Brainstorm & Plan

MANDATORY — Before executing this skill's workflow, complete these two steps:

Step 1: Brainstorm

Invoke the superpowers:brainstorming skill to explore user intent, clarify requirements, and align on the desired outcome before proceeding with this skill.

Step 2: Plan

If the task involves multiple steps or decisions, invoke the superpowers:writing-plans skill to create a structured execution plan before proceeding.

Only after brainstorming and planning are complete should you proceed to the skill workflow below.

Comprehensive session logging skill that creates detailed, timestamped work logs for session continuity. Operates via three explicit commands.

Commands

Infrastructure Paths

Workspace base path: ~/your-workspace

Command: /log start

What to do

1. Determine the working directory — Use the directory where the primary task output will be created. If unclear, ask the user.
2. Create .session_log.md in that directory with this structure:

# Session Log

## Session Info
- **Session ID:** `YYYYMMDD-HHMMSS` (local timezone)
- **Date:** YYYY-MM-DD
- **Start Time:** HH:MM
- **Working Directory:** `/absolute/path/to/dir`
- **Task Intent:** [What the user wants to accomplish — ask if unclear]
- **Skills/Tools Expected:** [List anticipated skills/tools]

## Progress Log

### [HH:MM] Session Started
- **Action:** Initialized session log
- **Context:** [Brief context of what triggered this work]

## Files Tracker
| Action | File Path | Timestamp | Notes |
|--------|-----------|-----------|-------|
| _No files tracked yet_ |

## Decisions Log
| # | Decision | Rationale | Timestamp | Alternatives Considered |
|---|----------|-----------|-----------|------------------------|
| _No decisions logged yet_ |

## Blockers & Issues
_None yet_

## Session Summary
_Session in progress..._

3. Announce to the user: "Session logging started. Log file: <path>/.session_log.md"

Ongoing Logging (Between start and end)

IMPORTANT: After /log start, you MUST actively log throughout the session without being asked. Specifically:

• Every file created, modified, or read → Add a row to the Files Tracker table
• Every significant decision → Add a row to the Decisions Log table
• Every skill invoked → Note it in the Progress Log
• Every error or blocker encountered → Add to Blockers & Issues

This happens automatically as part of your normal work — no extra user command needed. The /log update command is for explicit milestone checkpoints on top of this continuous tracking.

Command: /log update

What to do

1. Read the current .session_log.md from the working directory.
2. Append a new Progress Log entry with this format:

### [HH:MM] <Brief Title>
- **Action:** [What was just completed]
- **Files Changed:** [List files created/modified since last entry]
- **Key Decisions:** [Any decisions made, with rationale]
- **Status:** [in-progress / blocked / milestone-reached]
- **Notes:** [Any relevant context, errors encountered, workarounds applied]

3. Update the Files Tracker table with any new files not yet listed.
4. Update Decisions Log if new decisions were made.
5. If there are blockers, add them to the Blockers & Issues section.
6. Announce to the user: "Log updated at HH:MM — [brief summary of what was logged]"

When to use /log update

• Before and after complex debugging sessions
• When switching between sub-tasks
• When a major milestone is reached
• When encountering a blocker
• When making an important architectural/design decision

Command: /log end

What to do

Phase 1: Finalize the session log

1. Read the current .session_log.md.
2. Add final Progress Log entry:

### [HH:MM] Session Ended
- **Action:** Session finalized
- **Duration:** [calculated from start time]
- **Outcome:** [completed / partially-completed / blocked]

3. Fill in the Session Summary section:

## Session Summary
- **Duration:** X hours Y minutes
- **Start:** HH:MM → **End:** HH:MM
- **Outcome:** [completed / partially-completed / blocked]
- **What was accomplished:**
  - [Bullet list of completed work]
- **What remains:**
  - [Bullet list of pending items, if any]
- **Key outputs:**
  - [List of primary files/artifacts produced with absolute paths]

## Resume Prompt
> [A copy-paste-ready prompt that gives a future session full context to continue this work. Include: what was done, what's pending, key file paths, and any decisions that constrain next steps.]

Phase 2: Update Parent Index (SESSION_INDEX.md)

1. Read ~/your-workspace/session_logs/SESSION_INDEX.md (create if doesn't exist).
2. Prepend a new row to the index table (newest first):

| YYYY-MM-DD | HH:MM-HH:MM | Task description | `/absolute/path/.session_log.md` | completed/partial/blocked | Key output files |

3. If the index exceeds 200 rows, move the oldest entries to SESSION_INDEX_ARCHIVE.md.

Phase 3: Update Rolling Summary (RECENT_WORK.md)

1. Read ~/your-workspace/session_logs/RECENT_WORK.md (create if doesn't exist).
2. Prepend a 2-3 line summary of this session:

### YYYY-MM-DD HH:MM — [Task Title]
[2-3 sentences: what was done, key outputs, what's pending. Include absolute paths to key files.]

3. Prune to keep only the last ~20 sessions (delete oldest entries beyond 20). Target: under 100 lines.

Phase 4: Suggest Memory Updates

1. Analyze the session work and determine if any of these warrant memory updates:
   • New project context discovered (project memory)
   • New skill patterns or workflow improvements (feedback memory)
   • New external references encountered (reference memory)
   • User preferences revealed (user memory)
2. Present suggestions to the user in this format:

Suggested memory updates from this session:

1. [Type: project] "description of what to remember"
   → Would update/create: memory/filename.md

2. [Type: feedback] "description of what to remember"
   → Would update/create: memory/filename.md

Apply these? (yes/no/select numbers)

3. Only write memory files after user approval. Follow the standard memory format with frontmatter.
4. Announce to the user: "Session logged and indexed. Duration: X hours Y minutes."

Multi-Directory Sessions

If work spans multiple directories in a single session:

1. Create a .session_log.md in each directory where files are created/modified.
2. Each log tracks only the work relevant to that directory.
3. The first log created is the "primary" log — it contains the Session Info and full Decisions Log.
4. Secondary logs reference the primary: **Primary log:** /path/to/primary/.session_log.md
5. All logs are indexed in SESSION_INDEX.md (one row per log, same session ID).

SESSION_INDEX.md Format

# Session Index

Master index of all session logs. Newest first.

| Date | Time | Task | Log Path | Status | Key Outputs |
|------|------------|------|----------|--------|-------------|

RECENT_WORK.md Format

# Recent Work Summary

Rolling summary of the last ~20 sessions. Auto-pruned. For full history, see SESSION_INDEX.md.

---

### YYYY-MM-DD HH:MM — [Task Title]
[2-3 line summary with key file paths]

---

Timestamp Format

All timestamps use your local timezone in these formats:

• Session ID: YYYYMMDD-HHMMSS
• Log entries: HH:MM
• Index dates: YYYY-MM-DD
• Duration: X hours Y minutes or Xm for short sessions

To get current time, use: date '+%Y-%m-%d %H:%M:%S'

Tip: To set a specific timezone, configure your TZ environment variable (e.g., TZ='America/New_York', TZ='Europe/Berlin', TZ='Asia/Tokyo').

Edge Cases

• No /log start was called but user says /log end: Create a retroactive log by reviewing the current session's work, then proceed with the end workflow. Note in the log: "Retroactive log — session was not explicitly started."
• Session spans midnight: Use the start date for the session ID.
• Working directory has no files yet: Still create the log there; note in the intent what will be created.
• User switches task mid-session: Add a separator in the Progress Log: ### [HH:MM] --- Task Switch --- and update the task intent.

Example: Complete Session Log

# Session Log

## Session Info
- **Session ID:** `20260317-143022`
- **Date:** 2026-03-17
- **Start Time:** 14:30- **Working Directory:** `~/projects/example-grant-2026`
- **Task Intent:** Draft Example Grant application — Aim 2 methodology section
- **Skills/Tools Expected:** professional-word-doc, humanizer-2.2.0

## Progress Log

### [14:30] Session Started
- **Action:** Initialized session log
- **Context:** Continuing grant writing from 2026-03-15 session

### [14:45] Literature context gathered
- **Action:** Reviewed 3 papers on PBPK modeling approaches
- **Files Changed:** None (read-only)
- **Key Decisions:** Use population-based approach over individual PBPK
- **Status:** in-progress

### [15:20] Methodology draft completed
- **Action:** Wrote 1200-word methodology section
- **Files Changed:** aim2_methodology.docx (created), references.bib (updated)
- **Key Decisions:** Included CFD-DEM coupling justification per reviewer feedback
- **Status:** milestone-reached

### [16:00] Humanization pass done
- **Action:** Applied humanizer-2.2.0 two-pass audit
- **Files Changed:** aim2_methodology.docx (modified)
- **Status:** milestone-reached

### [16:15] Session Ended
- **Action:** Session finalized
- **Duration:** 1 hour 45 minutes
- **Outcome:** completed

## Files Tracker
| Action | File Path | Timestamp | Notes |
|--------|-----------|-----------|-------|
| Created | `~/projects/example-grant-2026/aim2_methodology.docx` | 15:20 | 1200 words |
| Modified | `~/projects/example-grant-2026/references.bib` | 15:20 | Added 3 refs |
| Modified | `~/projects/example-grant-2026/aim2_methodology.docx` | 16:00 | Humanized |

## Decisions Log
| # | Decision | Rationale | Timestamp | Alternatives Considered |
|---|----------|-----------|-----------|------------------------|
| 1 | Population-based PBPK over individual | Better statistical power for heterogeneous cohort | 14:45 | Individual PBPK, hybrid approach |
| 2 | Include CFD-DEM coupling justification | Reviewer 2 from previous submission flagged this | 15:20 | Brief mention only |

## Blockers & Issues
_None_

## Session Summary
- **Duration:** 1 hour 45 minutes
- **Start:** 14:30 → **End:** 16:15- **Outcome:** completed
- **What was accomplished:**
  - Drafted Aim 2 methodology section (1200 words)
  - Applied humanizer pass for natural writing style
  - Updated references
- **Key outputs:**
  - `~/projects/example-grant-2026/aim2_methodology.docx`

## Resume Prompt
> Continue grant writing. Aim 2 methodology is complete at `~/projects/example-grant-2026/aim2_methodology.docx`. Next: Aim 3 methodology section. Key constraint: must align with CFD-DEM coupling framework established in Aim 2. References at `references.bib` in same directory.