dira decision memory for AI coding agents
$dira whydec-0013
int-0003Replace the tool pile — kazi + dira + a subset of skills is the whole stackactive 2026-07-30
dec-0013The /sitrep skill is dira's validated query-surface spec, and its first replacement targetaccepted 2026-07-30
✗ Treat /sitrep as an unrelated reporting tool and design dira's output from scratchIt would discard a specification that has already been tested across roughly a dozen parallel sessions against a real reader with real time pressure.
✗ Have dira absorb the whole report, verdict and risks includedThe verdict ("stalling: everything is queued behind one red CI job"), the weighted percentage, the risk list and the trend delta are judgement and synthesis, not derivation.
int-0003Replace the tool pile — kazi + dira + a subset of skills is the whole stack
dec-0013The /sitrep skill is dira's validated query-surface spec, and its first replacement target
✗Treat /sitrep as an unrelated reporting tool and design dira's output from scratch
✗Have dira absorb the whole report, verdict and risks included
dec-0013 ◆ accepted 2026-07-30

Arising from int-0003 — Replace the tool pile — kazi + dira + a subset of skills is the whole stack

The /sitrep skill is dira's validated query-surface spec, and its first replacement target

`~/.claude/skills/sitrep` is a prose specification of dira's query surface, executed by an LLM re-reading markdown each time instead of by a query engine over structured entries. Its ledger mode maps onto the entry model almost one-to-one — decisions with provenance, parks *with their revival trigger*, reversals, routed open questions, not-yet-planned work, and merged-versus-verified — and it states dira's own purpose independently: that a fresh session cannot tell a ratified decision from a plausible suggestion an agent made once, so it re-argues settled things or builds on unagreed ones.

Two of its rules exist **only** because the data is unstructured, and dissolve rather than transfer: the no-bare-IDs rule is an artifact of ids living in one file and their descriptions in another, and "never from memory alone, verify anything surprising" is `dec-0004`'s derived-never-stored done by hand.

Four invariants this makes explicit

The design assumed these; the skill proves they are load-bearing. Each is checkable.

1. **No bare refs in output.** Any ref emitted by `brief`, `map`, `why`, or `check` carries its title in the same breath. A reader who has never opened the ledger must understand every line without looking anything up. 2. **Provenance is displayed, not merely stored.** On any surface a human disposes from, a human-confirmed decision must be visually distinguishable from an agent-staged guess. `source.tier` and `confirmed_by` exist in the schema; nothing said they must render, and an unrendered provenance field is the exact failure the skill's "never report a subagent's claim as fact" rule guards against. 3. **A deferral with no revival trigger is reported as a defect.** The skill's phrasing is the correct one: *a park without a trigger is not a decision, it is forgetting with better vocabulary.* This is the open gap where nine recorded `revisit_if` conditions sit inert with nothing watching them — the skill independently identifies the same defect class, which is what promotes it from a nice-to-have to a requirement. 4. **Contradictions are surfaced, never silently resolved.** Where two records conflict, both are named and neither is quietly preferred. This is `dira check`, and it extends to `map` and `brief`: a derived view that hides a conflict to look tidy is worse than one that reports it.

The boundary — what dira must never take

dira derives the **states**. The human keeps the **verdict**: the trajectory sentence, the weighted percentage, the risk list, the trend against the last report. Those are synthesis, and taking them would need a narrative field that `cst-0002` forbids for good reason — a compass reports a bearing, it does not tell you how the voyage is going.

So the replacement is not "dira prints the sitrep." It is: `/sitrep` shrinks to a thin judgement layer over `dira map` plus `gh`, and stops re-deriving state by hand.

Why this is the first replacement target

`int-0003` has been the vaguest intent in the ledger — "at least two tools are uninstalled and not missed" names no tool and no date, so nothing could falsify it. `/sitrep` is a concrete, daily-used, self-owned surface whose manual labour is exactly what dira automates, and whose correctness is verifiable against reports already written. It is the honest first dogfood: if dira cannot reduce this skill, the tool-reduction thesis is weaker than claimed.

The measurable form: the skill's gather phase currently reads `docs/plan.md`, `docs/roadmap.md`, `gh pr list`, claim refs and prior reports, then hand-glosses every id. When `dira map` supplies the four states with titles and provenance attached, that phase reduces to two calls — and the report that produced this entry, written entirely by hand, becomes the before-measurement.

Alternatives on record — 2

✗Treat /sitrep as an unrelated reporting tool and design dira's output from scratchrefused It would discard a specification that has already been tested across roughly a dozen parallel sessions against a real reader with real time pressure.

The skill's rules are not preferences — each one is scar tissue from a report that failed to be usable. Re-deriving them from first principles would mean rediscovering the same failures more slowly.

✗Have dira absorb the whole report, verdict and risks includedrefused The verdict ("stalling: everything is queued behind one red CI job"), the weighted percentage, the risk list and the trend delta are judgement and synthesis, not derivation.

Absorbing them would require a sixth entry kind or a narrative field, which cst-0002 exists to prevent — and it would put dira in the business of telling the operator how it is going, which is not a compass, it is an opinion.

revisit ifnever for the verdict; a derived risk signal with a numeric threshold would be a different proposal

Every decision in this repo is recorded like this one.

Keep your own →