kit-decisions
Skill6 starsChanged 27 days agoMITView on GitHub
Keep a short living decision log for one large feature. Use while building it, before continuing the work, or when a reviewer needs the history.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- rules/AGENTS.mdAGENTS.md
- kit-audit-metricsSkill
- kit-audit-skillsSkill
- kit-capture-lessonSkill
- kit-challenge-designSkill
- kit-check-blastSkill
- kit-create-prSkill
- kit-debate-decision-treeSkill
- kit-debug-prodSkill
- kit-evolveSkill
- kit-explainSkill
- kit-learn-repoSkill
- kit-minimizeSkill
- kit-optimize-contextSkill
- kit-planSkill
- kit-proveSkill
- kit-reviewSkill
- kit-strip-diffSkill
- kit-triage-commentsSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Keep one short file for a large feature so a later agent can see why the code looks like this.
- Very specific: line 20
Not the pre-code concept log (kit-plan).
- Very specific: line 21
Not a glossary or sparse ADRs (kit-challenge-design).
- Very specific: line 22
Not a reusable rule after a repeated miss (kit-capture-lesson).
- Very specific: line 23
Not a review of the diff (kit-review).
- Very specific: line 29
If a decisions.md for this feature already exists, use that path.
- Distinctive: line 33
Create the file only when the first real entry exists.
- Distinctive: line 48
When an accepted decision is replaced, move the old bullet to Rejected and add the new evidence.
- Distinctive: line 70
Leave a heading in place when its section is empty.
- Distinctive: line 78
Update the matching section in place.
- Very specific: line 79
If an Accepted item is hard to reverse, surprising without this file, and had a real alternative, offer an ADR through kit-challenge-design.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Decisions
Keep one short file for a large feature so a later agent can see why the code looks like this.
Two jobs:
- Capture — record a closed fork or a landmine
- Brief — read the file before review or more work on that feature
Accept kit-decisions capture|brief. If omitted: capture when this conversation closed a fork or hit a landmine; brief when they ask what was already decided, or before changing the feature.
What this is NOT
- Not the pre-code concept log (
kit-plan). That log lives in chat and stops at approval. - Not a glossary or sparse ADRs (
kit-challenge-design). Promote only when the ADR bar is met. - Not a reusable rule after a repeated miss (
kit-capture-lesson). - Not a review of the diff (
kit-review). Brief states what the log says. Review still owns findings.
Where the file lives
Default: docs/features/<feature>/decisions.md
If a decisions.md for this feature already exists, use that path. Do not move it.
The file stays as long as the feature lives. Do not delete it on merge.
Create the file only when the first real entry exists.
What to record
Four sections. One short bullet each. Edit in place. No chat transcript.
| Section | Write when |
| Accepted | A direction was chosen. Include why, and what must not be undone without new evidence. |
| Rejected | A direction was tried or seriously considered, and lost. Include why, and when it may be revisited. |
| Landmines | Something looked trivial and broke, or a small change would undo a hard-won fix. |
| Open | A real fork is still undecided. |
Skip obvious choices, easy-to-reverse trivia, and glossary terms.
When an accepted decision is replaced, move the old bullet to Rejected and add the new evidence. Keep the original why.
Format
# Decisions: {feature}
Living log for this feature. Hard-to-reverse decisions that meet the ADR bar belong in `docs/adr/` — leave a pointer here.
## Accepted
- **{decision}** — {why}. Do not undo without {new evidence}.
## Rejected
- **{option}** — {why it lost}. Revisit only if {condition}.
## Landmines
- **{looks trivial}** — {what broke, and why the obvious fix fails}.
## Open
- **{fork}** — {what is still unknown}.Leave a heading in place when its section is empty.
Flow
Capture
- Name the feature. Find the file, or create it at the default path on the first entry.
- Distill this conversation into one or two bullets. Do not paste the transcript.
- Update the matching section in place. Move Open items when they close.
- If an Accepted item is hard to reverse, surprising without this file, and had a real alternative, offer an ADR through
kit-challenge-design. Write the ADR only after they say yes. Then add a one-line pointer under Accepted. - Show the bullets that changed. Stop.
Brief
- Find the file. If it is missing, say so. Do not invent history.
- List only the bullets this change can touch.
- Before review: re-proposing a Rejected option needs new evidence that beats the recorded why. Undoing an Accepted decision without that evidence is a finding for
kit-review. - Before more work: state the landmines and accepted constraints the edit can hit. Continue only if the change respects them, or the user accepts the new evidence.
Do / Don't
| Do | Don't |
| "Rejected sync retry — duplicates under timeout. Revisit only with an idempotency key." | A paragraph retelling the thread |
| One bullet when a fork closes | An entry after every message |
| A pointer to ADR-0007 after they accept the promotion | A copy of the whole ADR in this file |
| "No decisions.md for billing. Nothing recorded." | A guessed history |
Generic only: no employer names, private hosts, or work-only tools.
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.

