---
name: tracking-progress-on-disk
description: Maintain plan and task files in .claude/progress/ as work proceeds. Use at the start of any non-trivial task and continuously while working, to keep the plan and checklist in sync with reality.
---

# Tracking progress on disk

Work items and status live in `.claude/progress/`. This skill defines how to
keep them honest.

## At the start of a task

1. Read `.claude/progress/plan.md` and `.claude/progress/tasks.md`. If they do
   not exist yet, create them from the **Templates** at the end of this skill.
2. If the plan is empty or stale for this work, fill in Objective, Scope and
   Approach before writing code.
3. Break the work into concrete checklist items in `tasks.md`. Each item should
   be small enough to finish and verify in one sitting.

## While working

- **Tick a task the moment it is genuinely done** — not when started, not
  "mostly". A box is checked only after the work is verified.
- **Add tasks as they surface.** New work discovered mid-task goes into the
  checklist immediately, so nothing lives only in your head.
- **Move blocked items** to the Blocked section with the reason.
- Keep exactly one small set of items in `In progress` — avoid claiming many
  things are simultaneously underway.

## Recording decisions

When you make a non-obvious choice — a library, a trade-off, a scope cut —
append a dated entry to the `Decisions` section of `plan.md`. Do not rewrite
past entries; the log is append-only so the reasoning trail survives.

## Honesty rules

- A stale checklist is worse than no checklist. If reality and the files
  disagree, fix the files.
- Do not tick a box to look productive. Do not leave a finished task unticked.
- If scope changes, update `plan.md` Scope — do not silently drift.

These files are the single on-disk source of truth for what is done, what is
left, and why. Treat them as a contract with the next session.

## Templates

Create `.claude/progress/plan.md`:

```markdown
# Plan

## Objective

_What we are trying to achieve and why. One short paragraph._

## Scope

**In scope**
- _..._

**Out of scope**
- _..._

## Approach

_How we intend to get there — the shape of the solution, key steps._

## Decisions

> Append a dated entry every time a non-obvious choice is made. Do not edit
> past entries; add new ones.

- **YYYY-MM-DD** — _choice and the reason for it._

## Open questions / risks

- _..._
```

Create `.claude/progress/tasks.md`:

```markdown
# Tasks

## In progress

- [ ] _..._

## To do

- [ ] _..._

## Done

- [x] _..._

## Blocked

- [ ] _..._ — blocked by: _reason_
```