visual-planning

Files (4)

• README.md
• SKILL.md
• openai.yaml · agents/
• preview.ts

SKILL.md (first lines)

# Visual Planning

## Overview

Make plans easier to understand by pairing concise prose with the right visual representation. Prefer diagrams, tables, architectural diffs, MDX-style blocks, and small code-shape examples when they reduce ambiguity or make tradeoffs easier to evaluate.

## Workflow

1. Read enough local context to avoid inventing architecture. Inspect relevant files, package boundaries, tests, and existing conventions before drawing diagrams.
2. State the plan's intent in one or two sentences: the goal, the main change, and the relevant boundary.
3. Write durable plan artifacts under `docs/plans/` unless the user explicitly asks for chat-only planning.
4. Choose one to three visuals that clarify the hardest parts of the plan. Do not add visuals as decoration.
5. Put each visual directly beside the decision it explains. Follow it with the concrete implementation steps it implies.
6. End with validation: tests, screenshots, type checks, migrations, rollout checks, or manual verification.

For tiny one-file tasks, keep the plan compact. A short ordered list is better than forcing a diagram that does not clarify anything.

## Plan Documents

When writing a plan file, create `docs/plans/` if it does not already exist. Use `.mdx` when the plan includes MDX components; otherwise `.md` is fine. Name the file with the current local date and a short kebab-case topic:

```text
docs/plans/YYYY-MM-DD-short-plan-topic.mdx
```

Examples:

```text
docs/plans/2026-06-17-runtime-session-store.mdx
docs/plans/2026-06-17-desktop-agent-streaming.md
```

If updating an existing plan for the same topic and date, edit that file instead of creating a near-duplicate. Keep the document readable as a standalone artifact: include context, diagrams, architectural diffs, steps, open questions, and validation.

Render the plan before handing off when visual accuracy matters — a diagram that does not render is worse than prose. This skill ships a self-contained previewer (`preview.ts` in this skill's folder; requires [Bun](https://bun.sh), no dependencies):

```sh
bun <path-to-skill>/preview.ts docs/plans/YYYY-MM-DD-short-plan-topic.mdx
```

It serves the plan as a live-reloading page with Mermaid rendered and the MDX components below styled. Use `--check` for a non-interactive render validation (unbalanced fences, empty mermaid blocks, unclosed components), or `--no-open` to serve without opening a browser. If the repository has its own preview command, prefer that.

## Visual Palette

Use the visual that matches the reasoning problem:

| Need | Best format |
| --- | --- |
| Request, data, or control flow | Mermaid `flowchart` |
| Multiple actors, async work, agents, clients, or APIs | Mermaid `sequenceDiagram` |
| State transitions, reducers, lifecycle, or protocol status | Mermaid `stateDiagram-v2` |
| Package, module, or ownership boundaries | Mermaid `graph` or dependency table |
| Schema, entity, or object relationships | Mermaid `erDiagram` or compact TypeScript shape |
| Rollout, migration, or phased delivery | Mermaid `gantt`, checklist, or phase table |
| Before/after architecture | Architectural diff plus a small diagram |
| API or data contract changes | Before/after code snippets and compatibility table |
| Risk and decision tradeoffs | Decision table with consequences |

Use Mermaid fenced blocks for diagrams:

```mermaid
flowchart LR
  Request[User request] --> Context[Inspect code context]
  Context --> Plan[Visual plan]
  Plan --> Steps[Implementation steps]
  Steps --> Verify[Validation]
```

Keep diagrams valid and easy to render. Use simple node IDs, quote labels that contain punctuation, and avoid cramming implementation details into node text.

## Architectural Diffs

Use architectural diffs to show structural change before detailed steps. Keep them conceptual unless file paths are already verified.

```diff
- ui/App.tsx owns fetching, state, and rendering
+ data/useProjectQuery.ts owns fetching and cache keys
+ ui/App.tsx owns composition and view state
+ ui/ProjectPanel.tsx owns project-specific rendering
```

Pair a diff with a short consequence statement:

| Change | Why it helps |
| --- | --- |
| Move fetching into a hook | Isolates async state and simplifies component tests |
| Split panel rendering | Keeps `App.tsx` focused on orchestration |

## MDX And Rich Components

When the target surface supports MDX, use components to make the plan scannable. Only use components that the repository, documentation site, or product surface actually supports.

```mdx
<Callout type="decision">
  Move session ownership into the runtime package so web and desktop share one source of truth.
</Callout>

<Steps>
  <Step title="Extract session store">Create the shared store and port current callers.</Step>
  <Step title="Wire desktop">Replace local state with the shared store API.</Step>
  <Step title="Verify">Run package tests and one desktop smoke path.</Step>
</Steps>
```

For plain Markdown or chat output, use blockquotes, tables, headings, and Mermaid instead of unsupported MDX.

## Plan Template

Adapt this structure to the task size:

````markdown
**Shape**
One sentence describing the intended architecture or workflow.

```mermaid
flowchart LR
  Existing[Current boundary] --> Proposed[Proposed boundary]
```

From erikreppel/skills, MIT.

More from erikreppel/skills