Project memory / Page 44 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/
Rule, decision or issue?
A rule says how something must be done now, in a sentence. A decision says why a lasting choice was made and what was rejected. An issue is one piece of work with its check, and keeps what landed. If a later agent might reverse it, record a decision; if every agent touching those files must follow it, write a rule.
| Rule | Decision | Issue | |
|---|---|---|---|
| Says | What to do | Why, and what was rejected | What to change, and how to prove it |
| Length | A sentence or two | A page | A paragraph |
| Lives | docs/rules/ | docs/decisions/ | The store |
| Changes | Edited in place, repealed by pointer | Superseded by a newer decision | Done, or let go with a reason |
| An agent meets it | At claim, for its files | In search, and cited by rules | In search, status and the plan |
One choice, three records#
Say you tell your agent: “Never push our issues to the code's remote. It's public and the plans are private.” A good agent offers to record it, and the result is three linked pieces:
The decision
DEC-10: Keep records local by default. Context: a public remote could publish private plans. Decision: sync only to a place the person chose. Why, what was rejected (pushing to the code remote automatically), and what follows from it.The rule
sync.3 Sync only to a place the person chose; never to the code remote (DEC-10).One sentence, in the sync area, so every agent touching sync code is handed it.The issue
The work that made the code obey, with its check and the landing that shipped it. Search finds it when someone asks “why can't the store go to origin?”
Months later an agent working on sync is handed sync.3 at claim. If it wants to know why, the rule points to the decision. If someone supersedes the decision, Ishoo flags every text that still cites the old one.
NoteNot every choice is a decision. Routine implementation choices stay in the code and the landing note. A decision is for something a later agent might otherwise undo.