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.

Key Takeaway

Timbers preserves the signal. Conduit is the narrative layer that turns per-repo signal into a feed a teammate, a stakeholder, or a future-you can actually read.

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 (project metadata, workflow YAMLs, and credentials) and calls a shared GitHub Action that handles drafting and dispatching. 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.

Artifact types, deliberately distinct

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

Pulse. A concise daily rollup for the whole team. It is the ambient “what moved today” artifact: short enough to scan, frequent enough to keep recent work visible.

Devblog. A weekly 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. The old sprint-report role is folded into this weekly recap rather than living as a separate standup-flavored artifact.

Leadership brief. A weekly stakeholder summary that rolls up the week’s recaps. It exists because leadership wants a different level of detail than engineers reading the devblog.

Product updates. Weekly customer-facing notes filtered to feat/fix/perf work. This is the successor to the old release-notes concept: less tied to tags, more tied to the product changes a customer would recognize.

Milestone. A rare, manually triggered summary for larger moments. It is intentionally not part of the ordinary weekly rhythm.

Decision log. An ADR-style technical record — context, options, decision, consequences. Decision logs are reference material, not narrative. They earn their slot in the system only when a real fork in the road was navigated.

Definition

Each artifact type has its own audience. A pulse is for “what moved today”; a devblog is for “what’s the engineering story this week”; a brief is for “what should leadership know”; product updates are for “what changed that a customer can use”; a decision log is for “why is this thing the way it is.” Lumping them into a single feed would lose all of that.

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, 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 dispatch, 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 dispatch anything 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.

Warning

The “no human writes it” property is not the same as “no human supervises it.” Bad prompts produce bad artifacts; broken credentials produce silent failures dressed up as quiet weeks. Both of those failure modes are real and both are addressed in how Conduit is built. The next cairn covers them.

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:

Surface Lives in Read by Update cadence
Code + tests Repo Anyone editing the code On every change
Runbooks + specs Repo or doc-vault Operators, on-call When the system changes
ADRs in docs/decisions/ Repo Engineers reaching back When a decision is made
Cairns (like this one) Cairns repo The team and stakeholders Curated, occasional
Conduit Conduit repo The team and stakeholders Continuous, automatic

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.

Scenario: a stakeholder asks what's been happening
@Bob "Can you put together a short summary of what the team's been up to in May?"
@Q The Conduit site for May already has it — weekly recaps, daily pulses, one new decision log, and a leadership brief. I can link the page; you'd be reading the same artifacts anyone on the team would.

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

Most of 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. Product updates are the exception: a weekly, customer-facing channel filtered to concrete product changes, not a general marketing surface.

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.

Tip

The right mental model is “Conduit is the team’s ambient narrative layer; Cairns is the team’s curated essays.” If you find yourself wanting to put deep analysis into Conduit, you are probably actually writing a cairn.

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 time windows are the design call that makes the whole thing work at multiple cadences without caller-side state or anchor files.
  • How Conduit runs — what onboarding a new project actually looks like, the composite GitHub Action that does the work, the versioning policy, the Bedrock 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. Several artifact types, several audiences. Pulses, devblogs, leadership briefs, product updates, milestones, and decision logs each have different jobs and 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?
  • Now that Conduit has a customer-facing product-updates channel, what would change if selected devblogs also needed a public slice?
  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.