Page 30 of 70
This page is one part of The Ishoo manual. The complete manual is a single page, short enough to read in one go: ishoo.app/docs/
Decisions
Decisions stay made when they're written down where every agent looks. In Ishoo, when you settle a lasting choice, your agent offers to record it as a decision file: what was decided, why, and what was rejected. Agents find decisions when they search the project, and a replaced one names its successor.
The most expensive thing an agent can forget is a reason. You spent an afternoon deciding not to use a database; three weeks later a fresh session, seeing a slow file read, helpfully adds one. Nothing told it the question was settled, or why.
A decision in Ishoo is a short Markdown file in docs/decisions/, landed like code. Your agent offers to write one when you settle something a later agent might reverse. You say yes or no; it never files one unasked.
Set becomes to the test that enforces the decision (test:<name>), an active product rule such as product.13, or history to keep the reasons for later. If Ishoo cannot find the target, it saves the decision and gives one nudge.
What a decision file holds#
+++
id = "DEC-07"
title = "Project memory is pull-first: a tiny pushed map, then scoped keyword search"
status = "accepted"
area = "rules"
scope = ["src/memory.rs", "src/rules.rs"]
supersedes = []
superseded_by = []
+++
## Context
Agents forget between sessions; classic Ishoo pushed matched decisions into every filing…
## Decision
Push only a small map at claim time. Agents pull everything else with ishoo_find…
## Why
More context makes coding agents worse even when it's relevant…
## Alternatives
Embedding-matched pushes (missed a third of what applied); a memory platform as the store…
## Consequences
CLAUDE.md stays tiny. Search must rank well for the files in play…| Part | What goes in it |
|---|---|
| Context | The situation that forced a choice. |
| Decision | What was chosen, plainly enough to check code against. |
| Why | The reasons. Required: a decision without its why gets undone by the first agent with a good-sounding argument. |
| Alternatives | What was considered and rejected, and why. Required: this is what stops the same idea being proposed again. |
| Consequences | What follows: what gets easier, harder, or now has to be true. |
How agents meet them#
- In search. Decisions are records
ishoo_findreturns, ranked higher for the files in their area. - Through rules. A rule can end with the decision behind it, like “(DEC-07)”, so the agent handed the rule at claim can follow it to the reason.
- In the window. The Decisions view groups them by area, those in force first. Open one to read it, with links to what it replaced and what replaced it.
Changing your mind#
Decisions are never edited into saying something else. A new decision supersedes the old one, and both files stay, linked both ways, so the history of the choice is readable. Anything that still cites the old one gets a one-line nudge naming the new one; see Citation checks.
NoteRoutine implementation choices aren't decisions; they live in the code and the landing note. Ishoo can't force a model to obey a decision, but it makes it easy to find, ranks it in search, and flags text that cites a replaced one, so the agent has no excuse not to know.