MEMORY

AGENT MEMORY

Generalized reusable lessons from agent sessions. Root causes converted into preventive rules, not incident-specific notes. Entries are h3 headers with [ACTIVE|RETIRED] status. Content: brief, grep-friendly, MECE across sections. Style: one-liner per entry, optional sub-bullets for context.

Preventive Rules

Learn Both Sides' Intent, Plans And Gates Before Merging; A Found Failure Is Fixed, Whoever Introduced It [ACTIVE]

Before resolving any conflict, read the branch's handoff/execution state, its plans and its acceptance gates, and main's incoming changes in full, not commit titles. Re-assess every resolution against both intents, then run the branch's gates. A failure found during the work is diagnosed to its root cause and fixed; "pre-existing" or "not from the merge" is never a reason to skip it.

Absence From This Repo Is Not Proof A Referenced Thing Does Not Exist [ACTIVE]

Before calling a reference dangling, establish what it is FOR. `/goal` and `/advisor` are Claude Code features the user sets; `graphify` is a third-party skill installed via `graphify install`. None is defined in this repo by design. Web-search and read `docs/definitions/workflows.md` first. Six issues in one batch rested on this error, and acting on them deleted working features.

Spec-First Components: Search Requirements Before Saying A Concept Does Not Exist [ACTIVE]

For `src/rosettify-plugins` and other requirements-first components, "not in code" ≠ "not in the design". Before claiming a mechanism does not exist, grep `docs/REQUIREMENTS/<component>/` for its domain terms and synonyms (priority → order, OrderToken, sort). Report status precisely: specified + `NotStarted` is not the same as absent. Failure: told the user "no priority token" while `FR-ARCH-0022 OrderToken` was specified and unimplemented.

Hand-Formatted JSON: Edit Text, Never Re-Serialize The Whole File [ACTIVE]

Repo JSON (e.g. `docs/definitions/live_counts.json`, `plugins.json`) uses hand-chosen inline arrays/objects. `json.dump` of the whole file rewrites hundreds of lines and hides the real change in review. Insert or replace the exact lines as text, then `git diff --stat` must show only the intended lines.

Prescriptive Schemas Outrank Observed Patterns [ACTIVE]

When an instruction file looks wrong, check `docs/schemas/*.md`, `instructions/r*/core/templates/shell-schemas/*.md`, and the sibling `README.md` "Invariants" section before changing it. A line repeated verbatim across many files is a convention, not a defect — `All Rosetta prep steps MUST be FULLY completed, load-project-context skill loaded and fully executed` is mandated by all three schemas and `skills/coding/README.md` forbids rewording it locally.

HITL Applies At Workflow Gates, Not Every Internal Mechanic [ACTIVE]

Proceed through read-only discovery, analysis, delegation, retries, and draft refinement; ask only at the workflow's defined approval or material-risk gates.

Multi-File Patches Require Fresh Exact Context Per Target [ACTIVE]

Before a multi-file patch, read each target's exact surrounding lines and split unrelated edits; one stale hunk otherwise rejects the entire patch.

Subagent Fork And Role Compatibility Must Be Resolved Before Dispatch [ACTIVE]

Full-history forks cannot override `agent_type`; use a bounded/empty fork for a role override. Runtime role availability may be narrower than the advertised catalog, so use an untyped agent with the required role contract in its prompt when a named type is rejected.

Fixing Someone's Artifact = Touch Only The Named Defect; Never Reword Their Notes Or Resolve Their Open Questions [ACTIVE]

When asked to "fix issues/inconsistencies" in a user's artifact (diagram, doc, code), change ONLY the specific defects and preserve the author's wording, decided content, and especially their "to think/discuss"/open-question notes — verbatim. Their notes and questions are never mine to resolve or rephrase. A vague "fix it" is NOT license to rewrite in my voice or auto-resolve open questions; when scope is unclear do the minimal literal fix or ask, and never use `replace_all` on a shared label without confirming blast radius. Root cause: on a broad "fix inconsistencies" directive I rewrote the user's "To think/discuss" note and rephrased several diagram cells in my own words, mangling an un-versioned artifact. Rule: edit the named defect only; leave authored prose, notes, and questions untouched.

Answered Decisions And Style Edits Are Review, Not Approval To Implement [ACTIVE]

A user answering design questions, picking options, or giving wording/style edits is REVIEWING — it is not authorization to write artifacts. "Design resolved" and "approved to implement" are separate gates. Treat as approval ONLY an explicit approval sentence; anything else (questions, picks, edits, refinements) keeps status pre-approval. Before any create/edit/delete of artifacts, hold for explicit approval. Root cause: I collapsed AskUserQuestion answers + style feedback into a green light and edited a skill and the always-on bootstrap unapproved. Rule: never conflate the decision gate with the approval gate; on mismatch stop immediately and revert my own just-made unapproved writes.

Never Convert A User's Rationale Into An AI-Side Decision Heuristic — HITL Gates Present, User Decides [ACTIVE]

When the user EXPLAINS why a capability exists (e.g. "code-graph navigation is only needed if code is large or for migration"), that is context for ME, not a condition for the AI to auto-evaluate and self-gate on. A HITL gate must surface the capability and let the USER choose ("we have this built in — your choice"), never silently decide for them. Also: the agent must NOT infer/search for environmental state it cannot reliably know (e.g. "is the code indexed?"). It may only report what is ALREADY present in the current context (registered LSPs, semantic-search/index MCP tools) WITHOUT going to look for it,