Working in this sandbox

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# Working in this sandbox

Instructions installed by the `dev-toolkit` kit. They apply to **every** session, whatever the project.

## Always start by reading the project memory

Before planning, before asking the user anything, before touching a file — check for a `.memory/` directory at the repository root:

```bash
ls .memory/ 2>/dev/null
```

**If it exists, read it before doing anything else:**

| Read | Why |
| --- | --- |
| `.memory/summary.md` | What the project is, its architecture, the decisions currently in force, the real build/test/run commands. |
| the tail of `.memory/history.md` | What has already been done, and why it was done that way. |
| the most recent file in `.memory/handoffs/` | Where the last session stopped: work in flight, next steps, blockers, traps. |

Then, before you propose anything:

- **Do not ask the user for information that is already recorded there.** Re-deriving state that is written down wastes the user's time and is the main reason this record exists.
- **Do not re-litigate a decision recorded in `summary.md`** without saying you are doing so and why. If you think a decision in force is wrong, say so explicitly and let the user decide.
- **Surface unfinished work.** If a handoff records work in flight, report it and ask whether to resume it or start something new — do not silently start something else on top of it.
- **Reuse the commands the memory documents.** Do not invent a parallel way to build or test a project that already has one.

If `.memory/` does not exist yet, carry on — you will create it when you write your handoff (see below).

## Always finish by updating the project memory

**Every session ends with all three files below brought up to date. No exceptions** — not for a one-line fix, not for a session that only read code, not for a session that failed to achieve anything.

You cannot detect the moment a session actually ends, so use this trigger instead: **do this as the last action before you hand control back, having finished or abandoned what the user asked for.** If the work then continues, extend what you already wrote instead of adding a second set of entries.

Two rules govern all three files. **Match the length to the work** — a one-line fix earns a few lines, not a filled-in template; padding with "N/A" makes the record unreadable, which is the one way this mandate defeats itself. And **record what the next person cannot re-derive** — where you stopped, what you tried that failed, the trap you hit, the decision still waiting on the user. Not a diff summary; git already has that.

### 1. `summary.md` — edit in place, never regenerate

- **Change only the parts your session actually establishes or invalidates.** Leave the rest byte-for-byte alone. You have seen a slice of this project; the file holds what every previous session established, and rewriting it wholesale from your slice silently destroys accurate content you never looked at. This is the single biggest risk in this whole mandate.
- **Only from what you verified** — a command you ran, a file you read. Never a plausible guess.
- **If nothing about the project's state changed, leave the file untouched.** That is what "update" means; it is not an exception to the mandate.
- What you could not check goes under an explicit `## Not yet established` heading. A summary that states unknowns as unknown is useful; one that states guesses as fact is worse than none, because the next session will trust it.

### 2. `history.md` — append exactly one entry

- One dated entry per session, appended at the end. **Never rewrite or delete an existing entry**, including your own from an earlier turn.
- Cover: what was asked, what changed, decisions made and alternatives rejected, tests, quality gate result, docs touched — dropping the lines that have no content.
- A read-only or failed session gets an entry too. One line stating that, and why, is a complete entry.

### 3. `handoffs/YYYY-MM-DD-<slug>.md` — write or update today's

- The slug names the topic. If a file for today already covers this topic, **update it**; if today's work is a different topic, write a new file under a different slug. Never overwrite another session's handoff.
- **A session that achieved nothing still gets a handoff**, and it is one of the valuable ones: it stops the next agent walking into the same wall.

### If `.memory/` does not exist

Create the whole skeleton — `README.md`, `summary.md`, `history.md`, and `handoffs/` with your handoff in it. All four, even if your session touched one file, so a later session finds a record to read and extend rather than a bare directory. `summary.md` is then written under the same rules as above: only what you verified, the rest under `## Not yet established`. `history.md` starts with its first dated entry: this session.

The full templates for all three files are in the `methodical-dev` skill (Phase 7). Use them as a menu, not a form to fill in.

## Keep the memory true

`.memory/` is **committed to the repository**, not gitignored. It only stays useful if it stays accurate, and the three files stay accurate in different ways: `summary.md` is a **snapshot** — it describes the present and carries no history. `history.md` and `handoffs/` are the **record** — they only ever grow, and are never tidied up, condensed, or corrected after the fact. A history you edit is not a history.

`.memory/` is for whoever *continues building* the project. `docs/` is for whoever *uses* it. Keep the two apart rather than duplicating content between them.

## Skills installed by this kit

Prefer these over doing the same work by hand:

| Skill | Use it for |
| --- | --- |
| `methodical-dev` | Any non-trivial change. Approval-gated: requirements → plan → implementation with tests → quality gate → EN+FR docs → `.memory/` update. Start here. |
| `quality` | Measuring code quality with qlty and refactoring until the gate passes. Never invoke qlty ad hoc instead. |
| `diataxis-doc` | Writing or restructuring documentation with the Diátaxis four-quadrant method. |


Never make a check pass by weakening it — no new `exclude_patterns`, no lowered thresholds, no disabled plugins, no deleted or skipped tests. Fix the code, or report that you could not.

The `quality` skill defines two narrow exceptions, both conditioned on evidence and on the user's agreement: excluding a vendored `kits/` directory (the measurement tool cannot measure itself), and removing a plugin proven to analyse nothing. Neither is a licence to trim a number — read the skill before invoking either, and never widen them.