Tooling to support Implementation Decision Records (IDRs), for humans and machines.
IDRs give you structured context that explains what you're building and why, without creating documentation debt.
idr new "Add OAuth support"
# Creates: idrs/202601051430-add-oauth-support.mdOpens a template like this:
# 2026-01-05: Add OAuth support
Owner: Your Name <[email protected]>
## Overview
### Problem Statement
<!-- What problem are we solving? -->
### Goals
<!-- What are we trying to achieve? -->
### Proposed Solution
<!-- High-level approach -->
## Detailed Design (as needed)
<!-- Technical details, API design, etc. -->
## Implementation (ephemeral)
<!-- What actually happened during implementation -->Use this template as a starting point:
- ✏️ Fill it in (get an LLM to help if you like)
- 🔄 Update as you work (especially the implementation section)
- ✅ Commit it with your code
- 🚀 Move on after it lands
IDRs are moments in time, a record of what was done. They are not intended to be permanent documentation of the system "as it is".
This is an experiment to try and find a middle ground between proposals, documentation, and implementation.
Traditional design docs are useful for larger decisions that require a great deal of discussion and alternatives. ADRs are great for documenting decisions but usually lack implementation detail. IDRs bridge the gap: detailed enough to guide implementation, ephemeral enough to not become stale documentation.
In some ways an IDR is analogous to a very large commit message. However, it is generally easier to scan, parse, and search as a permanent historical record.
Create a new IDR:
idr new "Your Feature Title"This will create a new markdown file in the idrs/ directory with:
- A UTC timestamp prefix (e.g.,
202512301600) - A slugified version of your title
- Pre-filled template with your git author name
Example:
idr new "Add last modified metadata"
# Creates: idrs/202512301600-add-last-modified-metadata.mdThe IDR template includes sections for:
- Problem Statement
- Context
- Goals and Non-Goals
- Proposed Solution
- Detailed Design
- Implementation notes (ephemeral)
The comments are useful reminders for both humans and LLMs, but you can opt to not include them by passing --no-comments or setting the environment variable IDR_NO_COMMENTS=1.
This repository includes an optional idr skill for agent workflows. It keeps IDRs human-led: the agent can create the scaffold, critique the IDR, implement from the approved IDR, and update the implementation notes after the work is done.
To install it locally, symlink skills/idr into your agent's skills directory:
# Codex
ln -s /path/to/idr-tools/skills/idr ~/.agents/skills/idr
# Claude Code
ln -s /path/to/idr-tools/skills/idr ~/.claude/skills/idrThis feature was itself implemented using an IDR—see idrs/202601031709-init.md for more about the IDR format and philosophy.