Operation logger

Operation Logger

Persistent step-by-step operation recording for long conversations and complex tasks.

Why This Skill Exists

Context windows are limited. In long conversations, earlier operations get compressed or dropped entirely. This creates a dangerous pattern: Claude forgets what it already tried, repeats failed approaches, loses track of modified files, and makes decisions that contradict earlier ones.

This skill solves that by treating the filesystem as persistent memory. Every meaningful operation gets recorded in operation-log.md — a single, chronological document that serves as the complete history of what happened, why, and what the outcome was.

Think of it this way:

• Context window = short-term memory (volatile, limited)
• operation-log.md = long-term memory (persistent, unlimited)

The log isn't just a record — it's a tool. Re-reading it before decisions keeps the full picture in your attention window, even after context compression has stripped away the details.

FIRST: Check for Existing Log

Before anything else, check if operation-log.md already exists in the project directory:

1. If it exists: Read it immediately to restore context from a previous session. Then continue logging from where it left off — add a new session header and keep going.
2. If it doesn't exist: Create it using the template (see below).

This is how cross-session continuity works. The log file IS the memory.

When to Create the Log

Create operation-log.md at the start of any task that will involve 3+ tool calls. Don't wait — if in doubt, create it. A log you didn't need costs nothing; a log you needed but didn't create costs everything.

Specific triggers:

• Multi-step implementations (new features, refactors)
• Debugging sessions
• Multi-file modifications
• Research or exploration tasks
• Any task where the user says "this might take a while" or similar
• When the user explicitly asks to track/log operations

Where the Log Goes

Always create operation-log.md in the project root directory (the current working directory). Never create it in the skill's installation folder.

Version control note: The operation-log.md is a working file, not source code. Consider adding it to .gitignore if you don't want it tracked. Some teams prefer to keep it for audit trails — use your judgment.

Opt-Out

If the user says "don't log this", "skip the log", or otherwise indicates they don't want logging for a task, respect that and skip log creation. The skill is a tool, not a mandate.

The Log Format

The log has three sections that work together:

1. Running Summary (top of file)

A live-updated summary that answers: "What's the current state?" This gets updated every 5 operations or whenever something significant changes. It should be short — 5-10 lines max — so re-reading it is fast.

2. Session Entries

Each session (conversation) gets its own header with a timestamp. Within a session, operations are logged chronologically.

3. Operation Entries

Each operation entry follows this format:

#### [OP-NNN] Operation Type | Brief Description
- **Time**: HH:MM (optional — include when available)
- **Action**: What was done (1-2 sentences)
- **Result**: What happened (success/failure/partial, key output)
- **Files**: Files created, modified, or read (if any)
- **Context**: Why this was done / what it connects to (if not obvious)

Keep entries concise but complete. The goal is that someone reading only the log can understand the full history of the task. Don't write paragraphs — write clear, scannable bullet points.

Operation Types

Categorize each operation to make the log scannable:

Type	Use When
SEARCH	Searching for files, code patterns, or information
READ	Reading/examining files or documentation
EDIT	Modifying existing files
CREATE	Creating new files
DELETE	Removing files or code
TEST	Running tests or verification
BUILD	Building, compiling, or bundling
COMMAND	Running shell commands
DECISION	Making a design or implementation choice
ERROR	Encountering and diagnosing errors
FIX	Resolving an error or bug
RESEARCH	Web searches, API exploration, doc reading
PLAN	Planning next steps or revising approach
REVIEW	Reviewing code or outputs

The Core Rules

Rule 1: Log After Every Meaningful Operation

After completing any tool call that changes state or produces important information, append a log entry. "Meaningful" means:

• Any file edit, creation, or deletion
• Any test or build run
• Any search that yielded useful results
• Any decision point
• Any error encountered

You do NOT need to log:

• Re-reading the log file itself
• Trivial reads that produced nothing useful
• Intermediate thinking steps with no output

Rule 2: Update the Running Summary Every 5 Operations

After every 5th operation entry (OP-005, OP-010, OP-015...), update the Running Summary at the top. The summary should reflect:

