Diary

An implementation diary captures the narrative of your work: what you did, why, what worked, what broke, what was tricky, and what needs review. The concept of "diary" activates existing behavioral patterns without requiring much engineering -- the model already knows what a diary is.

Working Loop

Follow this cycle for each meaningful unit of progress:

Implement -- make the code change
Update diary -- add or update the current step in the diary file
Commit -- commit the code and diary together

A "step" is a logical chunk of work, not necessarily a single commit. Examples: "wire up the API endpoint", "debug the flaky test", "research how the auth middleware works".

File Location

Diary files live at docs/diary/YYYY-MM-DD-<slug>.md relative to the project root.

The date is when work on the task started
The slug is free-form: a feature name, ticket reference, or whatever describes the task
One file per task or feature -- if work spans multiple days, steps accumulate in the same file
Create the docs/diary/ directory if it doesn't exist

Examples:

docs/diary/2026-03-25-add-diary-skill.md
docs/diary/2026-03-20-fix-auth-race-condition.md
docs/diary/2026-03-18-PROJ-123.md

Diary File Structure

# Diary: <task description>

Brief description of the goal and context for this task.

## Step 1: <short description>

**Author:** <agent name -- "main" if written by the main agent, otherwise the sub-agent name>

### Prompt Context

**Verbatim prompt:** <the exact user prompt that initiated this step>
**Interpretation:** <what the assistant understood from the prompt>
**Inferred intent:** <the underlying goal behind the prompt>

### What I did
<factual description of actions taken, files touched, commands run>

### Why
<connects the actions to the goal>

### What worked
<positive signals worth replicating>

### What didn't work
<failures recorded immediately with verbatim errors and commands>

### What I learned
<tacit knowledge that isn't obvious from the code>

### What was tricky
<friction points, hidden complexity, sharp edges>

### What warrants review
<tells a reviewer where to look and how to validate>

### Future work
<implied follow-ups that naturally fell out of the work, not a wishlist>

## Step 2: <short description>

...

Writing Rules

Prose-first. The diary is a narrative, not a log dump. Technical details (paths, hashes, error messages) are included inline but wrapped in readable prose.
All sections, every step. Never skip a section. If "What didn't work" is genuinely empty because everything went smoothly, say that explicitly.
Failures are gold. Record them immediately with verbatim error messages and the exact commands that produced them. These are the most valuable parts of the diary.
Absolute paths from project root. All file paths referenced in the diary are absolute relative to the project root (e.g., /src/handler.go).
Prompt Context is verbatim. Copy the user's prompt exactly as given. Don't paraphrase the verbatim section.
Identify authorship. Put a **Author:** line right under each step heading you write so it's obvious who wrote it -- your sub-agent name if you're a named sub-agent, or main if you're the main agent.
Don't modify old diary entries. Only edit a diary file if it was created in the current session. Subsequent work should create a new diary file rather than revising earlier entries -- diaries are a historical narrative, not a living document.

When to Activate

This skill activates proactively during non-trivial implementation work:

New features
Bug fixes
Refactors
Research spikes

Do not activate for:

One-line fixes
Config tweaks
Quick questions about the codebase
Trivial changes that don't warrant narration