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..2826471 100644 --- a/README.md +++ b/README.md @@ -72,3 +72,10 @@ paths to the scripts from the installed skill and add them to your } } ``` + +## Contributing + +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). diff --git a/skills/retro-marimo-pair/SKILL.md b/skills/retro-marimo-pair/SKILL.md new file mode 100644 index 0000000..e0add15 --- /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-marimo-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..29c1076 --- /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 | +| 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 | + +### Execution + +| Operation | Method | Notes | +|-----------|--------|-------| +| Execute code (scratchpad) | Via `execute-code.sh` or MCP | Results return to Claude, not user | +| Execute cell | `ctx.run_cell(cell_id)` | Explicitly queue execution; `create_cell` / `edit_cell` are structural only and do not auto-execute | + +### 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 `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 + analysis.