In Writing the Docs: 2026 Edition, I talked a little bit about IDRs (Implementation Decision Records, a pun on "Architecture Decision Records" which predate adoption of LLMs).

As a refresher, I created them to serve a couple purposes:

1. To get better output out of LLMs
2. To provide a durable record of a decision made during the implementation of a feature

I've realized that left to their own devices given a vague prompt, an LLM will often just try to fill one in with a textual description of what it planned to implement anyway.^[1] This makes them pretty lossy as a record of intent (it's basically not much better than a diff, and arguably worse) and I'm somewhat skeptical it improves their output much. At best, they might allow you to steer them towards a better outcome before too much code is written.

A great example is this one, where I asked the agent to update repo-parser to use DuckDB for the intermediate representation:

# DuckDB serialization

Owner: Will Lachance <[email protected]>

## Overview

### Problem Statement

repo-parser extracts metadata and structure from repositories into an in-memory `Resource` tree, but this ephemeral representation must be re-created for each consumer. We need a persistent, queryable serialization format that allows multiple tools to consume the extracted metadata without re-scanning the repository.

### Context

<very long winded, almost inscrutable LLM context>

...

link

The problem statement isn't horrible, but it's also rather vague. I don't think it really gave the agent much of a goal aside from "use duckdb in some way" to replace some other mechanism. I think the result was ok-ish, but I wonder a bit if the IDR had much value in that process. It certainly doesn't help explain what the duckdb output of repo-parser is actually good for (a BM25 search index of a repository's contents, possibly TUI search tools). And it's definitely not something I want to re-read later, I cringe looking at it now.

What I'm increasingly realizing is that for an IDR to be really effective it needs to keep returning to the intent and decisions taken to support it. Without this, it's just a long-winded way of restating the diff in english.

I'm much happier with this one:

# Publish to PyPI from GitHub Actions

Owner: Will Lachance <[email protected]>

## Overview

### Problem Statement

repo-parser packages can only be published to PyPI manually, which is time consuming, error prone and less secure than doing so via GitHub actions.

### Context (as needed)

### Goals

- Make it easier to publish new releases
- Improve security

### Non-Goals

- Automate version bumping (will still entail a seperate commit to bump version)

### Proposed Solution

Use the idiomatic best practice way of doing this, using the official packaging guide:

https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

In general this means adding a new GitHub workflow which ties uploads to PyPI to new releases.

## Other reading (as needed)

- [Official Guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
- [Stamina's implementation](https://github.com/hynek/stamina/blob/b25d4bc359ff603496aafbb217ab82c5a43715a6/.github/workflows/pypi-package.yml) (likely best practice)

link

The problem statement describes the "itch" that made me want to perform the intervention. The goals, non-goals and solution are short, punchy and explain the end result without getting into implementation details. When I go back and look at a repository later, this is the sort of thing I want to see. Bonus: when using an LLM it provides clearer guard-rails. Every sentence does the work of steering behaviour towards the actual result I want to see, rather than being a set of instructions that it might misinterpret. If I need more detail, I'll just look at the diff.

Over the past half a year (starting around this post: Music updates) I've been slowly building out a homelab.

Despite being adjacent to communities where this is common (Recurse, etc.), this wasn't something I thought I would do a few years ago: too much effort for the expected return. A couple of things changed since then:

• My present work at Voltus requires me to at least think of infrastructure issues a fair bit more: the engineering team is still small enough that I need to get into the weeds of how things are configured, deployed and monitored-- not just how they work at the data and application layer.
• The software stack around it has gotten better: we're long past the days where this meant dangerously exposing a raw Linux system on a router. Also there are many more actually useful things you can run.
• LLMs make this type of thing vastly easier to build independently with only generalist-level knowledge.

The exact architecture is still a work in progress, but the basic components are in place:

• Using Tailscale for the network boundary. This lets me run a bunch of network services using my local machines without exposing them directly to the internet. I can run services with minimal (or even no) built-in authentication since access is controlled by the tailnet.
• Using an old w520 for the main "persistent" system server running the network services. 8 GB, Intel Sandy Bridge. It's underpowered by today's standards but more than enough to run the types of things I might want to do (music servers, read-it-later, lightweight notebooks, ai agent harnesses).
• Storing persistent configuration as a git repository. Mostly a bunch of docker service definitions and systemd units, along with README.md files describing how to set it up and run it when I inevitably forget. I'm thinking about moving some of this to nix someday, but haven't found a compelling reason to do so other than "nix is cool, I want to learn more about it" (maybe that's enough).

Here is the server in all its glory:

The setup so far is:

• jellyfin for music listening
• readeck for saving useful posts to disk (after Mozilla discontinued Pocket, I determined that I should never trust a third party service to do this again)
• marimohub for exploring analytical ideas / questions in notebook form (it's a little under-documented right now, but it supports tailscale authentication headers out of the box, I might write more about this later)
• pi-web for interactive coding (honestly mostly used for working on this system recursively, but maybe more one day)

I'm pretty happy with the setup as a learning experience. I've been using various LLMs to build it, but try to understand their end products. Feels like the appropriate use of technology: the configuration is mostly boilerplate, the interesting questions for me are higher level: what does each additional piece of functionality allow me to do, what are the risks, etc. I could of course "do things the hard way" and reproduce tailscale configuration and systemd files from scratch but it just doesn't seem quite worth it. At present, I don't have the ambition of becoming an infrastructure engineer.

I don't really have illusions that this system is incredibly useful or life changing in itself-- it just replaces a few cloud services I would otherwise pay for (or be sad when they go away, as happened with Pocket). Most of the value is in the experience of building it.