Claude Code First, specification version 0.1.0. The plain-language guide

Version 0.1.0. Grade R2/S3.

F106 Shipping deletes a task's rationale, and what only the rationale held was lost with it

Claim

Because shipping a task deletes its rationale section, two kinds of knowledge written only there were lost on ship: that the design had been wrong, and a block's definition of done, whose loss let a block be declared closed and reopened six times.

Mechanism

The rationale file holds reasons for unshipped work only, so the ship verb removes a task's section in the same write that adds its ledger line. The ledger line is one sentence about the outcome. Anything the section held that outlives the task, such as a lesson about the design or a condition for a whole block, disappears from the planning files and survives only in history, where no later session looks before deciding.

Observations

• roadkeep. The rule is "When a section ships, delete it here." [roadkeep@91754240:docs/IMPROVEMENTS.md#L5]

On 2026-08-05 RK310 recorded two design sections found wrong on implementation, after which ship "then deleted the section with no trace that its reasoning had" [roadkeep@402ef7fc:docs/IMPROVEMENTS.md#L114] been wrong; the remedy makes the ledger sentence record what the design was wrong about [roadkeep@91754240:docs/CHANGELOG.md#L130]. Two weeks later RK1265 recorded that a block in a "repository using this tool carried 131 recorded entries and was declared closed and reopened" [roadkeep@91754240:src/roadkeep/criteria.py#L8] "six times, every close a count reaching zero" [roadkeep@91754240:src/roadkeep/criteria.py#L9], because its definition of done had been written in a rationale section that ship deleted: "Zero occurrences survive" [roadkeep@91754240:src/roadkeep/criteria.py#L11]. The remedy is "a list a ship never deletes" [roadkeep@a5f919c6].

• polyweave. The behaviour holds at the pin: the 26 rationale sections

(git grep -c '^### §PW' 6d1c136 -- docs/IMPROVEMENTS.md) are exactly the 18 open and 8 deferred lines by id [polyweave@6d1c136:docs/IMPROVEMENTS.md], and ship diffs delete the section [polyweave@7024e7e]. Where a design proved wrong, polyweave kept the lesson in the commit body instead, the line having "had its why amended and its design rewritten" [polyweave@f203b0a]. This is the tool's behaviour seen again, not a second loss.

• winwright. It adopted the done-when criteria on its first day with roadkeep's reason,

"A definition of done written into a rationale section is one" [winwright@861b82e:.claude/skills/roadmap-docs/SKILL.md#L124] that ship correctly deletes, and extended it with a test pairing each criterion with the case that demonstrates it [winwright@b26f7d7]. No winwright block is recorded as reopened.

Independence

One origin, the tool (rule 3): both losses are consequences of roadkeep's ship verb and are recorded in roadkeep's own sources, and winwright's criteria are a copy of the remedy (rule 2). The two losses are separate occasions, two weeks apart, of different content, the second after the first had been remedied; that is recurrence within one origin. The repositories in which the design sections and the reopened block were measured are not named, so they are not counted as further origins.

Counter-evidence

Deleting shipped rationale is also what keeps the file small, which is the purpose stated for it; the sources record no cost of the alternative because it was not tried. The reasons are not destroyed: history holds every deleted section, and this study reads roadkeep's incidents from the rationale file at the commits that filed them. The loss is of the reasons' place in the files a session reads, not of the reasons.

Grade

R2: two separate occasions of one tool's behaviour. S3: the source counts the second one (131 entries, six reopenings) and the first (two sections in one block of eleven tasks). Not S4: the remedies are a ledger sentence and a separate list, and no check that fails when knowledge is lost on ship is seen to fail.