The Work That Writes Itself

There is a specific decay that only happens to small engineering teams who are trying. The team is shipping. The team is making real architectural choices, finding real bugs, having real arguments about the right shape of a system. But six weeks later, almost none of that is legible to anyone who wasn’t sitting in the chair when the work happened.

The code merged. The decisions are buried in PR threads that nobody re-reads. The reasoning is in compacted agent sessions that no longer exist. The “we’ll write this up later” doc is still empty. Somebody asks at standup, “what changed in the auth model last month?” and the answer is a slow scroll back through commit messages until somebody recognizes a SHA.

This is not a documentation problem in the usual sense. It is what happens when ordinary engineering tooling — git, PRs, chat, ticket trackers — captures artifacts well and reasoning badly. The reasoning rots structurally because the tools we already use weren’t designed to hold it.

This cairn is about Conduit, the system we built to fix that for our team. The next two cairns get into how it’s shaped and how it runs. This one is about why it exists and what it actually changes about the day-to-day.

What was already in place, and why it wasn’t enough

We were not starting from scratch. The team already used Timbers, a development ledger CLI that captures what, why, and how as structured entries inside each repo, right when the work happens. Timbers is excellent at what it does: it preserves the reasoning that ordinary commit messages let evaporate.

But timbers is per-repo, terse, and structured. Reading a timbers ledger is a great experience for somebody already deep in that codebase. It is a much worse experience for somebody asking, “what has the team been up to this month?” or “did we ever decide how multi-tenant auth was going to work?” The signal is there, but it lives in JSON files, in three different repositories, in commit-anchored entries that don’t connect to each other or read like a story.

A second-order problem stacks on top of the first. Once you have any programmatic capture of reasoning per project, the natural next move is to aggregate. But aggregation alone is not enough. You also need the result to read like prose a human can actually consume. Bullet lists of decisions across repos are not it.

The shape of the gap, in one sentence: we needed something that could turn a week of timbers entries across multiple repos into a small set of well-formed artifacts that a human would happily skim.

What Conduit is, in one paragraph

Conduit is a static knowledge site that ingests bundles of LLM-drafted artifacts produced by per-project publishers running in CI. Each project repo carries a tiny configuration (a state file, a project file, two workflow YAMLs) and calls a shared GitHub Action that handles drafting, dispatching, and persisting state. The Conduit site itself runs on Eleventy and Cloudflare Pages, with Pagefind doing search.The static-site choice is deliberate. The artifacts are immutable once produced; everything is build-time rendering with client-side search. No runtime services, no databases, no auth-anchored read paths.

If that sentence felt dense, the next section unpacks it. The minimum mental model is: the work happens in project repos as it always did, and a separate site quietly accumulates a readable record without anybody needing to write anything by hand.

Four artifact types, deliberately distinct

Conduit publishes four kinds of artifact, each with a distinct job. They are not interchangeable, and that turns out to matter.

Devblog. A weekly-ish narrative post in the voice of the team — the story of recent work. What got tried, what hurt, what surprised us. One person’s voice, but written from the team’s actual movements. Reads like a blog post; isn’t optimized for reference.

ADR (Architecture Decision Record). A structured record of an architectural decision — context, options, decision, consequences. ADRs are reference material, not narrative. They earn their slot in the system only when a real fork in the road was navigated.

Sprint report. A periodic summary of what shipped, what’s in flight, and what’s coming. Operational, not narrative. The closest thing to a “status update” the system produces, but written from actual ledger entries rather than people’s recall at standup.

Release notes. User-facing notes attached to a tagged release. Wired but not yet drafting; future work attaches this to a tag-push workflow.

Because each type has a different audience and a different update rhythm, each gets its own publishing cadence. That is the single most important architectural insight in the system, and the next cairn opens with it.

What the rendered surface looks like

From a reader’s seat, Conduit looks like a small project portfolio. Each project has a landing page with a recent-activity feed, breaks out per-type listings (devblogs, ADRs, sprint reports, release notes), and shows a 60-day activity sparkline. A site-wide cross-project feed exists for the people who track everything. Search is Pagefind, with full-text across artifacts.Visual accents borrow from optical-fiber band naming — teal for current activity, amber for decisions, violet for releases. The article layout is Tufte-flavored. None of that is load-bearing for the architecture; it just signals that this is a knowledge site, not a CRUD app for documents.

graph LR
  P1[Project Repo<br/>osprey-strike] --> A[Composite Action]
  P2[Project Repo<br/>osprey-vantage] --> A
  PN[...Nth Project] --> A
  A --> B[Bundle Envelope<br/>repository_dispatch]
  B --> C[Conduit Site<br/>Eleventy + Pagefind]
  C --> R[Readers]

The diagram is intentionally narrow. Each project repo has the same one-action setup, drops a bundle into the same envelope shape, and the consumer (Conduit) does not care which project sent it.

The “no human writes it” property

