steid

docs: record how we actually work, not just what we build

CLAUDE.md captured conventions and gotchas but nothing about process, so
three things established by correction during milestones 2 and 3 lived only
in the conversation.

Plan the step, then execute it. A milestone-level sketch is not a step-level
plan, and answering a plan's open questions is not approval to start coding --
both of those were mistaken for a green light.

Decisions belong to the user: surface the choice and a recommendation rather
than picking a default, particularly for anything expensive to reverse. With
the corollary that unrequested scope should be proposed rather than added --
Repository::description went in unasked and had to be flagged afterwards.

Docs ship in the same commit as the code they describe. "Before reporting
work complete" was too loose; a separate docs: commit is the symptom, and it
happened twice.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

JamesPatrickGill authored 24 days agoparentbe4fac5Browse files5a2b113996494ad45a984ca69e9dc8df07e04b9e

1 file changed+24 −0

CLAUDE.md+24 −0View file

		@@ -45,6 +45,30 @@ Skip all of this for typos, formatting, and dependency bumps.
45	45	- Small steps. Build up slowly; prefer a working increment over a big drop.
46	46	- Explain why in commit messages, not just what.
47	47
	48	+### Plan the step, then execute it
	49	+
	50	+Milestones are planned in `current.md` as a list of steps. **Before executing a step,
	51	+lay out what it will contain — files, signatures, the tests worth writing, and any
	52	+decision inside it — and wait.** Then do that one step and stop.
	53	+
	54	+A milestone-level sketch is not a step-level plan. Answering the open questions in a
	55	+plan is not the same as approving the code; ask before starting.
	56	+
	57	+### Decisions belong to the user
	58	+
	59	+Surface a choice rather than picking a sensible-looking default, especially anything
	60	+expensive to reverse: URL shape, storage layout, visibility defaults, dependencies.
	61	+Give a recommendation and the trade-off, then let them decide.
	62	+
	63	+Corollary: don't add scope that wasn't asked for. If something seems obviously
	64	+needed, propose it. `Repository::description` was added unrequested and had to be
	65	+flagged after the fact.
	66	+
	67	+### Docs ship with the code
	68	+
	69	+Update `plans/` in the same commit as the change it describes, not a follow-up
	70	+`docs:` commit. This has slipped repeatedly; a separate commit is the symptom.
	71	+
48	72	## Conventions
49	73
50	74	Full detail in `plans/architecture.md`. The short version: