---
name: worklog
description: Create comprehensive structured markdown worklogs documenting work sessions in docs/worklogs/. Use when the user explicitly asks to document work, create/write a worklog, log the session, or record what was accomplished.
---

# Worklog Skill

Create comprehensive structured worklogs that document work sessions with rich context for future reference.

**Skill directory:** `~/.claude/skills/worklog/` (contains scripts/, assets/)

## When to Use

Invoke this skill when the user requests:
- "Document today's work"
- "Create a worklog"
- "Record this session"
- "Write up what we accomplished"
- "Log this work session"

## Context Gathering

Before writing the worklog, run the metrics script to gather git context:

```bash
scripts/extract-metrics.sh
```

This outputs: branch, uncommitted changes, commits today, files touched, lines added/removed, and recent commit messages.

## File Location

Save worklogs to: `docs/worklogs/YYYY-MM-DD-{descriptive-topic-kebab-case}.md`

Create the `docs/worklogs/` directory if it doesn't exist.

Use the helper script to suggest the filename:
```bash
scripts/suggest-filename.sh
```

## Structure

Read and follow the template: `assets/worklog-template.md`

The template defines all required sections. Parse it directly rather than relying on this summary.

## Helper Scripts

**Suggest Filename:**
```bash
scripts/suggest-filename.sh
```
Analyzes recent commits to suggest a descriptive filename

**Find Related Logs:**
```bash
scripts/find-related-logs.sh "keyword1 keyword2"
```
Searches previous worklogs for context continuity

## Principles

1. **Be thorough** - More information is better; these logs can be distilled later
2. **Document the journey** - Include false starts, debugging, and the path to the solution
3. **Focus on why** - Decisions, rationale, and context matter more than what
4. **Include specifics** - Code snippets, commands, error messages help reconstruct solutions
5. **Think ahead** - What would you need to know in 6 months?
6. **Pull previous context** - Use find-related-logs for continuity across sessions
7. **Aim for 3-5KB minimum** - Thorough logs typically run 5-15KB

## Process

1. Run `scripts/extract-metrics.sh` to gather git context
2. Run `scripts/suggest-filename.sh` to get filename suggestion
3. Read the complete template from `assets/worklog-template.md`
4. Search for related previous worklogs using the find-related-logs script
5. Fill in all template sections with detailed information from the session
6. Ensure the `docs/worklogs/` directory exists (create if needed)
7. Save the worklog with the suggested filename
8. Verify metadata frontmatter is complete

## Requirements

- Must be in a git repository
- Saves to `docs/worklogs/` directory (will create if needed)
- Outputs markdown format with YAML frontmatter
- Requires helper scripts in `scripts/`
