Published on 2026-03-01
]]>Published on 2026-03-01
Tags: article, llm, ocaml, python, software-eng, software-eng-auto
On today's episode: a lot of code. The previous work prepared the project codebase to guide agents in generating good quality code, which is what we did.
After the Kb_service module was broken apart, the coding agent easily generated full verticals for update, resolve, and archive commands. The process I'm following:
docs/product-requirements.md.prompts/activities/implementation-plan.md for building the functionality.prompts/activities/code-review.md), and apply changes for all issues.Related commit: 0eb5584 — feat: add update, resolve, and archive commands
Published on 2026-02-26
]]>Published on 2026-02-26
Tags: article, llm, ocaml, software-eng, software-eng-auto
Today's log consists mostly of code generation. We've laid enough foundation that new functionality is easily produced.
The functionality for bs list is well defined after the work for the previous dev log. I think the experiment of directing the agents from the requirements document rather than my own intuition of what to tackle was successful, though perhaps only at the scale of a project like Knowledge Bases. The coding agent was able to select a reasonable chunk of functionality to peel off and turn into an implementation plan, with a different agent generating the implementation.
Published on 2026-02-24
]]>Published on 2026-02-24
Tags: article, llm, ocaml, software-eng, software-eng-auto
Today's changes follow on from the previous post's "next steps": nesting and ideation.
I worked with the agent to find code with deep nesting, decide how to flatten it, and generalize the approach into suggestions for a nesting principle. We then applied that principle across the codebase, and I think we were successful as the diff in the refactor commit is noticeably flatter.
]]>4. Nesting Depth
Keep expressions nested at most two or three levels deep. Deeply nested code is hard to follow because the reader must hold every enclosing context in their head at once. When nesting grows, treat it as a signal that the code should be restructured.
Approaches for reducing nesting:
- Use monadic result operators (
let*,let+). ...- Extract resource-management wrappers. ...
- Consolidate error mapping into named functions. ...
- Factor repeated control-flow shapes into helpers. ...
Published on 2026-02-20
]]>Published on 2026-02-20
Tags: article, code-review, llm, ocaml, software-eng, software-eng-auto
Today's changes build on the previous commit's unpacking of Todo, making a repository for Todos, and hooking it up to the command line to provide bs add todo ....
The implementation plan forgot to add a task for integration tests, which resulted in a bin principle saying changes to bin, where we're only keeping command-line parsing and top-level orchestration, should always be accompanied by an integration test. I also had the agent put together an architecture document guiding the structure of integration tests and their purpose.
In the hopes of keeping file sizes down, I added a line length principle to bin and lib. I'm not sure about these principles, because I think this can be automated as a lint. I will keep these in mind and improve the linting situation when I get another structural/syntactic principle that can be automated.
Published on 2026-02-19
]]>Published on 2026-02-19
Tags: article, code-review, llm, ocaml, software-eng, software-eng-auto
Today's change to Knowledge Bases is addressing my unhappiness at the beginning of the month: "Data modeling". I've returned to the work of unpacking Note into Todo, to make it easier to control the TypeID prefix, and prepare for making a Todo repository.
A handy thing about coding agents: they can make such a wide-ranging change with minimal effort (see the number of changed files in the commit). Additionally, the coding principles guidance doc paid for itself — agent code review noted the duplicated validation logic for title and content now in both Note and Todo and recommended deduplication. I redirected it to encapsulate the validation into new types, a favorite software engineering technique of mine (see "Aside: Correct Construction"), as well as adjusted the guidance.
Published on 2026-02-18
]]>Published on 2026-02-18
Tags: article, git, llm, ocaml, software-eng, software-eng-auto
I've decided to use this project as a testbed for automatic development, to explore the kinds of techniques described in recent results [1] [2], and to speed up development. I'll be making the vast majority of changes to the codebase via coding agents, exploring what controls are needed to stay hands-off yet maintain code quality.
I've played around with longer AGENTS.md and not seen much value. Agents would ignore pieces, and after a while it felt like simply a waste of context space. I'm keeping AGENTS.md short this time around, "linking" to where more information can be retrieved, with the hope that brevity keeps the content important.
Published on 2026-02-03
]]>Published on 2026-02-03
Tags: article, database, git, ocaml, software-eng
Today's update is brought to you by my lack of motivation 😆. I decided to work on building out a storage layer for Knowledge Bases objects, and then got burned by lack of interest.
Restating our storage requirements: we need notes, todos, etc to be persisted to disk in a way where git's diff will capably show edits, additions, and deletions, and which allows for easily querying these objects by identifier or by their relation to each other (we want to support parent-child, related-to, etc). To meet those requirements I intend to persist data in two ways. First, in an appropriately-sorted JSON or YAML file, to solve for the git-diff requirement. Second, in a SQLite database to make it easy to add/edit/delete/query. The program will mirror the SQLite database onto the JSON file unless it's determined to be out of date (i.e. when the git branch is changed), in which case we'll rebuild the database from the JSON file. For now I'm starting with the SQLite db, as that can be useful for purely local todo storage, and we'll bolt-on the ability to synchronize them over git later.
]]>Published on 2026-01-01
]]>Published on 2026-01-01
Tags: article, git, meta, ocaml, static-site
For 2024's New Year's resolution I decided I'd finally build and publish a personal website. That I'd write up my thoughts on the articles I was reading and post them instead of dumping them on friends 😆. In review, I'm happy to say I succeeded.
I wrote and published 164 blog posts over the past year, not counting this post. September was my most prolific month. I initialized the OCaml project that became the static site generator in late January, writing a test post at the beginning of February to work out frontmatter parsing, markdown generation, and my custom templating language. The first "real" post came at the end of June, a few days after I bought the domain name.
]]>Published on 2025-11-30
]]>Published on 2025-11-30
Tags: article, git, ocaml, software-eng
TypeID is a micro-standard combining a number of well-thought-out decisions.
TypeIDs are a modern, type-safe extension of UUIDv7. Inspired by a similar use of prefixes in Stripe's APIs.
TypeIDs are canonically encoded as lowercase strings consisting of three parts:
- A type prefix (at most 63 characters in all lowercase snake_case ASCII
[a-z_]).- An underscore '_' separator
- A 128-bit UUIDv7 encoded as a 26-character string using a modified base32 encoding.
user_2x4y6z8a0b1c2d3e4f5g6h7j8k
└──┘ └────────────────────────┘
type uuid suffix (base32)
Most identifiers, barring a specialized context, should include a "type" for the identifier. Interconnected computer systems are always passing around identifiers — for someone holding an identifier in their database it is really valuable to know who that identifier belongs to as well as what the identifier is for. For example in a financial institution handling investments, md_quote_2x4y6z8a0b1c2d3e4f5g6h7j8k can tell the receiver that they're holding a reference to a stock price quote, owned by the market data (md) system. Identifier types give engineers metadata, which can be especially useful when there's a bug in the system — no need to stress whether the integer identifier you're currently holding came from the user table or news table.
Published on 2025-11-01
]]>Published on 2025-11-01
Tags: article, ocaml
Short update today — the definitions of note and todo types and their basic operations.
My intention is to represent arbitrary content as a note, and represent things to be done with todo. Notes are just an identifier, a title, and some content, while Todos also have a status and eventually relationships. I've left relationships between notes and todos for later. I'm not sure if I want them represented separately or as part of the structures.
(** Note type and operations.
A note bundles an [Identifier.t] with a title and content.
*)
(** Abstract type of notes. *)
type t
(** [pp fmt t] prints the note [t] using the formatter [fmt]. *)
val pp : Format.formatter -> t -> unit
(** [show t] returns the same string that {!pp} would print. *)
val show : t -> string
(** [make identifier title content] constructs a note after validating inputs.
- [title] must be non-empty and at most 100 characters.
- [content] must be non-empty and at most 10000 characters.
@raise Invalid_argument if validation fails. *)
val make : Identifier.t -> string -> string -> t
(** [id t] returns the note identifier. *)
val id : t -> Identifier.t
(** [title t] returns the title of the note. *)
val title : t -> string
(** [content t] returns the content of the note. *)
val content : t -> string
Published on 2025-10-25
]]>Published on 2025-10-25
Tags: article, llm, ocaml
My inclination, after getting the hello world project set up in place, is to start defining the major data representations of the domain we're working in. Since I'm documenting the process, and I want to discuss decisions, I'm going to start out pretty slowly — today's update is basically just a type for representing identifiers for "notes" (whatever it is we decide to call the basic content building block).
The plan here is to expose an opaque type t for our identifier values (Identifier.t), and be explicit and deliberate about what data is exposed to the rest of the program. I liked how Beads stuck with an identifier format that's human readable, and likely prevalent in LLM training data, so we'll use the same format for our identifier: [a-z]{1,5}-[0-9]+ (e.g. kbase-12345). Decomposing that identifier gets us a namespace and raw_id.
Published on 2025-10-22
]]>Published on 2025-10-22
Tags: article, git, llm, ocaml
A couple days ago, Steve Yegge wrote about a coding agent tool he's been developing called Beads.
Beads is a lightweight memory system for coding agents, using a graph-based issue tracker. Four kinds of dependencies work to chain your issues together like beads, making them easy for agents to follow for long distances, and reliably perform complex task streams in the right order.
I haven't had an opportunity to see if it works well or not, but the feature set seems straightforward to implement and I've been looking for a project to work on which will involve OCaml and publishing to opam. I'll be documenting the development process here 😁.
]]>Published on 2025-09-06
]]>Published on 2025-09-06
Tags: article, ocaml, security, software-eng
When using OpenSSH, you may see ASCII art from time to time, like:
+--[ED25519 256]--+
| |
| . |
| o |
| o o o . |
| .B S oo |
| =+^ =... |
| oo#o@.o. |
| E+.&.=o |
| ooo.X=. |
+----[SHA256]-----+
This is output[1] of the randomart SSH Key visualization algorithm, intended to leverage the user's visual pattern matching to quickly recognize (or not) a remote host key. It's known as the Drunken Bishop's algorithm, contributed to the OpenSSH codebase by Alexander von Gernler in 2008.
]]>Alexander von Gernler on 2008-06-11:
Introduc[ing] SSH Fingerprint ASCII Visualization, a technique inspired by the graphical hash visualization schemes known as "random art", and by Dan Kaminsky's musings on the subject during a BlackOp talk at the 23C3 in Berlin.
Scientific publication (original paper): "Hash Visualization: a New Technique to improve Real-World Security", Perrig A. and Song D., 1999, International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
Published on 2025-08-10
]]>Published on 2025-08-10
Tags: article, java, javascript, ocaml, static-site
I like the idea of having search for my blog, to help readers find anything related to a specific topic, or something they'd read in the past. How do I make something as dynamic as search, but statically generated?
Published on 2025-08-06
]]>Published on 2025-08-06
Tags: article, css, html, javascript, static-site
Unfortunately I spoke too soon when I wrote the Building this Site post. I had a plan in place to use hilite, along with TextMate grammars and themes pulled from Shiki (which in turn gets its grammars and themes from TextMate/VSCode), but it fell through.
The plan was to grab lightmode and darkmode themes from Shiki's trove of themes, stripping out any extraneous styles (a lot of text-editor-specific colors are given) to arrive at two sets of colors for pre-determined class names. Shiki works similarly to hilite: during processing it tags portions of the source code with CSS tags derived from the grammars. All of the TextMate grammars employed by Shiki use a consistent naming scheme, ensuring themes always line up with the grammars, resulting in colored text. With a little adjustment of the theme CSS tags to account for any differences between Hilite's and Shiki's tagging, I'd have ahead-of-time syntax highlighting, with as many supported languages as VSCode.
Published on 2025-07-25
]]>Published on 2025-07-25
Tags: article, html, static-site
I learned recently that web browsers will execute an HTTP request for each <script> tag they find in the document. I hadn't really thought much about it, assuming a kind of declarative interpretation of HTML, where when multiple <script src="foo.js"></script> show up in the document, only one would be requested and executed. Turns out my assumption is wrong and the browser will happily request the same script multiple times. It's not much of an issue in practice, on subsequent page loads the browser will hit its local cache for every script load.
I have a number of "builtins", invokable functions, in the site's templating language. For example, date which parses and calculates date formats:
Published on 2025-07-18
]]>Published on 2025-07-18
Tags: article, software-eng, static-site
This website is created with a hand-rolled static site generator. In this series I'll talk about some of the infrastructure I've built towards making the website.
My static site generator asite, is primarily programmed in OCaml, using Dune and OPAM for the build system. The templating language used is custom, as is the majority of steps in the site building process. I do use a number of external packages:
asite uses cmarkit to render the markdown into HTML.markup is used to parse and process a blog post's HTML into just a teaser, to keep the size of the rss file small.esbuild as a step in the build process, more on this in future posts.Published on 2025-07-01
]]>Published on 2025-07-01
Tags: article, code-review, communication, software-eng
At my day job I review a lot of other people's work, in the form of code reviews or design (and other) documents. A few years back a coworker whose code I was reviewing requested, rather insistently, that I start using conventional comments when doing code reviews. They also messaged it out to the team, though more as a practice suggestion and not a proposed change to the team's process.
I internally shrugged the request off, as they were a junior engineer still working through their personal relationship to feedback — as we all do. I don't think many people are raised with the education necessary for internally de-personalizing feedback, analyzing your own behavior, synthesizing the given feedback with your own understanding of "the world", and thanking the other person for their gift, regardless of your orientation towards that "gift". It's complicated stuff and most of us, myself included, take years to adjust our reactions accordingly.
]]>