• Current task state
• Key files modified so far
• Any open issues or blockers
• What comes next

Rule 3: Re-read Before Major Decisions

Before making any significant decision (choosing an approach, starting a new phase, handling an error), re-read the Running Summary. This takes seconds but prevents contradictions with earlier work.

Rule 4: Log Errors with Full Context

When an error occurs, log:

• The exact error message (or key parts)
• What was attempted
• The diagnosis
• The resolution (or "unresolved" if moving on)

This prevents the deadly pattern of retrying the same failed approach after context compression drops the memory of the failure.

Rule 5: Mark Decision Points Explicitly

When making a choice between alternatives, log it as a DECISION entry with the rationale. Future-you (or the user reviewing the log) needs to know not just what was chosen but why.

#### [OP-012] DECISION | Use REST API instead of GraphQL
- **Action**: Chose REST over GraphQL for the data layer
- **Result**: Decision made
- **Context**: GraphQL would require additional dependencies (apollo-server),
  and the data model is simple enough that REST endpoints are clearer.
  The user mentioned wanting to keep dependencies minimal.

Rule 6: Session Continuity

When resuming from an existing log:

1. Read the full log (or at least the Running Summary + last 10 operations)
2. Add a new session header: ## Session: [DATE] (Resumed)
3. Log a PLAN entry summarizing what you understand from the previous session
4. Continue operation numbering from where it left off

Log Template

Use templates/operation-log.md as the starting template. Copy it to the project root and fill in the task description.

Practical Tips

Keep It Lean

The log should be detailed enough to reconstruct context, but not so verbose that re-reading it is slow. A good operation entry is 3-5 lines. If you need more detail, that detail probably belongs in a separate findings file.

Batch Rapid Operations

If you do 3 quick file reads in a row to understand a module, you can batch them into one entry:

#### [OP-007] READ | Examined auth module structure
- **Action**: Read auth/login.ts, auth/middleware.ts, auth/types.ts
- **Result**: Auth uses JWT with refresh tokens, middleware checks on every route
- **Files**: auth/login.ts, auth/middleware.ts, auth/types.ts (read)
- **Context**: Understanding auth before modifying the session handling

Use the Log as a Communication Tool

The log isn't just for Claude's memory — it's also useful for the user. They can review operation-log.md at any time to see exactly what was done, in what order, and why. Write entries as if another developer will read them.

Cross-reference with Other Planning Tools

If you're also using task_plan.md (from planning-with-files) or todo tasks, the operation log complements them. The plan says what to do, the log says what was done. Reference plan phases in your log entries when relevant.

When to Stop Logging

Stop logging when:

• The task is complete and the user has confirmed
• The user explicitly asks you to stop
• The task turned out to be trivial (< 3 operations)

Before stopping, add a final summary entry:

#### [OP-NNN] REVIEW | Task Complete
- **Action**: Final review of all work performed
- **Result**: [Summary of what was accomplished]
- **Files**: [All files created/modified during the session]
- **Context**: Task completed successfully / with notes: [any caveats]

Integration with Other Skills

This skill works alongside other skills, not instead of them:

Skill	Role	How They Connect
planning-with-files	Plans what to do	Operation log records what was actually done
systematic-debugging	Guides debug approach	Operation log records each debug step and finding
test-driven-development	Guides test workflow	Operation log records test results and iterations
brainstorming	Explores ideas	Operation log records which ideas were explored/chosen

Anti-Patterns

Don't	Do Instead
Skip logging "just this once"	Log it — the one you skip is the one you'll need
Write multi-paragraph entries	Keep entries to 3-5 concise lines
Log only successes	Errors and failures are the most valuable log entries
Forget to update the summary	Every 5 ops, refresh the running summary
Create the log mid-task	Create it at the start, before the first operation
Put external/untrusted content in the log	Summarize external content; put raw data in separate files
Stop logging when things get complex	That's exactly when logging matters most

Reference Files

• templates/operation-log.md — Ready-to-use log template
• references/best-practices.md — Advanced patterns and tips
• references/examples.md — Real-world log examples