decision-records
Skill553 starsChanged 2 months agoMITView on GitHub
Create, update, or manage decision records in homeracker. Use this skill when comparing alternative solutions and choosing one, changing behavior of CLI tools or build processes or model conventions, making trade-offs that future contributors need to understand, or superseding a previous decision. USE FOR: creating new decision records, looking up existing decisions, superseding outdated decisions, documenting rationale behind tooling or architecture choices. DO NOT USE FOR: routine config changes, version bumps, dependency updates, or changes that are self-explanatory from the code or commit message.
8 other projects use a version of this.
Adopted by
Most recently taken up by
- axodouble/skillstheir own version, first seen Nov 8, 2026
- zxyycom/skillstheir own version, first seen Nov 8, 2026
- musterd-io/musterdtheir own version, first seen Nov 1, 2026
- swestfall21/claude-skillstheir own version, first seen Oct 15, 2026
- theultimate-dev/skillstheir own version, first seen Oct 11, 2026
- skymavis/skillstheir own version, first seen Oct 11, 2026
Other versions8 projects use a version of this.
Word for word · 1
- kellerlabs/homeracker★ 553100% same
Edited · 0
None found.
Wrote their own version · 7
- markphelps/agent-plugins★ 6same name
- theultimate-dev/skills★ 2same name
- zxyycom/skills★ 2same name
- musterd-io/musterd★ 1same name
- skymavis/skills★ 1same name
- axodouble/skills★ 0same name
- swestfall21/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- grill-my-modelSkill
- grill-my-planSkill
- humanizerSkill
- makerworld-descriptionSkill
- scadfmt-adaptSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 9 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Before creating a new decision, always check if one already exists:
- Very specific: line 37
Read docs/decisions/README.md for the active decisions table.
- Distinctive: line 38
If a related decision exists, determine whether to supersede it (§4) or reference it.
- Distinctive: line 55
Use this exact structure:
- Distinctive: line 80
Context: must explain the problem clearly enough that someone unfamiliar can understand it.
- Distinctive: line 81
Decision: must state the choice explicitly and include alternatives considered with brief reasons for rejection.
- Distinctive: line 82
Consequences: must include both positive and negative effects, every decision has trade-offs.
- Distinctive: line 83
Keep it concise. Prefer bullet points over prose.
- Very specific: line 84
Use the homeracker emoji conventions (📋 title, 📌 Status, 🤔 Context, 🔧 Decision, 📊 Consequences).
- Very specific: line 88
Update the decisions index: Add a row to docs/decisions/README.md (keep sorted by date descending).
- Distinctive: line 95
When a previous decision is being replaced:
- Distinctive: line 97
Create a new decision record (§3) explaining the new choice.
- Very specific: line 101
Update docs/decisions/README.md to remove the old entry and add the new one.
- Very specific: line 124
After writing or editing a decision record, run the humanizer skill over it to strip AI tells.
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
📋 Decision Records, homeracker Skill
This skill guides the creation and management of lightweight decision records that capture the why behind architecture, tooling, and workflow decisions.
Decision records help contributors and AI agents understand the original intent behind choices, especially when the reasoning isn't obvious from the code alone.
1. Determine the Action
| Request | Action |
| "Record/document this decision" | → §3 (Create a new decision) |
| "What was decided about X?" | → §2 (Look up existing decisions) |
| "Supersede/update decision about X" | → §4 (Supersede a decision) |
| "List all decisions" | → Read docs/decisions/README.md |
2. Look Up Existing Decisions
Before creating a new decision, always check if one already exists:
- Read
docs/decisions/README.mdfor the active decisions table. - If a related decision exists, determine whether to supersede it (§4) or reference it.
3. Create a New Decision
3.1 File Location & Naming
- Location:
docs/decisions/ - Naming:
kebab-case-title.md, name after the component/topic and action.- ✅
image-hosting-assets-repo.md - ✅
unify-export-png-into-scadm.md - ❌
ADR-001-image-hosting.md(no numeric prefixes)
- ✅
- The title should use a present-tense imperative verb phrase describing the decision.
3.2 Template
Use this exact structure:
# 📋 Title (present-tense imperative verb phrase)
## 📌 Status
**Accepted**: YYYY-MM-DD
## 🤔 Context
What problem or situation triggered this decision? What constraints exist?
If this supersedes a previous decision, link the predecessor commit here.
## 🔧 Decision
What did we decide and why? Include alternatives considered and why they were rejected.
## 📊 Consequences
What follows from this decision? Include both positive and negative effects.3.3 Writing Quality Criteria
- Context must explain the problem clearly enough that someone unfamiliar can understand it.
- Decision must state the choice explicitly and include alternatives considered with brief reasons for rejection.
- Consequences must include both positive and negative effects, every decision has trade-offs.
- Keep it concise. Prefer bullet points over prose. Link to code, PRs, or other docs rather than duplicating content.
- Use the homeracker emoji conventions (📋 title, 📌 Status, 🤔 Context, 🔧 Decision, 📊 Consequences).
3.4 After Creating the Decision
- Update the decisions index: Add a row to
docs/decisions/README.md(keep sorted by date descending). - Cross-link from related docs: Reference the decision from READMEs, instructions, or other decisions where viable.
4. Supersede a Decision
When a previous decision is being replaced:
- Create a new decision record (§3) explaining the new choice.
- In the new record's Context, link to the last commit on
maincontaining the old decision so readers can find it in history:git log -1 --format=%H origin/main -- docs/decisions/old-decision.md. Never a PR branch commit, it vanishes after the squash merge. Format:Supersedes [old-decision.md](https://github.com/kellerlabs/homeracker/blob/<commit-sha>/docs/decisions/old-decision.md) - Delete the old decision file: it remains available in git history.
- Update
docs/decisions/README.mdto remove the old entry and add the new one.
5. When NOT to Write a Decision
Skip decision records for:
- Routine config changes, version bumps, or dependency updates
- Changes that are self-explanatory from the code or commit message
- Temporary workarounds (use code comments instead)
- Single-option situations where there was nothing to decide
6. Reference Example
See docs/decisions/image-hosting-assets-repo.md for a well-structured example covering context, alternatives considered, and positive/negative consequences.
7. Humanize the Prose
After writing or editing a decision record, run the humanizer skill over it to strip AI tells. ADRs are reference text, so use its neutral register (no first person or injected opinions), just plain, concrete prose.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

