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:

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:

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: Diagnose & Capture

The goal of a retro is diagnosis, not a contribution. Based on the root cause, write up a clear diagnosis the team can act on — don't jump to proposing or authoring a fix.

For each friction point, produce:

• Diagnosis — What went wrong and why it was frustrating, in plain terms
• Contributing factors — Skill structure, gap, misleading docs, API

ergonomics, missing API, API bug, context window (from Step 2)

• Considerations — Trade-offs, open questions, or things that would need to

be true for a fix to make sense. Note possible directions here, but frame them as considerations rather than committed solutions.

The default next step is to capture the diagnosis as an issue or discussion so the team can weigh it — not to immediately make a contribution. Concrete code changes (skill edits, API designs) come after an issue/discussion exists and the user explicitly chooses to go further.

Present the diagnosis and ask: "Want me to draft this as an issue or discussion?"

Step 4: File or Follow Up

Default: file an issue / discussion

Write it up clearly for the marimo team to triage:

• Problem: What happened and why it's painful
• Current behavior: What the skill or _code_mode does today
• Considerations: Trade-offs and open questions (not a committed solution)
• Example: A minimal snippet or quote from the session, if helpful

Leave the actual filing to the user — do not auto-file. This is the preferred outcome: surface friction for the team rather than ship a fix from the retro.

Only if the user explicitly wants to go further

A skill edit or API change should follow an issue/discussion, not replace it. If — and only if — the user explicitly asks to draft a change now:

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)

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

To inspect the live _code_mode API surface during a retro, the user can run in their notebook scratchpad:

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)

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

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

Cell Operations (Mutating)

Execution

Package Management

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.