docs(process): the engineering log's single-file, newest-at-top layout makes every concurrent PR conflict

[dennisonbertram]

Work type

Feature slice

Change class

Infrastructure, CI, or process change

Why this matters

docs/logs/engineering-log.md is a single file whose newest entry goes at the top. Every PR that adds an entry therefore edits the same first line, so any two concurrent PRs conflict — not on content, but on position.

This session hit it four times in a row: #1421, #1425, #1427 and #1429 all needed a rebase whose only conflict was two entries competing for the top of the file. Each resolution was mechanical — keep both, order them, restore the blank line — and each cost a rebase, a force-push, and a fresh CI cycle.

CLAUDE.md actively encourages the conditions that produce this: it asks for small, scoped PRs that merge quickly, and notes that main moves fast with many concurrent squash-merges. The log's structure taxes exactly the workflow the repo wants.

The cost is not just time. A conflict that is always resolved the same way trains people to resolve it without reading, which is how a real conflict eventually gets flattened by reflex.

Protected path

Entry point: an agent or human finishing a unit of work appends an engineering-log entry, then opens a PR.

Current path that must keep working: entries are dated ## YYYY-MM-DD — Issue #N <title>, newest first, in one file; readers scan from the top for recent work; CLAUDE.md's Operational Reminder requires recording symptom, cause and fix for any solved blocker; docs/logs/long-term-thinking-log.md is a separate file and is not in scope.

Whatever replaces the current arrangement must keep the log readable as a chronological narrative — that is what makes it useful when someone is trying to understand why a decision was made.

Acceptance contract

1. Two PRs each adding an engineering-log entry on the same day do not conflict with each other.
2. The log remains readable in chronological order without assembling it by hand.
3. The convention is written down where the next contributor will find it, so entries do not drift back into one file.
4. Existing history is preserved and still findable — no entry is lost, and links or references to the current file keep resolving.
5. Whatever is chosen does not require a build step, a generator, or a tool that must be installed to read or write the log.

Current architecture and search evidence

• docs/logs/engineering-log.md — one file, newest entry inserted at the top, immediately under the # Engineering Log heading. That insertion point is the conflict.
• CLAUDE.md Operational Reminder — requires recording symptom, cause and fix in "the relevant durable log", and separately requires keeping docs/logs/long-term-thinking-log.md in sync. Neither names a file layout, so the convention lives only in the file's existing shape.
• CLAUDE.md Git & Merge Discipline — "Prefer small, scoped PRs that merge quickly" and "This repo's main moves fast (many concurrent squash-merged PRs)". The two guidances are in tension with the single-file log.

Evidence of frequency, this session alone: PRs #1421, #1425, #1427 and #1429 each rebased for this and no other reason. Four out of five PRs that touched the log.

Not yet searched, and should be before choosing: whether anything links to specific line ranges or anchors in engineering-log.md (docs, runbooks, issue bodies, code comments), since a split would break those. grep -rn "engineering-log" --include=*.md --include=*.go is the check.

Cross-surface impact map

Callers and data flow: documentation only. No code reads the log.

Config/env/defaults: none.

API/CLI/wire formats/tools: none, provided no generator is introduced. If a concatenation step were ever added it would become a build dependency — a reason to prefer a layout that needs none.

Persistence/schema/cache: none.

Concurrency/lifecycle: this is the point — the change is about concurrent writes to one file.

Security/auth/permissions/privacy: none.

TUI/web/macOS/other clients: none.

Provider/model/tool catalog: none.

Deployment/observability/runbooks: docs/runbooks/documentation-maintenance.md exists and may describe log conventions; it must be checked and updated if so.

Compatibility: any move or split breaks existing deep links to the file. Inbound references must be found first and updated, or a stub left behind.

Existing tests/fixtures: none — no test asserts on the log.

Documentation: CLAUDE.md (to state the convention), docs/runbooks/documentation-maintenance.md if it covers this, and the log itself.

Product and UX contract

None — reason: contributor-facing documentation layout with no user-visible surface. The experience being fixed is "adding a log entry should not require a rebase".

In scope

• Choose and implement a layout in which concurrent entries do not collide.
• Record the convention in CLAUDE.md so it holds.
• Preserve existing entries and any inbound references.

Options worth weighing, not a decision:

• One file per entry under docs/logs/engineering/YYYY-MM-DD-issue-NNNN.md, with the existing file becoming an index or being left as historical archive. No collisions at all, since two PRs never touch the same file. Costs the single-file scan.
• Append at the bottom rather than the top. A one-line change to the convention; conflicts become rare rather than certain, since git merges non-adjacent appends cleanly. Costs "newest first" readability.
• Per-month files (engineering-log-2026-09.md). Reduces but does not eliminate same-month collisions.

The trade-off is between eliminating collisions and keeping one scannable narrative. Worth deciding explicitly rather than drifting.

Out of scope

• docs/logs/long-term-thinking-log.md, which has the same shape but a much lower write rate. Revisit only if it starts conflicting.
• Rewriting or condensing existing entries.
• Any automated generator or lint that would need installing to write a log entry.

Coordination and dependencies

Should land when no other PR has an unmerged log entry in flight, or it will conflict with exactly the thing it is fixing. Worth announcing before merging.

Test-first plan

No automated test is appropriate — nothing asserts on the log, and a test that grepped for a filename pattern would pin the convention's letter rather than its purpose.

The check is a deliberate collision test, run before the PR is opened: create two throwaway branches from the same base, add an entry to each following the new convention, and merge both. If the second needs a manual resolution, the change has not achieved its purpose and the layout is wrong.

Control: also confirm the log is still readable in chronological order after the change, so a layout that eliminates conflicts by making the log unreadable is rejected rather than shipped.

Verification plan

• Run the two-branch collision test above and record the result.
• grep -rn "engineering-log" across the repo to find inbound references; confirm each still resolves.
• Confirm CLAUDE.md states the convention.
• Docs-only: no build or rebuild required, and the PR must say so explicitly rather than skipping it silently.

Rollout and rollback

Takes effect immediately on merge. Anyone with an in-flight log entry rebases once, which is the last time they should have to.

Rollback is reverting the commit; entries written under the new convention would need moving back, so the window for a cheap rollback is short. That argues for deciding the layout carefully rather than iterating on it in main.

Documentation and handoff

• CLAUDE.md: state where engineering-log entries go and why, so the convention survives.
• docs/runbooks/documentation-maintenance.md if it covers log conventions.
• An engineering-log entry recording the change — written under the new convention, which doubles as the first real use of it.

Definition of done

• Inbound references to engineering-log.md found and confirmed still resolving
• Layout chosen with the trade-off stated explicitly, not drifted into
• Two-branch collision test run and recorded as passing
• Log still readable chronologically without a tool
• Convention recorded in CLAUDE.md
• Existing entries preserved
• PR states no rebuild required