retro-marimo-pair

Files (2)

• SKILL.md
• code-mode-surface.md · reference/

SKILL.md (first lines)

# 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: 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

| 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 |

From itzmetanjim/coolton, AGPL-3.0.

More from itzmetanjim/coolton