re-frame-pair

Category: Development & Coding | Uploader: day8 | Downloads: 0 | Version: v1.0（Latest）

Pair-program with a live re-frame application via shadow-cljs nREPL. Inspect app-db, dispatch events, hot-swap handlers, trace dispatches, read epoch data, time-travel, and perform post-mortems without source edits when probing. Use whenever the user asks about their running

Changelog: Source: GitHub https://github.com/day8/re-frame-pair

Directory Structure

Current level: tree/main/

📁 .beads/
- 📄 config.yaml 123 B
- 📄 metadata.json 158 B
📁 .claude-plugin/
- 📄 plugin.json 1.2 KB
📁 .github/
- 📁 workflows/
  - 📄 ci.yml 3.1 KB
  - 📄 release.yml 3.4 KB
📁 docs/
- 📁 skill/
  - 📄 debux.md 14.0 KB
  - 📄 operations.md 6.7 KB
  - 📄 post-mortems.md 2.0 KB
  - 📄 probing-and-hot-swap.md 2.8 KB
  - 📄 source-meta.md 3.7 KB
  - 📄 troubleshooting.md 4.0 KB
  - 📄 ui-debugging.md 2.4 KB
- 📄 handler-source-meta.md 4.9 KB
- 📄 initial-spec.md 49.5 KB
- 📄 LOCAL_DEV.md 6.8 KB
- 📄 TESTING.md 7.9 KB
📁 scripts/
- 📁 re_frame_pair/
  - 📁 runtime/
    
    📄 console.cljs 7.0 KB
    
    📄 dispatch.cljs 32.3 KB
    
    📄 dom.cljs 6.5 KB
    
    📄 epochs.cljs 13.6 KB
    
    📄 native_epoch.cljs 13.4 KB
    
    📄 re_com.cljs 3.7 KB
    
    📄 registrar.cljs 7.4 KB
    
    📄 session.cljs 1.2 KB
    
    📄 ten_x_adapter.cljs 32.0 KB
    
    📄 time_travel.cljs 6.8 KB
    
    📄 versions.cljs 5.6 KB
    
    📄 wire.cljs 13.7 KB
  - 📄 runtime.cljs 19.5 KB
- 📄 app-summary.sh 653 B
- 📄 console-tail.sh 893 B
- 📄 discover-app.sh 843 B
- 📄 dispatch.sh 1.3 KB
- 📄 eval-cljs.sh 595 B
- 📄 handler-source.sh 1.0 KB
- 📄 inject-runtime.sh 550 B
- 📄 ops.clj 73.3 KB
- 📄 tail-build.sh 1.3 KB
- 📄 trace-recent.sh 610 B
- 📄 watch-epochs.sh 1.3 KB
📁 tests/
- 📁 fixture/
  - 📁 public/
    
    📁 css/
    
    📄 bootstrap.css 144.0 KB
    
    📄 material-design-iconic-font.min.css 69.2 KB
    
    📄 re-com.css 38.6 KB
    
    📄 index.html 846 B
  - 📁 src/
    
    📁 app/
    
    📄 core.cljs 814 B
    
    📄 db.cljs 983 B
    
    📄 events.cljs 5.3 KB
    
    📄 subs.cljs 1.6 KB
    
    📄 views.cljs 7.5 KB
    
    📄 wrap_handler_smoke.cljs 3.6 KB
  - 📄 deps.edn 1.8 KB
  - 📄 package-lock.json 8.3 KB
  - 📄 package.json 397 B
  - 📄 README.md 8.4 KB
  - 📄 shadow-cljs.edn 1.2 KB
- 📁 probe/
  - 📄 probe_advanced.cljs 4.8 KB
- 📁 runtime/
  - 📄 fixtures.cljs 6.1 KB
  - 📄 runtime_test.cljs 148.9 KB
  - 📄 wire_test.cljs 10.5 KB
- 📄 ops_smoke.bb 68.1 KB
- 📄 skill_recipe_smoke.bb 16.8 KB
📄 .gitignore 459 B
📄 AGENTS.md 393 B
📄 CHANGELOG.md 8.4 KB
📄 CLAUDE.md 772 B
📄 CONTRIBUTING.md 5.2 KB
📄 deps.edn 3.1 KB
📄 LICENSE 1.0 KB
📄 package-lock.json 8.0 KB
📄 package.json 1.4 KB
📄 README.md 14.0 KB
📄 RELEASING.md 3.8 KB
📄 shadow-cljs.edn 1.8 KB
📄 SKILL.md 7.2 KB
📄 STATUS.md 9.3 KB

SKILL.md

---
name: re-frame-pair
description: >
  Pair-program with a live re-frame application via shadow-cljs nREPL.
  Inspect app-db, dispatch events, hot-swap handlers, trace dispatches,
  read epoch data, time-travel, and perform post-mortems without source
  edits when probing. Use whenever the user asks about their running
  re-frame app or mentions: re-frame, app-db, dispatch, subscribe,
  reg-event, reg-sub, reg-fx, epoch, interceptor, re-frame-10x, re-com,
  shadow-cljs.
allowed-tools:
  - Bash(scripts/discover-app.sh *)
  - Bash(scripts/app-summary.sh *)
  - Bash(scripts/eval-cljs.sh *)
  - Bash(scripts/console-tail.sh *)
  - Bash(scripts/handler-source.sh *)
  - Bash(scripts/inject-runtime.sh *)
  - Bash(scripts/dispatch.sh *)
  - Bash(scripts/trace-recent.sh *)
  - Bash(scripts/watch-epochs.sh *)
  - Bash(scripts/tail-build.sh *)
  - Read
  - Edit
  - Write
  - Grep
  - Glob
---

# 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`.

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`](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

```bash
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`](docs/skill/operations.md).

## Detail On Demand

| Question / task | Read |
|---|---|
| Operation names, command forms, epoch fields, console tags | [`docs/skill/operations.md`](docs/skill/operations.md) |
| Post-mortem — how did `app-db` get here? Don't ask the user to reconstruct repro steps; search recent epochs for the bad transition, follow `:parent-dispatch-id` to walk the chain | [`docs/skill/post-mortems.md`](docs/skill/post-mortems.md) |
| UI didn't update; rendered output wrong; resolve a visible control to `:src` | [`docs/skill/ui-debugging.md`](docs/skill/ui-debugging.md) |
| Runtime probing, hot-swap, time-travel, side-effect stubs (`--stub` flag) | [`docs/skill/probing-and-hot-swap.md`](docs/skill/probing-and-hot-swap.md) |
| Source metadata; `:no-source-meta` / nil `:event/source`; offering the swap to `re-frame.core-instrumented` | [`docs/skill/source-meta.md`](docs/skill/source-meta.md) |
| Form-by-form trace inside a handler / sub / fx (re-frame-debux — an optional source-printing instrumentation library) | [`docs/skill/debux.md`](docs/skill/debux.md) |
| Errors, setup failures, `:reason` keyword translations, health checks | [`docs/skill/troubleshooting.md`](docs/skill/troubleshooting.md) |

## 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`](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`](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.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

re-frame-pair

Directory Structure

SKILL.md

Report

Notice