Worklog

A worklog is a per-PR markdown file that records the notable decisions behind a change and the reasoning for them — the why this and not that, and the alternatives set aside, that the diff, the PR description, and the review thread don't keep. It is extracted from this session's record on disk, not written from memory: memory, especially after a compaction, loses exactly the decisions worth keeping. Produce one as you open the PR, keep it current through review, and commit it with the change.

When to use this skill — opt-in per project

Worklogs are off by default. Keep one only when the project asks for it — the repo's AGENTS.md / CLAUDE.md says worklogs are kept here, or the user asks. In a project that doesn't opt in, don't invoke this skill at all. Each repo keeps its own worklogs under its own .worklogs/ store, so the record travels with the code.

One worklog per branch of work

A worklog tracks a single branch of work — in practice, one per PR. Distinct streams of work each get their own worklog, even when they are related; the unit is the branch, not the feature or the ticket:

• Two unrelated PRs → two worklogs.
• Two PRs on the same issue → two worklogs — the issue isn't the unit.
• Two closely-related stacked PRs on one issue → still two worklogs, one per PR.

The test is not "is this the same feature or ticket?" but "is this a distinct branch of work, with its own diff and its own decisions?" If it has its own PR/branch, it gets its own worklog. Link sibling worklogs to each other through the related: frontmatter rather than merging them into one file.

When a single session produced work for more than one branch, scope each worklog to its branch's decisions — extract only what belongs to that change, and leave the rest for their own worklogs.