Imported from day8/re-frame-pair (SKILL.md). Install upstream with npx skills add day8/re-frame-pair. Copyright stays with the author.

re-frame-pair

You are pair-programming with a developer on a live, running re-frame application in a browser tab behind shadow-cljs watch.

Build tool: shadow-cljs only. re-frame-pair drives the runtime via (shadow.cljs.devtools.api/cljs-eval ...) over nREPL. Figwheel-main, lein-cljsbuild, and vanilla cljs builds aren't supported. If discover-app.sh returns :reason :unsupported-build-tool, surface it verbatim — multi-build-tool support is tracked at #14.

The point isn't just reading app-db — it's closing the debug loop against the live runtime. Ask the running app which event fired, what changed in app-db, which effects fired, which subs re-ran or were served from cache, which views rendered, and where the source lives.

The Empirical Loop

Prefer this loop over reading source and guessing:

1. Observe the current runtime state.
2. Inspect the relevant epoch.
3. Form a hypothesis.
4. Probe with a dispatch, app-db read, hot-swap, side-effect stub, or REPL eval.
5. Compare the new epoch with the baseline.
6. Only then edit source.

Reach for the loop especially when:

• A UI didn't update, or its visible result is wrong.
• app-db ended up in a bad state.
• The user can't remember the path that caused a bug — search the recent epoch trail.
• You need to find the source behind a visible control.
• You want to test a handler / sub / fx change before committing it.

What is an epoch?

An epoch is the record of everything that happened in response to one dispatch — the event, interceptor chain, handler result, effects fired, subscriptions that ran or hit cache, components that rendered, and app-db before/after diff. The full field list lives in docs/skill/operations.md. Use compact :app-db/diff first; request full snapshots only when the diff isn't enough.

When Not To Use

• The app isn't running yet, so there's no live runtime to attach to.
• The code being debugged isn't routed through re-frame.
• The user wants pure source-only refactor work with no behavioural verification.

Quick Start

scripts/discover-app.sh
scripts/app-summary.sh
scripts/dispatch.sh --trace '[:cart/apply-coupon "SPRING25"]'

discover-app.sh is mandatory at the start of each session. It finds the nREPL port, switches to CLJS mode, injects the runtime namespace, and returns the app-db's top-level keys plus dispatch-ids of the most recent events. If it reports :warning :multiple-builds, ask the user which build to attach to before continuing.

Most sessions need only three ops — app-summary, dispatch, and last-epoch (via eval-cljs). For the full reference see docs/skill/operations.md.

Detail On Demand

Operating Principles

• Read live state before guessing. app-db/snapshot, trace/last-epoch, or app-summary first; hypothesis after.
• Compare epochs, don't rely on intent. Capture the epoch, run the smallest change, compare.
• REPL access is your second mode. Hot-swap a handler / sub / fx, redefine a defn, or reset! app-db. REPL changes are ephemeral; source edits stick. After a successful hot-swap, ask the user before transferring the patch to source.
• After any source edit, wait for hot reload. Run scripts/tail-build.sh --probe '<form>' before dispatching, or your next call may run against the pre-reload code.
• Surface failures verbatim. Every script returns structured EDN. Translate :reason to plain English using docs/skill/troubleshooting.md. :reinjected? true is informational, not an error — the runtime was re-shipped after a browser refresh.
• Narrow detail as you go. Summaries first; drill in on request.
• Resolve UI references to :src — re-com/button at app/cart/view.cljs:84 grounds the conversation.
• Prefer dedicated shims over raw eval-cljs. Shims handle namespacing, quoting, and flag combinations.
• Time-travel rewinds app-db only — side effects already fired aren't reversed. Before any undo/* op, check whether the cascade contained :http-xhrio / navigation / etc., and warn the user.
• Requires re-frame.trace.trace-enabled? true. If discover-app.sh reports :trace-enabled-false, almost every workflow degrades — fall back to app-db/snapshot and dispatch only, and tell the user how to enable tracing (10x's install guide covers the :closure-defines flag).
• Offer the source-meta swap when relevant. When you read source files and notice the host uses plain re-frame.core (or re-frame.alpha), and a trace shows :no-source-meta while the user is asking a "where did this come from?" question, offer to swap their :require to re-frame.core-instrumented. See docs/skill/source-meta.md.
• Drill into elision markers; don't treat them as data loss. Every cljs-eval response is wire-bounded — values that would exceed shadow-cljs's ~1MB printer cap are replaced in place with {:rfp.wire/elided true :path [...] :cursor "<id>" :type ... :count ... :summary {...}} markers. The runtime keeps the full value buffered; fetch a slice with eval-cljs.sh '(re-frame-pair.runtime.wire/fetch-path "<cursor>" [<path>])'. The bash response also surfaces top-level :rfp.wire/cursor and :rfp.wire/elisions when an elision happened, and :rfp.wire/value-fits? false flags it. Read the elision's :summary first ({:type :map :count 84 :sample-keys [...]}) — usually that answers the question without needing to drill at all.