engineering-journal

name	engineering-journal
description	Use when starting or picking up a non-trivial effort (feature, investigation, perf probe, refactor, migration) in a shared repo where teammates or future agents must coordinate or hand off; when a repo has no durable in-tree record of decisions and dead-ends; when you're about to drop a well-measured negative result; or when bootstrapping a journal from a repo's commit history.

Engineering Journal

Overview

An engineering journal is an in-repo markdown record of efforts — what you set out to do, the decision to proceed or not, what happened, and what was learned. It lives in the tree (docs/journal/ or the repo's docs dir), lands on main via PR, and is grounded in code (real commits, files, specs).

Core principle: an effort's record is a deliverable, landed alongside the code — not a closed issue, not notes in your head. A well-measured dead-end is the most valuable entry: an unrecorded NO-GO is the one the team re-pays to rediscover.

When to use

• Starting a non-trivial effort a teammate or future agent might need to understand or continue.
• Picking up someone's in-progress work — read their entry to continue.
• A repo with no decision/dead-end record — establish the journal as the convention.
• Bootstrapping from a repo's commit history (retrospective mode, below).

Not for trivial one-liners.

Journal vs. issues (use both)

Issues/PRs are the task layer — discrete units, assignment, notifications. The journal is the narrative/decision layer — why, the dead-ends, current state, how to continue. It must be in-repo: versioned with the code, greppable, code-grounded, and readable by the next agent without leaving the tree. Link the journal to issues/PRs; don't let an issue be the only record of a non-trivial effort.

The lifecycle (per effort)

1. Pick & scope. Gather requirements. Grep the journal + git log for prior art first — don't re-litigate a settled question.
2. Open — land intent on main. Write the entry: goal/hypothesis, requirements, GO/NO-GO criteria (number-gated where possible), plan. Commit via PR to main so the effort is visible before you build. This is the coordination move. If the entry names deferred/reopen items, mirror them into docs/backlog.md in the same commit (see "Keep the backlog in sync").
3. Go / no-go. Probe or price it cheaply before building. Record the verdict honestly.
4. Implement & test.
5. Close out — in the implementing PR. Update the entry with the outcome (shipped / NO-GO + numbers + mechanism) and update any docs the change affects. Reconcile docs/backlog.md: add any new deferred items this effort leaves behind, and remove or mark done every backlog item this landing completes or deprecates — in the same PR. Landing the work closes the record.

A NO-GO closes out the same way: land the negative result with its mechanism and a reopen condition ("revisit if new hardware / data / regime"). Merge negative probes; don't abandon them.

Ground every claim in code

The journal's authority is that it traces to source: real commit SHAs, PR numbers, source-code paths (src/…, crates/…), measured numbers — never invented figures, and never a transient design/spec doc that may be deleted (absorb its content instead — see below). When you update or reconstruct an entry, re-verify against current code; stale claims are the main failure mode. If a detail isn't in the source, say so or omit it.

Absorb the design doc — the entry is self-contained

An effort's design often starts life as a separate spec/plan/brainstorm doc (from a planning skill, an ad-hoc docs/design/ or scratch location). Do not leave that doc beside the journal and link to it: parallel records drift, and a scratch doc that later gets deleted turns the journal's links into dangling references.

When you journal an effort, lift the design doc's durable content — the goal, the decisions and their rationale, the GO/NO-GO, the dead-ends — into the journal entry itself, then remove the consumed spec/plan doc in the same PR. The entry becomes the design record (as this skill's own entries do). A useful check: after writing, grep the entry for any path you are about to delete — if a fact only lives behind such a reference, lift it inline; then the reference goes. The entry must read completely on its own, citing only things that persist (SHAs, PRs, code paths).

Sampler efforts carry a measured overhead number

If the effort adds or changes a sampler — or changes core code that affects samplers — the GO/NO-GO criteria and the close-out MUST carry the measured per-refresh overhead (µs at fleet-representative scale, from the agent's sampling latency debug line), never "bounded"/"low"/"negligible". If the refresh reads a non-mmap source (sysfs device command, ioctl, SMI/library call, page-table walk), also record the cadence decision (throttle to the sampler's own interval + dispatch off the sample cycle). This is where "measured numbers" above is non-negotiable, and it is most dangerous for a legitimate sysfs/procfs exception, where no cost alarm fires for you — an unmeasured overhead claim there is not a GO. See docs/principles.md principles 13, 16, 17. For the full pass, use the reviewing-samplers skill.

