Agent Log

Agent Log

Maintain .agents/log/ — a version-controlled journal of product and engineering decisions, tradeoffs, and directions, co-owned by the developer and agents. Entries capture why — the reasoning that code and git history cannot recover.

Layout

• .agents/log/index.md — index of all entries
• .agents/log/YYYY-MM-DD-slug.md — one entry per feature or standalone decision

Initialize .agents/log/ only when the user explicitly asks — by invoking this skill or directly requesting an agent log. If .agents/log/ is absent otherwise, do not create it, even when a plan is approved. When initializing, create .agents/log/index.md with the table header from Index Format; create an entry only if the current task records a decision.

Entry Format

---
title: Human-readable decision or feature title
date: YYYY-MM-DD
status: wip | done
related_paths:
  - src/feature-area/
  - src/shared/specific-file.ts
---

# Human-readable decision or feature title

## Background

Context needed to understand the problem. Link related entries as
[title](YYYY-MM-DD-other-entry.md).

## Problem

What is being solved and why now.

## Questions & Answers

Clarifying questions asked and the user's answers. Open questions stay
here until resolved.

## Decision

The chosen design. Concrete: file paths, type signatures, data shapes.
Mark examples with ✅ (do) and ❌ (don't) — the canonical notation for all
entries. Use Mermaid diagrams only when they clarify the decision.

## Tradeoffs & Alternatives

Rejected options and why. This section prevents re-litigating decisions
later.

## Implementation Plan

Phases or steps, when the entry starts as a plan draft.

## Verification

How success is checked, as a checklist:

- [ ] Tests, behaviors, or measurable criteria
- [ ] Manual checks that need a human

## Implementation Notes

Dated notes appended during and after implementation: deviations from
the plan, discoveries, test outcomes.

Make the level-one heading the first content after frontmatter and match its text exactly to the frontmatter title. Use only one level-one heading. Omit sections that have no content. Keep entries short and decision-focused — do not document what the code or git history already states.

Index Format

index.md holds a single markdown table:

| Date | Name | Status |
|---|---|---|
| 2026-07-07 | [Dark mode toggle](2026-07-07-dark-mode-toggle.md) | done |

Use the linked name as the short description. Keep paths, tradeoffs, and other details in the entry itself. Keep entries sorted newest first. Update the index whenever an entry is created, renamed, or its status changes.

Recall: Read Before You Write

Before drafting a plan or making non-trivial changes in a repo that has .agents/log/:

1. Read index.md.
2. Read entries whose related_paths overlap the files or areas being touched. If the index seems stale, grep entry frontmatter directly. Also grep entry bodies for 2-3 keywords from the request — path overlap alone misses cross-cutting decisions.
3. Surface relevant prior decisions to the user before asking clarifying questions — they may answer the questions or reshape the request.
4. Treat done entries as binding constraints unless the active conversation shows that the agent set the status without explicit user finalization; recover that lifecycle error under Done entries are frozen. Treat wip entries as current direction. When entries conflict, the newer one wins.
5. If the requested change contradicts an explicitly finalized done entry, surface the conflict to the user before proceeding. Resolution is a new entry recording the new decision and linking the old one, not a silent edit.
6. When answering questions about existing behavior or past decisions, cite the relevant entry by title and link.

Read index.md and matching entries with the agent's normal file-reading tool. When the log is large, narrow down which entries to read first:

rg -l "src/feature-area|src/shared/file.ts" .agents/log   # entries touching the paths being changed
rg -il "keyword1|keyword2" .agents/log                    # cross-cutting decisions by topic

Replace the placeholders with the touched paths and 2-3 keywords from the user request, then read the matching entries in full — do not rely on match snippets alone.

Write Workflow

1. Ask clarifying questions before implementation

Before drafting a plan or entry for a significant feature or architectural change:

• Run the recall steps above and surface relevant prior decisions first.
• Ask specific clarifying questions about scope, behavior, and tradeoffs that the request, the codebase, and prior entries do not already answer. Prefer 2-4 concrete options per question and mark a recommended one.
• Use the agent's structured question tool when available; otherwise ask a short numbered list in plain text.
• Wait for answers before designing. Record the questions and answers in the entry's Questions & Answers section.
• Do not manufacture questions for trivial scope — zero questions is fine when the request is already unambiguous.

2. Draft when a plan is approved

When the user approves a plan for a significant feature or architectural change, continue an existing wip entry for that feature. Create a draft entry as the first implementation step only when no same-feature entry exists — and only if .agents/log/ already exists or the user explicitly asked for an agent log. Otherwise skip the entry; plan approval alone never initializes the log.

• Name it YYYY-MM-DD-slug.md using today's date.
• Set status: wip and fill related_paths with the folders and files the plan touches.
• Seed the sections from the plan text; record clarifying questions and answers already given.
• Add it to index.md.

3. Update freely while WIP

While status: wip, the entry is a living document. Update it as decisions change, questions get answered, and the plan deviates. Keep related_paths in sync with where the work actually landed.

• Treat the entry as belonging to the feature, not to one prompt, turn, review round, or implementation pass.
• Continue the same entry across follow-up prompts, diff comments, fixes, and revised choices while the user is still working on the same feature.
• Treat the same thread, overlapping paths, and one continuing uncommitted diff as strong evidence of feature continuity. A thread may still contain multiple features when the user clearly starts a separate one.

4. Finalize when the feature is done

Finalize only when the user explicitly says the feature is finished or directly asks to finalize the entry.

• Do not infer finalization from passing tests, completing implementation, returning a final response, committing or merging code, or reaching the end of a turn.

• If the user appears to wrap up the feature without mentioning the log, ask once whether to finalize it. Keep it wip while waiting for the answer.

• Make sections reflect what was actually built; record final deviations and test outcomes in Implementation Notes.

• Check off Verification items that passed. Do not mark an entry done while items are unchecked — either verify them, or record in Implementation Notes that the user explicitly waived them.

• Set status: done and update index.md.

5. Done entries are frozen

A done entry is frozen only after explicit user finalization. Never edit an explicitly finalized entry. Later work that overrides it gets a new entry that links back to the old one.

If an agent set status: done without explicit user confirmation and the feature is still active, treat that as a lifecycle error: restore the entry and index status to wip, then continue the same entry. Do not create a compensating entry. Preserve user-authored content while correcting the status and continuing the living document.

Handling Feedback During Implementation

When uncertain which type it is, state your assumptions and ask.

Guidelines

• Log significant features, architectural changes, and directional decisions. Skip trivial fixes, refactors with no decision content, and routine chores.
• The developer edits entries too: never delete or rewrite user-authored content in an entry — append or ask.
• Keep one entry per user-defined feature or standalone decision. Do not split a feature by prompt, review turn, implementation pass, or revised choice.
• Continue the active wip entry for follow-up prompts on the same feature. Create a new entry only when the user clearly starts a separate feature or the work is an independent decision that can stand without the active feature. Ask when unclear.
• Do not put secrets, credentials, or private user data in entries.