Erik’s Weblog

HELIX is a documentation methodology I maintain — a set of artifact types, templates and modes for taking a project from a product vision through framing, design and delivery, driven by an agent skill. Its own PRD, written in its own format, promised two things: healthy artifact sets average fewer than three alignment findings per run, and HELIX-template PRDs pass first review more often than free-form ones Neither is measurable as written. I had shipped two claims with no instrument behind them. The first has no definition of “healthy” and no baseline. The second compares against a control group that doesn’t exist. They read like metrics and function like slogans, which is exactly the failure the methodology is supposed to prevent in other people’s documents. ...

HELIX is a documentation methodology I maintain for software projects: artifact types, templates and modes that carry a project from a product vision through framing, design and delivery, driven by an agent skill. Its first two stages, discover and frame, claim to be about understanding a problem before committing to a solution. That claim shouldn’t depend on the problem being software. So I tested it in the least charitable way I could think of: an empty repository, a fresh install, and a competitive analysis of the dog treats market. ...

I seal my documentation with innsigle, a small content-provenance tool: each page carries a signed claim saying who published it and how it was composed — human-authored, model-primary, or mixed. For a while, one key signed all of it. That’s fine right up until you notice what the key is actually asserting. Generated reference pages are built and sealed in CI, so the private key has to be a GitHub Actions secret. Curated pages are written by hand and claim mixed or human-authored. Same key, same signature. Which means the CI secret — a value sitting in a repository settings page, readable by any workflow, restorable by anyone with admin — can produce a page that says a person wrote it. ...

Someone in the house reported choppy Google Meet calls. I have QoS on the router — a MikroTik RB5009 running fq-codel with a three-tier queue tree, shaped both directions — and conferencing traffic is supposed to be in the priority lane. So either the QoS wasn’t working, or Meet wasn’t landing in the lane I thought. Measuring first, from a wired host on the same segment: zero packet loss to the gateway, to the affected machine, and to 8.8.8.8, with 0.05 ms jitter on the LAN and 0.71 ms to the internet. Nothing wrong at the time I looked, which already suggested I was chasing something intermittent and load-dependent rather than broken. ...

On a UEFI Ubuntu system there’s a 123-byte file on the ESP that almost nobody looks at. Mine was at \EFI\ubuntu\grub.cfg and contained this: search.fs_uuid 0a9ccc8b-d14c-4291-9eb8-7bf71995a901 root hd2,msdos1 set prefix=($root)'/grub' configfile $prefix/grub.cfg That’s the whole bootstrap. The signed grubx64.efi on the ESP has no idea where your real configuration lives, so this stub finds the /boot filesystem by UUID, sets $prefix to point at it, and chains to the grub.cfg that update-grub generates. Three lines, and I’d never read them before the day my NAS stopped booting. ...

My NAS runs on a Supermicro X10SDV-TLN4F — Xeon D-1541, 128 GB of ECC, a 22 TB ZFS pool, and a BIOS dated 2017. It had been up since March. I did some network configuration work one morning, rebooted, and it didn’t come back. What it showed instead was the Supermicro splash screen with A2 in the bottom right corner, and a keyboard that did nothing. DEL wouldn’t get me into Setup, F11 wouldn’t open the boot menu, F12 wouldn’t PXE. The machine sat there indefinitely. ...

While rebuilding the root filesystem of my NAS I had to decide how much swap to give it. The machine has 128 GB of ECC RAM and runs a ZFS pool, some containers, and a Spark setup that occasionally gets greedy. The old install had a 976 MB swap LV that wasn’t even in fstab. The folk rule says swap should be at least as large as RAM, which would mean carving 128 GB out of a 929 GB mirrored volume group for something I’d hope never to use. That felt obviously wrong, so I went looking for where the rule comes from. ...

I keep a few infrastructure repos in ~/Sync, a Syncthing folder shared between my laptop, my desktop and a NAS. It’s a convenient way to have the working trees follow me around. The repos also have real git remotes — a bare repo on the NAS — so Syncthing was never the mechanism for sharing history, just for keeping the directories in step. One afternoon I made a small change to a Terraform file, went to commit it, and got this: ...

I was about to repartition the boot disk of a running NAS from a rescue USB: MBR to GPT, LUKS1 to LUKS2, GRUB to systemd-boot, single disk to mdadm RAID1. Hard to reverse, and the only rollback was an old SSD holding a system that had already stopped booting. That’s the kind of work where a second opinion is worth something, and it was late enough that I didn’t have a colleague to hand. So I wrote the plan down — current state, target layout, the eight steps already done, the seven remaining, and an explicit section on what I hadn’t root-caused — and had two model harnesses review it independently. One was codex, one was a Fable subagent. Same brief, separate processes, neither saw the other’s output. ...

I rebuilt a NAS onto a mirrored encrypted root: two SSDs, mdadm RAID1, LUKS2 on top, LVM inside. That layout is well-trodden — it’s what the Debian and Ubuntu Server installers produce when you ask for software RAID plus encryption, and the reasoning for putting RAID below LUKS is sound. You encrypt once instead of twice, resync traffic is ciphertext, and rebuilds work on raw blocks below the crypto layer. ...