Stop starting over

In order. Each one answers a specific way work gets lost between sessions.

1. git init and /init

   A project with no git history has nothing to hand off. /init writes the first CLAUDE.md once there is something real to describe — code, or at minimum a scoped brief.

2. Install and run the updating-claude-md skill

   A working CLAUDE.md today, without learning to build the skill yourself yet. Using a skill is not the same as building one — that comes later, in Specialist 4.

3. CLAUDE.md as the hub, not the archive

   CLAUDE.md carries the gist and points at the file with the detail. Progress numbers and status-as-of blocks belong in the dev-doc they describe, not here.

4. docs/ shapes the idea, dev-docs/ records the build

   docs/ holds the brief and the scope as they stand today. dev-docs/ is the dated trail of what actually happened, including the parts that went wrong.

5. Naming sessions and one session, one job

   Brainstorming, researching and building are three different intents. Mixing them in one session is where decisions start getting lost.

6. The context gauge, compacting, restarting

   Watch the window fill. Hand off by updating the files before compacting forces the choice for you.

7. lessons.md

   The one file that turns a mistake into a rule instead of a repeat. Every entry here is something that actually happened.

We cover Skills — what they are, and where they live — in more depth on the Claude Skills page.

Open a fresh session against your own project and run this. Don't explain anything first — that's the point.

Then come back here and tick what the fresh session got wrong.

Our own result

We ran this prompt twice on the reference project. The first time, only the brief existed. The second time, after CLAUDE.md, the first dev-doc and a commit — with the session's own memory moved aside so it read like a teammate opening the repo cold.

During the reference project's Core 2 run, Claude answered “Saved” nine times after nine of the owner's decisions. It took three attempts to state what actually happened — the first two were wrong in different ways.

Owner: Nine of your replies started with 'Saved'. What was actually on
disk after each of them? Check git log and the file history, then write
the lesson.

Claude (first attempt): every "Saved" reply only wrote to my private
memory file — a folder outside this repo, never git-tracked.
[Wrong in a different way — fixed on the next check]

Owner: Closer, still not right. I read this session's tool log. From
12:21 to 12:23 every 'Saved' was a Write or Edit to
~/.claude/projects/-Users-.../memory/ — Claude Code's auto-memory on
this laptop, outside the repo.

The tool log settled it: every “Saved” had gone to Claude Code's own auto-memory on that one laptop — outside the repo, invisible to anyone else who opened it. The fix went into the lessons file, in one line that says exactly what happened instead of the word “Saved.”

### 2026-09-17 — "Saved" meant Claude Code's auto-memory on this laptop, not the repo
Every "Saved" reply from 12:21-12:23 wrote to
~/.claude/projects/-Users-.../memory/ (per-laptop auto-memory) —
docs/brief.md itself only got the Gaps section at 12:23 and the full
rewrite at 12:26.

“The work has to live in the repo, not in the person.”

Three files from the reference project after Core 2, simplified samples. Same project every module, further along.

1
---
2
last_updated: 2026-09-17T14:31
3
---
4
5
# CLAUDE.md
6
7
## Overview
8
9
Tool Scout, a fictional product-team example: one web page comparing
10
5 AI app builders on 4 fixed points, so the team can choose a tool
11
for its next prototype. No app code exists yet — the project is at the agreed-scope
12
stage.
13
14
## Key facts
15
16
- No app code yet. The repo holds docs/brief.md, dev-docs/, and this file.
17
- Planned build: a single HTML page that reads a sibling data.js file.
18
- Scope/plan/handoff docs follow a fixed dev-docs/ convention: flat
19
  dev-docs/, dated status filenames, lessons captured in
20
  dev-docs/lessons.md.
21
22
## Rules and gotchas
23
24
- The full agreed scope lives in docs/brief.md. Read it before
25
  changing anything; don't re-derive scope from memory.
26
- Facts must cite the tool's own public pages only, each with a link
27
  and a check date. If a tool's pages don't say, the cell reads "Not
28
  stated" — never a guess.
29
- Build-time rules (stale-fact flag, broken-file error handling, a
30
  consistency check between two columns) are recorded in the pt1
31
  dev-doc, not in docs/brief.md. They're deferred, not dropped.
32
- Don't start building without checking with the user first — as of
33
  the last planning session they said not to build yet.
34
35
## Where to look
36
37
- docs/brief.md — full scope: confirmed facts, assumptions, gaps,
38
  success criteria.
39
- dev-docs/2026_09_17-SCOPE-pt1-Comparison_Page.md — build-time
40
  decisions underneath the brief.
41
- dev-docs/lessons.md — durable, non-obvious lessons from past
42
  sessions.
43
44
## Active work
45
46
- pt1-Comparison_Page: decides how version one gets built — the
47
  repair option picked and why, build-time rules deferred out of the
48
  brief, the proposed build order, and the open shared-drive question.

