{"article":{"slug":"idrs-as-records-of-intent","title":"IDRs as records of intent","subtitle":null,"summary":"Will Lachance refines his Implementation Decision Records (IDRs), short documents meant both to get better output from LLM coding agents and to leave a durable record of implementation decisions, arguing they should capture the problem, goals, non-goals and intended result rather than a step-by-step plan.","content_type":"blog_post","language":"en","canonical_url":"https://wrla.ch/log/2026/10/idrs-as-records-of-intent/","author":{"name":"Will Lachance","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"wrla.ch","url":"https://wrla.ch/","listing_slug":null,"listing":null},"topics":[{"name":"AI Agents","slug":"ai-agents","url":"https://listedarticles.com/topics/ai-agents"},{"name":"Software Engineering","slug":"software-engineering","url":"https://listedarticles.com/topics/software-engineering"},{"name":"Writing","slug":"writing","url":"https://listedarticles.com/topics/writing"},{"name":"Developer Tools","slug":"developer-tools","url":"https://listedarticles.com/topics/developer-tools"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":609,"reading_minutes":3,"published_at":"2026-10-10T00:00:00.000Z","added_at":"2026-10-13T23:11:49.198Z","updated_at":"2026-10-13T23:11:49.198Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/idrs-as-records-of-intent","markdown_url":"https://listedarticles.com/articles/idrs-as-records-of-intent.md","example":false,"citation":"Will Lachance, wrla.ch. \"IDRs as records of intent.\" 10 Oct 2026. https://wrla.ch/log/2026/10/idrs-as-records-of-intent/ (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://wrla.ch/log/2026/10/idrs-as-records-of-intent/"},"body_markdown":"In [Writing the Docs: 2026 Edition](https://wrla.ch/log/2026/08/writing-the-docs-2026-edition/), I talked a little bit about [IDRs](https://github.com/wlach/idr-tools) (Implementation Decision Records, a pun on \"Architecture Decision Records\" which predate adoption of LLMs).\n\nAs a refresher, I created them to serve a couple purposes:\n\n1. To get better output out of LLMs\n2. To provide a durable record of a decision made during the implementation of a feature\n\nI'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]](https://wrla.ch/log/2026/10/idrs-as-records-of-intent/#fn-idrs-as-records-of-intent-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.\nAt best, they might allow you to steer them towards a better outcome before too much code is written.\n\nA great example is this one, where I asked the agent to update [repo-parser](https://github.com/wlach/repo-parser) to use DuckDB for the intermediate representation:\n\n```\n# DuckDB serialization\n\nOwner: Will Lachance\n\n## Overview\n\n### Problem Statement\n\nrepo-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.\n\n### Context\n\n\n\n...\n```\n\n[link](https://github.com/wlach/repo-parser/blob/main/idrs/202601030409-duckdb-serialization-and-interactive-ui-architecture.md)\n\nThe problem statement isn't horrible, but it's also rather vague.\nI don't think it really gave the agent much of a goal aside from \"use duckdb in some way\" to replace some other mechanism.\nI think the result was ok-ish, but I wonder a bit if the IDR had much value in that process.\nIt 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).\nAnd it's definitely not something I want to re-read later, I cringe looking at it now.\n\nWhat 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.\nWithout this, it's just a long-winded way of restating the diff in english.\n\nI'm much happier with this one:\n\n```\n# Publish to PyPI from GitHub Actions\n\nOwner: Will Lachance\n\n## Overview\n\n### Problem Statement\n\nrepo-parser packages can only be published to PyPI manually, which is time consuming, error prone and less secure than doing so via GitHub actions.\n\n### Context (as needed)\n\n### Goals\n\n- Make it easier to publish new releases\n- Improve security\n\n### Non-Goals\n\n- Automate version bumping (will still entail a seperate commit to bump version)\n\n### Proposed Solution\n\nUse the idiomatic best practice way of doing this, using the official packaging guide:\n\nhttps://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/\n\nIn general this means adding a new GitHub workflow which ties uploads to PyPI to new releases.\n\n## Other reading (as needed)\n\n- [Official Guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)\n- [Stamina's implementation](https://github.com/hynek/stamina/blob/b25d4bc359ff603496aafbb217ab82c5a43715a6/.github/workflows/pypi-package.yml) (likely best practice)\n```\n\n[link](https://github.com/wlach/repo-parser/blob/main/idrs/202512310404-publish-to-pypi-from-github-actions.md)\n\nThe problem statement describes the \"itch\" that made me want to perform the intervention.\nThe 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.\nBonus: when using an LLM it provides clearer guard-rails.\nEvery 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.\nIf I need more detail, I'll just look at the diff.\n\n1. They'll also do this if you ask them to create a commit message without strong guardrails [↩︎](https://wrla.ch/log/2026/10/idrs-as-records-of-intent/#fnref-idrs-as-records-of-intent-1)\n","body_html":"

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).

\n

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

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

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.\nAt best, they might allow you to steer them towards a better outcome before too much code is written.

\n

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

\n
# DuckDB serialization\n\nOwner: Will Lachance\n\n## Overview\n\n### Problem Statement\n\nrepo-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.\n\n### Context\n\n<very long winded, almost inscrutable LLM context>\n\n...
\n

link

\n

The problem statement isn't horrible, but it's also rather vague.\nI don't think it really gave the agent much of a goal aside from "use duckdb in some way" to replace some other mechanism.\nI think the result was ok-ish, but I wonder a bit if the IDR had much value in that process.\nIt 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).\nAnd it's definitely not something I want to re-read later, I cringe looking at it now.

\n

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.\nWithout this, it's just a long-winded way of restating the diff in english.

\n

I'm much happier with this one:

\n
# Publish to PyPI from GitHub Actions\n\nOwner: Will Lachance\n\n## Overview\n\n### Problem Statement\n\nrepo-parser packages can only be published to PyPI manually, which is time consuming, error prone and less secure than doing so via GitHub actions.\n\n### Context (as needed)\n\n### Goals\n\n- Make it easier to publish new releases\n- Improve security\n\n### Non-Goals\n\n- Automate version bumping (will still entail a seperate commit to bump version)\n\n### Proposed Solution\n\nUse the idiomatic best practice way of doing this, using the official packaging guide:\n\nhttps://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/\n\nIn general this means adding a new GitHub workflow which ties uploads to PyPI to new releases.\n\n## Other reading (as needed)\n\n- [Official Guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)\n- [Stamina's implementation](https://github.com/hynek/stamina/blob/b25d4bc359ff603496aafbb217ab82c5a43715a6/.github/workflows/pypi-package.yml) (likely best practice)
\n

link

\n

The problem statement describes the "itch" that made me want to perform the intervention.\nThe 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.\nBonus: when using an LLM it provides clearer guard-rails.\nEvery 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.\nIf I need more detail, I'll just look at the diff.

\n
  1. They'll also do this if you ask them to create a commit message without strong guardrails ↩︎
","headings":[]}}