The most useful invariant Conduit enforces is that no human is required to write any artifact for it to publish. The publisher runs in CI on every relevant trigger. If there is something to say, it says it. If there is not, the run is silent — no commit, no notice, no zero-content placeholder.“Truly silent on quiet weeks” is the term we ended up using internally. Workflows that politely “report nothing happened” produce status noise that costs more attention than it returns. A workflow that simply does not commit on a quiet week is better.

That property is what makes Conduit work as a long-lived system rather than a documentation initiative that quietly dies. Documentation initiatives die because they cost human attention every week. Conduit costs zero attention until it has something to say, and even then the cost is reading, not writing.

What this means for a small team: the people doing the work do not also have to be the people narrating the work, and yet the work still gets narrated. That is a different shape of system than a wiki, and a different shape than even a well-maintained engineering blog.

Where Conduit fits next to other docs

Conduit is not a replacement for repo-local documentation, runbooks, or specs. Those continue to live where they always did. Conduit is the narrative outer layer — what’s been happening, why decisions look the way they do, how the system has evolved week to week.

A useful way to think about it:

Cairns are the curated essays — written by humans (or AI agents under human review) at human pace. Conduit is the steady accumulation of evidence between cairns. Together they form a layered record: ambient capture in Conduit, deep treatments in cairns, primary sources in the repos themselves.

The thing that quietly disappears in that scenario is the “draft a summary” task. There is no draft. The summary is already written, and it is the summary the team would have written if they had unlimited time, voice, and discipline.

What it doesn’t try to be

The voice is internal. Conduit publishes for the team, the stakeholders close to the team, and a small ring of curious onlookers who have access to the site — not for product marketing, not for customer-facing release notes (yet), not for external-audience documentation.

It also is not a substitute for the act of thinking carefully about a topic and writing a careful piece. That work is what Cairns is for. Conduit’s outputs are decent and surprisingly readable, but they are aggregations from a week of structured ledger entries. They cannot, and should not, replace deep thinking written down deliberately.

What this cairn doesn’t get into yet

This piece is the orientation. The next two cairns get progressively more concrete:

• How Conduit is shaped — the architectural split between project-repo publishers and the consumer site, the bundle envelope as the contract, and why per-type anchors in state.json are the design call that makes the whole thing work at multiple cadences.
• How Conduit runs — what onboarding a new project actually looks like, the composite GitHub Action that does the work, the versioning policy, the Gemini API key probe, and the operational failure paths.

If you want to skim the ground truth before the next cairn, the action’s README in the conduit repo is the densest source. The README is also part of what the next two cairns will reference and link.

What the team should take away

The thing Conduit changes for the team is not “we now have a blog.” Anyone can have a blog. The change is that there is a cheap, automatic, honest surface where the team’s reasoning accumulates without anybody having to remember to put it there.

That changes a few practical things. Newcomers have a place to read recent history. Stakeholders can self-serve the question “what’s been happening.” The team can look back over six months and have something resembling an institutional memory, instead of squinting at a git log and trying to remember what the discussion was about.

It also makes the per-repo discipline of writing good timbers entries pay back at the org level rather than only at the per-repo level. The investment in capturing reasoning at the moment of work has a visible downstream surface now, which is the kind of feedback loop that keeps the discipline alive.

1. Reasoning rots structurally without a place to live. The default tools (git, PRs, chat) capture artifacts and lose reasoning. Conduit gives reasoning a durable, readable home.
2. Timbers preserves the signal; Conduit is the narrative layer. Per-repo ledger entries become aggregated, multi-artifact, human-readable feeds.
3. Four artifact types, four audiences. Devblog (story), ADR (decision), sprint report (status), release notes (user-facing). Different jobs, different cadences.
4. The work writes itself. No human is required to draft any artifact. Quiet weeks are silent. The cost is reading, not writing.
5. Conduit complements rather than replaces. Repo docs, runbooks, ADRs, and cairns all keep their roles. Conduit is the ambient outer layer.

• What's the right cadence for someone outside the engineering team to check Conduit — daily, weekly, on demand? What signals would make us want to surface specific artifacts more actively?
• Where does the line live between "this should be a Conduit artifact" and "this should be a Cairn"? How would we know if the trade-off is drifting?
• If we wanted Conduit to support a customer-facing slice (filtered to release notes and selected devblogs), what would change about the publisher side, the bundle envelope, or the consumer's permission model?

1. Timbers — The per-repo development ledger that captures the reasoning Conduit aggregates. Reading the Timbers cairn first makes Conduit's role much clearer.
2. The Quiet Teammate — Background on how the team treats AI agents as ambient collaborators rather than tools, which shapes the editorial voice Conduit publishes in.
3. The Memory Problem — The deeper framing of why small engineering teams lose institutional memory, and what shape of system actually fixes it.
4. Eleventy — The static site generator Conduit is built on. Static-site rendering is the right call for an artifact-driven knowledge site.
5. Pagefind — Client-side search for static sites. Used by Conduit so search works without a runtime service.
6. GitHub Composite Actions — The mechanism Conduit uses to share publisher logic across N project repos without each repo carrying its own copy. The next cairn unpacks why this was the right architectural choice.