1
---
2
status: SCOPE
3
date_created: 2026-09-17
4
---
5
6
# pt1: Comparison_Page
7
8
> Decides how version one of the competitor comparison page gets
9
> built: which repair option we picked and why, three build-time
10
> rules kept out of docs/brief.md, the proposed build order, and the
11
> still-open question of which shared drive hosts the page.
12
13
**Problem:** docs/brief.md holds the agreed WHAT — scope, points,
14
sourcing rules, trust rules, success criteria — but not the HOW.
15
16
**Evidence:** this session's conversation, docs/brief.md, and a
17
devil's-advocate review that produced 9 findings (F1–F9).
18
19
**Solution:** Option 2 picked as the build path. Four findings folded
20
into docs/brief.md as rules. Three findings (F4, F5, F6) kept out of
21
the brief on purpose — they're build details, not scope — and
22
recorded here for the build plan instead.
23
24
## Decisions
25
26
Picked: Option 2 — the page as already scoped, reading a sibling data
27
file, official sources only. Option 1 (a hand-filled table) is
28
throwaway and enforces nothing. Option 3 (added automation) breaks
29
the "no automation in version one" rule and needs a second reviewer
30
nobody's named yet.
31
32
### F4 — stale-fact flag
33
The page flags any fact whose check date is old enough not to trust
34
without a re-check. Threshold: 35 days, confirmed by the user.
35
36
### F5 — a broken data file shows an error, not a blank page
37
A clear on-page message when the data file fails to load, plus a
38
commented example entry to copy from.
39
40
### F6 — two columns can't contradict each other
41
If one column says a part is "Built in," the other column can't claim
42
the project is free to leave unless the tool's own pages say
43
otherwise.
44
45
### Build order (confirmed)
46
1. Pull the facts for points 1–3 from each tool's official pages.
47
2. Pull the facts for point 4 last, with extra care on sourcing.
48
3. Build the page to read from the data file.
49
4. User reviews before the team uses it.
50
51
## Lessons
52
53
See dev-docs/lessons.md.

1
# Lessons Learned — Tool Scout
2
3
### 2026-09-17 — "Saved" meant Claude Code's auto-memory on this laptop, not the repo
4
Every "Saved" reply from 12:21-12:23 wrote to per-laptop auto-memory —
5
docs/brief.md itself only got one section edit and one rewrite in that
6
whole window.
7
8
### 2026-09-17 — Don't bundle multiple asks into one table; one question per reply
9
A 5-item "give me these" table sent as a single reply broke the
10
one-question-max rule and needed a correction; switching to strict
11
one-question-at-a-time then closed 9 scope rounds with zero friction.
12
13
### 2026-09-17 — Use a script-loaded file, not JSON, for data a double-clicked local page must read
14
A page opened straight from disk can't fetch a sibling JSON file —
15
same-origin rules block it — but a script tag pointed at a sibling
16
file loads fine.

In enterprise teams the production repos sit under change control, so “just git init it” doesn't have an obvious home. Three real options, same as the org-wide version of this argument.

1. A separate repo in the same org

   Same admin boundary, same billing, but not under deployment change control. Usually the fastest to get approved, because nothing about production changes.

2. A repo outside the org entirely

   Clean separation if the org's access rules make even a second internal repo hard to get. Costs you a second place to remember to look.

3. docs/ and dev-docs/ inside the existing repo

   No new repo, no new approval. Works if the team can add plain-text folders without touching deploy paths or triggering the same review as code.

Three free files: a Claude skill that rewrites your project notes when a session ends, a filled-in example of the record it keeps, and a sample plan you can copy.

• The skill that keeps your project notes current

  A Claude skill, a trigger and the three lines that wire them up. When a session ends, your project notes are rewritten to match what actually changed.

  See what the skill writes when a session ends

  Project notes before it ran

  ## Active work

  None — no work records exist yet.

  The project had just gained its first work record, a plan and three decisions. None of it was in the notes, so the next session would have started by re-reading everything.

  After it ran

  CLAUDE.md, rewritten by the skill

  Marker moved · one line per open piece of work

  Active work

  dev-docs/2026_09_17-SCOPE-pt1-Comparison_Page.md: decides how version one of the comparison page gets built — the option picked and why, the rules kept out of the brief, the build order, and the open question about the shared drive.

  Where to look

  docs/brief.md — the agreed scope. dev-docs/ — the build decisions underneath it. lessons.md — what went wrong before.

  Rules it added

  Facts come from the tool's own pages only, each with a link and a check date. If a page does not say, the cell reads “Not stated” — never a guess.

  What it left out

  Progress percentages, status-of-today lines, and anything that belongs in the work record rather than the notes.

  Get it free

• A filled-in example of the work record

  The real folder from Tool Scout, simplified: one file per piece of work, its status in the file name, and the lessons kept beside it. Copy the shape by eye.

  See how a piece of work is usually recorded, and how the example records it

  How you'd usually record it

  A message in chat: “went with option 2, security column last, will pick the threshold later.”

  A note in a doc nobody opens again, and a task called “comparison page” that has been open for three weeks.

  Nothing says what was decided, where it stands, or what happens next — so the next session, or the next person, starts by asking you.

  With the example record

  One file per piece of work, status in its name

  2026_09_17-SCOPE-pt1-Comparison_Page.md

  The file name

  The date it started, the status (scoped, in progress, done), which part of the project it is, and what it is about — readable without opening anything.

  The top of the file

  The problem, the evidence behind it, and the decision taken. Three short blocks, not a wall.

  The progress log

  One dated entry per session: what changed, the proof, who owns the next move, what is blocking, what happens next.

  Beside it

  lessons.md — one line per thing that went wrong, so it does not go wrong twice.

  Get it free

• A sample plan you can copy

  What a plan has to say before anyone builds: the steps, what each one changes, and how you will know it worked.

  See how a plan is usually written, and how the sample writes it

  How you'd usually plan it

  1. Research the tools

  2. Build the page

  3. Ship it

  Every line is a wish. Nothing says which file changes, what counts as finished, or what is deliberately left out — so the build drifts and the review has nothing to check against.

  With the sample plan

  The same work, as a plan you can check

  12 small steps · each one provable

  Each step

  Names the file it changes and the one thing it does, small enough to finish and check in one go.

  Proof

  How you will know the step worked — stated before the work starts, not decided afterwards.

  Not doing

  What is deliberately out of scope, so the build does not quietly grow.

  Your steps

  The parts only a person can do are marked as yours, so nothing waits silently on you.

  Get it free