Troubleshooting Memory

The plugin keeps a small, auto-maintained notes file for each project at .rn-agent/local/troubleshooting.md. The agent reads it at the start of a session so it begins knowing this repo’s quirks, and updates it at the end of a session when tool calls failed — so the next session doesn’t re-hit the same wall.

What	A two-section markdown file: Configuration & How-To (repo-specific facts) and Troubleshooting (failure→resolution gotchas).
Where	.rn-agent/local/troubleshooting.md — gitignored, per-developer, never committed.
Read	Injected into the agent’s context at SessionStart (when it has real content).
Written	A Stop hook asks the agent to merge new failures into it once per session.
Captured by	A PostToolUseFailure hook that records redacted failure records to a session buffer.
Why	Known gotchas and config are remembered across sessions instead of being rediscovered each time.

Replaces the Experience Engine

This feature supersedes the earlier global “Experience Engine” (~/.claude/rn-agent/experience.md plus the /rn-agent-compact, /rn-agent-health, /rn-agent-export, and /rn-agent-import commands), which had no working on-demand entry point and whose read path was never wired up. The replacement is repo-scoped, read at session start, and needs no manual command — see GH #200.

Why it exists

An LLM agent driving your app re-discovers the same friction every session: which directory Metro must start from, that a store is exposed under a non-obvious global, that one screen’s testIDs are camelCase while the rest are kebab-case. It also re-hits the same failures — a CDP reconnect dance after a Metro restart, a deep link that only works once a gate is dismissed.

None of that is worth re-deriving. The troubleshooting memory captures it once and feeds it back. It is the same idea as Actions — turn a one-time discovery into a cheap, reused artifact — applied to knowledge rather than flows.

What’s in the file

The agent maintains two sections:

# rn-dev-agent — local notes for this repo   (auto-maintained, gitignored)

## Configuration & How-To
- Metro: start from `apps/mobile` (not the repo root) or the Dev Client bundle 404s
- Stores: __ZUSTAND_STORES__ exposes { cartStore, authStore }
- testIDs: kebab-case; screens suffixed `-screen`
- Auth: deeplink `myapp://login?token=` bypasses the OTP gate

## Troubleshooting
### cdp_status fails after Metro restart
- Symptom: "CDP connection failed"; Cause: stale CDP target after HMR
- Fix: cdp_reload(full=true) then cdp_status   ·  last seen 2026-06-01

The doc is kept under ~2000 tokens; when it grows past that, the agent prunes the stalest, least-recently-seen entries so the session-start injection stays cheap.

How it works

Three hooks cooperate around one file — capture is deterministic, synthesis uses the agent’s judgement, and the read happens automatically.

1. Capture (deterministic). When an rn-dev-agent MCP tool call fails, a PostToolUseFailure hook appends a record — tool name, a computed diagnostic (e.g. “Metro not running”), and the redacted error text — to .rn-agent/local/session-buffer.jsonl. Secrets and PII are scrubbed before anything touches disk.

2. Synthesize (agent). When the session ends and the buffer has new records, a gated Stop hook asks the agent to merge them into troubleshooting.md: write clean gotchas under Troubleshooting, record any new repo facts under Configuration & How-To, dedupe, and prune to budget. It fires at most once per session.

3. Read (automatic). At the next SessionStart, the hook that detects your RN project injects the file’s content (when it has real content beyond the template) so the agent starts informed.

It's gitignored on purpose

The file lives under .rn-agent/local/, which the plugin adds to .rn-agent/.gitignore. It’s per-developer working memory, not a shared artifact — so it never shows up in your PRs. (Contrast Actions, which are committed and shared.)

Privacy

The capture hook redacts before writing: bearer tokens, API keys, GitHub/AWS/Slack/Google token shapes, JWTs, key=value secrets, private-key PEM blocks, and emails are replaced with [REDACTED_SECRET] / [PII_REDACTED]. Redaction runs before truncation so a secret can’t leak at a size boundary. The buffer is local and gitignored, but it is scrubbed regardless.

You don’t run anything

There is no command to invoke. Capture, synthesis, and read are all hook-driven. If a Stop hook ever asks you to update the file, let the agent do it — keep entries concise. To start fresh, delete .rn-agent/local/troubleshooting.md; it is re-scaffolded on the next session.