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

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, and present that as information to inform the user's decision. Root cause: I turned the user's explanatory rationale into an `IF (not indexed) AND (large OR migration)` AI gating condition, removing the human decision the user explicitly requested as HITL. Rule: explanations ≠ auto-conditions; decisions that belong to the user stay HITL; never assert unknowable environment state.

Docs State Facts/Guards Only — Never Narrate Reasoning Or Assert Unverified Tool Data-Flow [ACTIVE]

User-facing docs, install gates, and website state FACTS and GUARDS — never reasoning, never my own error-corrections, never unverified claims about what a third-party tool does with data ("sends your source to a third party" AND "runs locally" are both wrong moves: one is false, the other an unverifiable what-runs-where claim that creates liability if it changes). For a third-party tool the guard is liability-shaped and ownership-neutral: "Third-party tool will have access to IP. Review license and policy with your manager." — the manager/user reviews and agrees, not us. Non-MIT tools get a SECOND guard (the commercial-license fact, e.g. GitNexus free non-commercial / paid commercial). Root cause: I wrote "indexes your source code; your IP is exposed to a third party" (false — runs locally), then "runs locally" (unverified what-runs-where), and narrated my correction into the artifact. Rule: assert only verified facts; for third-party tools use the access-to-IP + review-with-manager guard instead of describing data flow; keep reasoning and mistake-corrections out of the document. Apply especially to public/website/init-gate docs.

Read Every File You Cite; Don't Dress Up Native Agent Mechanics As Rosetta Design [ACTIVE]

Rosetta's r3 runtime footprint is `bootstrap-alwayson.md` plus exactly one slim mode file (`mcp-files-mode.md` MCP xor `plugin-files-mode.md` plugin/standalone xor `local-files-mode.md` local development). Everything else (skills/workflows/agents) loads ON DEMAND; the host agent surfaces skill name+description and auto-loads matching skill bodies — that is NATIVE coding-agent behavior, NOT a Rosetta-injected "channel." Guardrail engagement is the compact actor list in `bootstrap-alwayson.md` plus always-visible skill descriptions. Process root cause: while reviewing `reduce-bootstrap.md` I (a) cited `pa-rosetta.md`/`pa-rosetta-intro-for-AI.md` as edit targets WITHOUT reading th