From a319e828ef7174522a25db4ddd19ad423edc884e Mon Sep 17 00:00:00 2001 From: Myles Scolnick Date: Fri, 24 Apr 2026 10:37:58 -0400 Subject: [PATCH 1/5] retro pair --- .claude-plugin/marketplace.json | 3 +- README.md | 4 + skills/retro-marimo-pair/SKILL.md | 128 ++++++++++++++++++ .../reference/code-mode-surface.md | 62 +++++++++ 4 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 skills/retro-marimo-pair/SKILL.md create mode 100644 skills/retro-marimo-pair/reference/code-mode-surface.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a828dc7..ad7e2e8 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -14,7 +14,8 @@ "description": "Pair programming protocol for marimo notebooks", "source": "./", "skills": [ - "./" + "./", + "./skills/retro-marimo-pair" ] } ] diff --git a/README.md b/README.md index 7e934dd..7f37bd0 100644 --- a/README.md +++ b/README.md @@ -72,3 +72,7 @@ paths to the scripts from the installed skill and add them to your } } ``` + +## Contributing + +We'd love your help in improving this skill. Please use the `/retro-marimo-pair` after a marimo pair session to provide feedback on how we can improve the skill and file an issue on the [GitHub repository](https://github.com/marimo-team/marimo-pair/issues). diff --git a/skills/retro-marimo-pair/SKILL.md b/skills/retro-marimo-pair/SKILL.md new file mode 100644 index 0000000..f739715 --- /dev/null +++ b/skills/retro-marimo-pair/SKILL.md @@ -0,0 +1,128 @@ +--- +name: retro-marimo-pair +description: >- + Session retrospective for improving marimo-pair and marimo._code_mode. + Use when the user wants to analyze friction from a pairing session, identify + what went wrong, and brainstorm improvements to the skill docs or the + underlying API. Trigger on: "retro", "what went wrong", "improve the skill", + "session review", "friction", or /retro-pair. +--- + +# Session Retrospective + +You are helping a **marimo team member** review a pairing session to find +friction and turn it into improvements. The target is always one or both of: + +1. **The marimo-pair skill** (`~/github/marimo-team/marimo-pair/`) +2. **`marimo._code_mode`** — the underlying notebook metaprogramming API + +This is a **conversation**, not an automated report. You surface findings, +the user steers which ones matter, and together you decide what to do about +them. + +## Guard Rails + +- **NEVER** edit files in `~/github/marimo-team/marimo-pair/` without explicit + user approval. +- **ALWAYS** start with session analysis (Step 1) — do not jump to solutions. +- **Present friction points before root causes** — let the user choose which + ones to dig into. +- If the user invoked with a specific complaint, focus your analysis there but + still scan for other friction in the background. + +## Step 1: Session Analysis + +Review the current conversation and identify friction. Look for: + +| Signal | What to look for | +|--------|-----------------| +| **User frustration** | Corrections ("no not that"), repeated attempts, backtracking, confusion, tone shifts | +| **Inefficiency** | Multiple rounds for a one-step task, over-engineering, wrong API usage | +| **Errors** | Compile-check failures, runtime errors, silent failures, wrong output | +| **Workarounds** | User or Claude working around a limitation instead of doing it directly | +| **Context loss** | Claude forgetting instructions from earlier, re-asking things the skill covers | + +Present a numbered summary of friction points found. For each, note: +- What happened (brief) +- Where in the conversation it occurred (quote or paraphrase) +- Initial category guess (skill structure / skill gap / API issue / etc.) + +Then ask: **"Which of these should we dig into? Or is there something I missed?"** + +## Step 2: Root Cause Discussion + +For each friction point the user selects, work through these lenses: + +| Lens | Question | Example improvement | +|------|----------|-------------------| +| **Skill structure** | Was the right info in the skill but hard to find? Buried in reference/ when it should be in SKILL.md? | Promote to guard rail, restructure progressive disclosure | +| **Skill gap** | Was information missing entirely from the skill? | Add new section, example, or anti-pattern | +| **Misleading docs** | Did the skill say something that led Claude astray? | Correct the docs, add clarifying examples | +| **API ergonomics** | Was `_code_mode` clunky or unintuitive for this task? | Propose API improvement (better defaults, clearer errors) | +| **Missing API** | Is there something `_code_mode` simply can't do that it should? | Design a new API surface | +| **API bug** | Did `_code_mode` behave incorrectly? | Characterize the bug, propose fix or workaround | +| **Context window** | Did Claude forget instructions due to long context? | Shorter, more prominent guard rails | + +Discuss each lens briefly, then converge on the most likely root cause with the +user. It's okay to have multiple contributing causes. + +## Step 3: Brainstorm Solutions + +Based on the root cause, brainstorm concrete next steps. Possible outputs: + +- **Skill edit** — Draft changes to SKILL.md or reference/ files, discuss with + user, optionally apply (Step 4) +- **API design sketch** — Propose what a better `_code_mode` API would look + like for this case, with code examples +- **Issue draft** — Write up a bug report or feature request for marimo + (the user decides where to file it) +- **Pattern/recipe** — Document a new pattern that should be added to the + skill's reference docs +- **No action** — Sometimes the discussion itself is the value + +Present options and let the user choose. Multiple outputs are fine. + +## Step 4: Apply (if agreed) + +### For skill edits + +1. Read the target file in `~/github/marimo-team/marimo-pair/` +2. Show the proposed diff to the user +3. Only apply after explicit sign-off +4. After applying, verify SKILL.md stays under 500 lines (reference/ files + have no limit) + +### For API proposals or issues + +1. Write it up clearly with: + - **Problem:** What happened and why it's painful + - **Current behavior:** What `_code_mode` does today + - **Proposed behavior:** What it should do instead + - **Example code:** Before/after snippets +2. Leave it for the user to action — do not auto-file + +### Wrapping up + +After completing the cycle for the selected friction points, ask if the user +wants to revisit any remaining items from Step 1, or if the retro is done. + +## Key Files Reference + +| File | Purpose | +|------|---------| +| `~/github/marimo-team/marimo-pair/SKILL.md` | Main skill instructions | +| `~/github/marimo-team/marimo-pair/reference/execute-code.md` | Scratchpad & cell operation recipes | +| `~/github/marimo-team/marimo-pair/reference/rich-representations.md` | Widget & display patterns | +| `~/github/marimo-team/marimo-pair/scripts/` | Bundled discovery & execution scripts | + +To inspect the live `_code_mode` API surface during a retro, the user can +run in their notebook scratchpad: + +```python +import marimo._code_mode as cm + +async with cm.get_context() as ctx: + # List all public methods/attributes + print([x for x in dir(ctx) if not x.startswith('_')]) + help(ctx) +``` diff --git a/skills/retro-marimo-pair/reference/code-mode-surface.md b/skills/retro-marimo-pair/reference/code-mode-surface.md new file mode 100644 index 0000000..77926eb --- /dev/null +++ b/skills/retro-marimo-pair/reference/code-mode-surface.md @@ -0,0 +1,62 @@ +# `marimo._code_mode` API Surface + +> This is a **point-in-time snapshot** for retro discussions. The live API may +> differ — always verify with `dir(ctx)` and `help()` in the running session. + +## Entry Point + +```python +import marimo._code_mode as cm + +async with cm.get_context() as ctx: + ... # all operations go here +``` + +The `async with` is mandatory — without it, operations silently do nothing. +The context manager auto-compile-checks on exit: syntax errors, multiply-defined +names, and cycles are caught before any graph mutation occurs. + +## Context Object (`ctx`) + +### Reading State + +| Attribute / Method | Returns | Notes | +|-------------------|---------|-------| +| `ctx.cells` | List of cell objects | Each has `.cell_id`, `.code`, `.name` | +| `ctx.graph` | Kernel graph | Has refs/defs info (cells themselves lack this) | +| `dir(ctx)` | All attributes | Always check this first — API evolves | + +### Cell Operations (Mutating) + +| Operation | Method | Notes | +|-----------|--------|-------| +| Create cell | `ctx.create_cell(code, ...)` | Adds to graph, auto-compile-checks | +| Update cell | `ctx.update_cell(cell_id, code, ...)` | Edits existing cell in-place | +| Delete cell | `ctx.delete_cell(cell_id)` | Confirm with user first | +| Move cell | `ctx.move_cell(cell_id, ...)` | Reorder in notebook | + +### Execution + +| Operation | Method | Notes | +|-----------|--------|-------| +| Execute code (scratchpad) | Via `execute-code.sh` or MCP | Results return to Claude, not user | +| Execute cell | Happens automatically after cell ops | Unless `code_is_stale=True` | + +### Package Management + +| Operation | Method | Notes | +|-----------|--------|-------| +| Install package | Explore via `dir(ctx)` | Prefer API over `uv add` | + +## Known Friction Points + +Track recurring issues here as they surface in retros: + +- **Compile-check false positives on delete+create:** When deleting a cell and + creating a replacement that defines the same variables, the compile check can + see the old definitions still present and reject the new cell. Workaround: + use `check=False` or `update_cell` instead of delete+create. + +- **`ctx.cells` lacks refs/defs:** Cell objects don't expose which variables + they reference or define. Must use `ctx.graph` directly for variable flow + analysis. From 5e74dc14bc81ca9245d1a2e8e793a203f9f1bd6e Mon Sep 17 00:00:00 2001 From: Myles Scolnick Date: Fri, 24 Apr 2026 10:48:50 -0400 Subject: [PATCH 2/5] Update skills/retro-marimo-pair/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- skills/retro-marimo-pair/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/retro-marimo-pair/SKILL.md b/skills/retro-marimo-pair/SKILL.md index f739715..d0eabbb 100644 --- a/skills/retro-marimo-pair/SKILL.md +++ b/skills/retro-marimo-pair/SKILL.md @@ -5,7 +5,7 @@ description: >- Use when the user wants to analyze friction from a pairing session, identify what went wrong, and brainstorm improvements to the skill docs or the underlying API. Trigger on: "retro", "what went wrong", "improve the skill", - "session review", "friction", or /retro-pair. + "session review", "friction", or /retro-marimo-pair. --- # Session Retrospective From 60fe51f7f54384938d38656b0ccc01c19b66103e Mon Sep 17 00:00:00 2001 From: Myles Scolnick Date: Fri, 24 Apr 2026 10:49:05 -0400 Subject: [PATCH 3/5] Update skills/retro-marimo-pair/reference/code-mode-surface.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- skills/retro-marimo-pair/reference/code-mode-surface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/retro-marimo-pair/reference/code-mode-surface.md b/skills/retro-marimo-pair/reference/code-mode-surface.md index 77926eb..5ad7630 100644 --- a/skills/retro-marimo-pair/reference/code-mode-surface.md +++ b/skills/retro-marimo-pair/reference/code-mode-surface.md @@ -40,7 +40,7 @@ names, and cycles are caught before any graph mutation occurs. | Operation | Method | Notes | |-----------|--------|-------| | Execute code (scratchpad) | Via `execute-code.sh` or MCP | Results return to Claude, not user | -| Execute cell | Happens automatically after cell ops | Unless `code_is_stale=True` | +| Execute cell | `ctx.run_cell(...)` | Explicitly queue execution; `create_cell` / `update_cell` are structural only and do not auto-execute | ### Package Management From 5e1c8b3bc50ea176b69c534c14337b5b2c6b0747 Mon Sep 17 00:00:00 2001 From: Myles Scolnick Date: Fri, 24 Apr 2026 10:49:13 -0400 Subject: [PATCH 4/5] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7f37bd0..2826471 100644 --- a/README.md +++ b/README.md @@ -75,4 +75,7 @@ paths to the scripts from the installed skill and add them to your ## Contributing -We'd love your help in improving this skill. Please use the `/retro-marimo-pair` after a marimo pair session to provide feedback on how we can improve the skill and file an issue on the [GitHub repository](https://github.com/marimo-team/marimo-pair/issues). +We'd love your help in improving this skill. After a marimo pair session, +please run the `/retro-marimo-pair` command to share feedback on how we can +improve the skill. You can also file an issue on the +[GitHub repository](https://github.com/marimo-team/marimo-pair/issues). From 5f9f290aeb8f8bee60f6554f02bfec32f0ee455b Mon Sep 17 00:00:00 2001 From: Myles Scolnick Date: Fri, 24 Apr 2026 10:51:53 -0400 Subject: [PATCH 5/5] comments --- skills/retro-marimo-pair/SKILL.md | 14 +++++++------- .../reference/code-mode-surface.md | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/skills/retro-marimo-pair/SKILL.md b/skills/retro-marimo-pair/SKILL.md index d0eabbb..e0add15 100644 --- a/skills/retro-marimo-pair/SKILL.md +++ b/skills/retro-marimo-pair/SKILL.md @@ -13,7 +13,7 @@ description: >- You are helping a **marimo team member** review a pairing session to find friction and turn it into improvements. The target is always one or both of: -1. **The marimo-pair skill** (`~/github/marimo-team/marimo-pair/`) +1. **The marimo-pair skill** (`github://marimo-team/marimo-pair`) 2. **`marimo._code_mode`** — the underlying notebook metaprogramming API This is a **conversation**, not an automated report. You surface findings, @@ -22,7 +22,7 @@ them. ## Guard Rails -- **NEVER** edit files in `~/github/marimo-team/marimo-pair/` without explicit +- **NEVER** edit files in `github://marimo-team/marimo-pair` without explicit user approval. - **ALWAYS** start with session analysis (Step 1) — do not jump to solutions. - **Present friction points before root causes** — let the user choose which @@ -86,7 +86,7 @@ Present options and let the user choose. Multiple outputs are fine. ### For skill edits -1. Read the target file in `~/github/marimo-team/marimo-pair/` +1. Read the target file in `github://marimo-team/marimo-pair` 2. Show the proposed diff to the user 3. Only apply after explicit sign-off 4. After applying, verify SKILL.md stays under 500 lines (reference/ files @@ -110,10 +110,10 @@ wants to revisit any remaining items from Step 1, or if the retro is done. | File | Purpose | |------|---------| -| `~/github/marimo-team/marimo-pair/SKILL.md` | Main skill instructions | -| `~/github/marimo-team/marimo-pair/reference/execute-code.md` | Scratchpad & cell operation recipes | -| `~/github/marimo-team/marimo-pair/reference/rich-representations.md` | Widget & display patterns | -| `~/github/marimo-team/marimo-pair/scripts/` | Bundled discovery & execution scripts | +| `github://marimo-team/marimo-pair/SKILL.md` | Main skill instructions | +| `github://marimo-team/marimo-pair/reference/execute-code.md` | Scratchpad & cell operation recipes | +| `github://marimo-team/marimo-pair/reference/rich-representations.md` | Widget & display patterns | +| `github://marimo-team/marimo-pair/scripts/` | Bundled discovery & execution scripts | To inspect the live `_code_mode` API surface during a retro, the user can run in their notebook scratchpad: diff --git a/skills/retro-marimo-pair/reference/code-mode-surface.md b/skills/retro-marimo-pair/reference/code-mode-surface.md index 5ad7630..29c1076 100644 --- a/skills/retro-marimo-pair/reference/code-mode-surface.md +++ b/skills/retro-marimo-pair/reference/code-mode-surface.md @@ -31,7 +31,7 @@ names, and cycles are caught before any graph mutation occurs. | Operation | Method | Notes | |-----------|--------|-------| | Create cell | `ctx.create_cell(code, ...)` | Adds to graph, auto-compile-checks | -| Update cell | `ctx.update_cell(cell_id, code, ...)` | Edits existing cell in-place | +| Edit cell | `ctx.edit_cell(cell_id, code, ...)` | Edits existing cell in-place | | Delete cell | `ctx.delete_cell(cell_id)` | Confirm with user first | | Move cell | `ctx.move_cell(cell_id, ...)` | Reorder in notebook | @@ -40,7 +40,7 @@ names, and cycles are caught before any graph mutation occurs. | Operation | Method | Notes | |-----------|--------|-------| | Execute code (scratchpad) | Via `execute-code.sh` or MCP | Results return to Claude, not user | -| Execute cell | `ctx.run_cell(...)` | Explicitly queue execution; `create_cell` / `update_cell` are structural only and do not auto-execute | +| Execute cell | `ctx.run_cell(cell_id)` | Explicitly queue execution; `create_cell` / `edit_cell` are structural only and do not auto-execute | ### Package Management @@ -55,7 +55,7 @@ Track recurring issues here as they surface in retros: - **Compile-check false positives on delete+create:** When deleting a cell and creating a replacement that defines the same variables, the compile check can see the old definitions still present and reject the new cell. Workaround: - use `check=False` or `update_cell` instead of delete+create. + use `check=False` or `edit_cell` instead of delete+create. - **`ctx.cells` lacks refs/defs:** Cell objects don't expose which variables they reference or define. Must use `ctx.graph` directly for variable flow