Honest-ledger voice

Factual, not diaristic or triumphant. NO-GOs and falsifications are first-class, with their mechanism. Flag what you couldn't measure. Don't overclaim — the record is trusted only if it's honest about what didn't work and what's uncertain.

Retrospective mode (bootstrap)

For a repo without a journal: cluster the commit history into thematic arcs/campaigns, write one grounded entry per arc from its commit range + design docs + notes (one drafter per arc parallelizes well), and add a series index. Same grounding and voice rules — lift the design docs' key decisions into the entries and remove the consumed docs (see "Absorb the design doc"); the entries, not the scratch docs, are the record.

Keep the backlog in sync

docs/backlog.md is the repo's consolidated backlog — the ordering layer over the work. Most items are the journal's deferred/reopen items mirrored here, each tracing back to the journal entry that owns its "why" and mechanism (it may also carry net-new follow-ups/capability requests not yet tied to an effort — those cite their own origin). The journal-derived portion is not a second source of truth; because it is derived it goes stale unless updated with the journal, so treat it as part of every journal change:

• Adding an entry (open or retrospective) whose Deferred/Reopen/limitations section lists items → add those items to docs/backlog.md, each linking its source entry and carrying its reopen condition.
• Updating an entry — new deferred items, or a resolved one → mirror the change in the backlog (add / edit / drop).
• Landing work that completes or deprecates a backlog item → remove it (or mark it done with the PR that closed it) in the same PR. A backlog that still lists shipped work is worse than none — it sends people to re-do or re-litigate finished efforts.

Keep items grounded (link the entry, cite code paths / PRs), and mark state (Open / Roadmap / By-design) rather than deleting the reasoning. If the repo has a dedicated backlog/roadmap skill, defer ordering and prioritization to it; this skill still keeps docs/backlog.md consistent with the journal.

Optional: publish as docs

The journal can feed a doc site in whatever the repo already uses (mdBook, another SSG, plain markdown, the repo's existing docs) — don't impose a toolchain. Journals stay source-of-truth; the site consumes them. A concrete worked example (private-by-construction mdBook with a build + link-check gate) and reusable scripts are in publishing-example.md.

Related

The journal records a single effort; docs/backlog.md (see "Keep the backlog in sync") is the consolidated index of their deferred/reopen items, kept in step with the journal by this skill. Prioritizing which effort to pick next is a separate concern — defer it to a dedicated backlog/roadmap skill if the repo has one.

Common rationalizations

Rationalization	Reality
"No journal convention here; I won't invent one for one item."	The journal is the convention — establish it once. It compounds; every entry saves the next person from re-deriving.
"A GitHub issue is enough."	Issues aren't versioned with the code, aren't greppable in-repo, aren't code-grounded, and the next agent won't find them. The record belongs in the tree.
"I'll keep scratch notes in my head."	Then the reasoning is lost at handoff. The journal is where the reasoning lives.
"It's a dead end — nothing to record."	The dead-end is the highest-value entry. Record the mechanism and the reopen condition.
"I'll write it up after it ships."	Land the record in the same PR. "After" = never, or an unverified reconstruction.
"Close enough on the numbers."	Ground every figure in a source or omit it. Invented numbers destroy the record's authority.
"The sampler refresh is a small sysfs read — obviously cheap."	Cheap is a measured number. drivehealth's "small sysfs read" was ~83 ms/refresh (an ATA command per drive). A legitimate principle-15 exception is exactly where no cost alarm fires — measure it.
"The spec doc already says all this — I'll just link it."	A separate spec drifts from the code and dangles when the doc is deleted. Lift its decisions into the entry and remove the doc; the entry is the design record.

Red flags — stop

• About to implement without landing intent for coordination.
• Recording an outcome you didn't verify against code.
• Dropping a negative result instead of landing it.
• Reaching for a GitHub issue as the only record of a non-trivial effort.
• Writing "bounded" / "low overhead" in a sampler effort's GO criteria or close-out with no measured µs number behind it.
• Leaving a separate spec/plan/scratch doc beside the entry and linking to it, instead of lifting its content in and removing it — especially a doc slated for deletion (the link will dangle).
• Landing work that finishes or deprecates a backlog item without removing it from docs/backlog.md, or adding a journal entry's deferred items without mirroring them into the backlog.