# eli5

Adopt this skill: https://proskills.md/skills/other/coldteadotai-pr-lens-skills-eli5

Page: https://proskills.md/skills/other/coldteadotai-pr-lens-skills-eli5
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/eli5/SKILL.md
size: 9301
sha: 01cd2d4083a1067d9b770a483276de7a5510ff72
upstream: https://github.com/coldteadotai/pr-lens/blob/main/skills/eli5/SKILL.md

````text
---
name: eli5
description: "WHAT: Explains a codebase, a folder, a feature, a command or a pull request to someone who knows nothing about it, as a PR Lens canvas whose walkthrough builds the picture one part at a time. WHEN: /eli5 <thing>, or asked to explain code simply, for a beginner, a new hire, a non-engineer, or 'like I'm five'. KEYWORDS: eli5, explain like I'm five, explain simply, beginner, onboarding, walkthrough, diagram, PR Lens"
---

# eli5

Explain like I'm someone who knows nothing about this code: one sentence, then one part at a time, until the whole picture is on screen and the reader already knows every part of it.

A reader who knows nothing cannot take in a diagram. They can take in two boxes and an arrow. So the canvas starts with two boxes and grows. The whole picture is the last thing they see, not the first, and by then it holds nothing new.

You write one graph document. Its views are the growing pictures, its walkthrough plays them in order, and PR Lens draws them. The reader opens a link and presses play. There is no page, no list, no paragraph.

## What you need

The PR Lens manual and its reference pages. The PR Lens CLI prints both. Run `npx @coldtea/pr-lens-cli@latest skill`, then `npx @coldtea/pr-lens-cli@latest skill references`, and read both before your first document. The manual's rules hold here except where this page marks an **Override**.

## Operating manual

1. **Write the answer first.** Read the code until you can say what it does for a person, in under 48 characters, because the sentence is also a walkthrough heading and a heading stops at 48. Count them.
   - For a feature or a command: "When you ___, this code ___." Example: "When you hit send, it emails everyone."
   - For a whole codebase: what the product is for. Example: "BestRegards sends newsletters for you." The sentence is about the product, not one path through it.
   **Override, summary.** The sentence is also the document `summary`. The reference wants a paragraph about a change; eli5 wants this sentence.

2. **Cut to the path.** For a feature, trace the one path input takes to output. For a whole codebase, first list the 3 to 5 things a person does with the product, then trace the path of the main one: the thing the product is named after or sold on, or the one with the most code on it. The parts on that path are the diagram: 4 to 10 nodes, 2 to 5 lanes. Helpers, config, types and tests stay out. When two entry points converge on the same code, draw the point where they meet and name both in its body; do not drop one.

3. **Write `.pr-lens/graph.json`.** Follow `references/graph-document.md`, plus these rules:
   - **Override, provenance.** The schema requires it. Take the remote from `git remote get-url origin`. `https://github.com/acme/mail.git` and `git@github.com:acme/mail.git` both become `{ "owner": "acme", "name": "mail", "host": "github.com" }`. Put the current `HEAD` sha in both `base.sha` and `head.sha`. The parser rule about "a patch whose two commits are the same" is about `patch`, not `provenance`, so this validates.
   - Lanes are places the reader can picture, left to right in the order the path runs: "your browser", "the website", "the mail company", "your reader". Not the folder tree. Set `order`. A database or queue the path touches more than once is not a place on the path; put it in the lane of the code that owns it.
   - The first node is the reader, or the thing the reader touches: "You write the email". The reader must find themself on the first picture. Use `kind: "external"` for a person; the schema has no person kind.
   - Node `label` is what the part does, in three words or fewer. The real name goes in `subtitle`, the file in `files`.
   - **Override, deltas.** Every `delta` is `unchanged` unless the thing is a pull request.
   - No `stats`. There is no diff to count.
   - Exactly one edge with `emphasis: "hero"`: the hand-off the answer sentence is about, the one edge that, if removed, would make the sentence false. Set `animated: true` on every edge along the path.
   - One flow when the path is a sequence, which it nearly always is. Flow step labels are what is passed, in plain words.

4. **Write the growing views.** **Override, views.** This replaces the C4 decision tree in the pr-lens skill. eli5 views are the same picture growing, not a drill-down.
   - View 1 holds 2 nodes: the reader and the first part they touch, with the edge between them. Scope: `{ "kind": "selection", "nodes": [...], "edges": [...] }`.
   - Each next view holds everything the last one held plus 1 to 3 new nodes along the path, and the edges among them. Never more than 3 new parts in one view. The one exception is the codebase view below.
   - The last architecture view is the whole thing: `"scope": { "kind": "all" }`. It is the only one with `"defaultOpen": true`. The growing view before it must still be missing at least 1 node, so the two are not the same picture; the pr-lens rule against two views with the same nodes holds. **Override, views.** Growing views share most of their nodes on purpose; only the last two must differ.
   - For a whole codebase, view 2 is the reader plus the 3 to 5 things the product does, as nodes in the product's lane. This view may add up to 5 parts; they are a list, not a path. Views 3 onward grow the main path. The other things stay on the picture so the reader knows they exist.
   - One data-flow root scoped to the flow: `"scope": { "kind": "selection", "flows": ["<flow id>"] }`. It is needed or the flow is never drawn.
   - All views are roots. Do not nest.
   - Name views by what is on them: `you-and-the-editor`, `plus-the-queue`, `the-whole-thing`.

5. **Write the walkthrough. One step per growing view, then the flow, then the whole.** Count first: growing views plus 1 to 2 flow steps plus 1 closing step, at most 9. With 10 nodes that means 3 to 5 growing views, so grow by 2 or 3 at a time, not 1.
   - **Override, headings.** A heading says what happens, not what changed: "The website packs your email". No step numbers; the canvas counts.
   - `body`: one line, up to 140 characters, that a smart twelve-year-old reads once. What happens, then what it means. Numbers as digits.
   - Step 1 stages view 1, focus left out, heading is the answer sentence, body introduces the two parts: "This is you, and the screen you write in. Everything starts here."
   - Each next step stages the next growing view and focuses only the new nodes with `{ "kind": "selection", "nodes": [...] }`. The body says what the new part does, and only that.
   - After the last growing view, stage the flow with `{ "kind": "flow", "flow": "<id>" }` for 1 to 2 steps that follow the sequence, focusing `messages`. Where things go wrong is one of these steps, in matter-of-fact words; focus the message that comes right before the failure, since a happy-path flow has no failure message of its own. Do not invent a message for it.
   - The whole-thing view carries two steps: one that introduces the nodes it adds, with focus, and the closing step. The closing step stages the whole-thing view, focus left out, heading is the answer sentence again, body adds one number the reader now understands: "1 email in, 2,000 emails out, 1 request to Postmark."

6. **Validate, render, push.**

   ```bash
   npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json
   npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light
   npx @coldtea/pr-lens-cli@latest canvas push .pr-lens/<drawing>/drawn.graph.json
   ```

   `render` prints the folder it drew into, named after the document's title. Push the `drawn.graph.json` in that folder. A bare `canvas push` stops when `.pr-lens/` holds more than one drawing.

   Fix every failure and validate again. Do not delete the element a failure names; fix the reference. `canvas push` prints the view link, `https://prlens.dev/c/{id}`, and an embed link. The view link is the deliverable.

7. **Open it and stop.** If this harness can open a browser, open the view link. Reply with the answer sentence and the link, on two lines. Nothing else: no step list, no file list, no summary of what you did. If the person who asked wants a report or a comparison, that is a second request, answered after this one.

A follow-up question about the canvas is answered on the canvas: `npx @coldtea/pr-lens-cli@latest canvas open .pr-lens/<drawing>/drawn.graph.json` once, then `canvas answer` with `--drawing` and the same path, as "Answering beside an open canvas" in the pr-lens skill says. Keep the same plain words there.

## Words

Plain words only. Not: leverages, orchestrates, pipeline, abstraction, handler, wrapper, layer, utility, invoke, instantiate. Say what it does. Real names appear once each, in subtitles, so a curious reader can find the code.

An analogy is allowed when the reader is not an engineer and one everyday thing matches the path beat for beat. Use it in bodies, never in labels, and drop it in the last step so the reader leaves with the real thing.

## What this is not

Not a review, not a file list, not a tutorial, not an architecture document. There is no field for a bug, a risk or an opinion, and there is no paragraph anywhere. And it is never one big diagram shown all at once.
````

## File: README.md
upstream: https://github.com/coldteadotai/pr-lens/blob/main/README.md

```text
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/mark.dark.svg">
    <img alt="" src="docs/brand/mark.light.svg" width="76">
  </picture>
</p>

<h1 align="center">PR Lens</h1>

<p align="center">English · <a href="README.zh-CN.md">简体中文</a></p>

<p align="center">
  <b>Understand a pull request, any codebase, or software visually, before you read a line of code</b><br>
  PR Lens draws every pull request as animated architecture and data-flow diagrams,<br>
  posted as a comment inside the pull request itself. For your coding agents, leverage it for understanding any codebase or code change with a live canvas of animated explainers
</p>

<p align="center">
  <a href="https://github.com/apps/coldtea-pr-lens"><img alt="Install the GitHub App" src="https://img.shields.io/badge/GitHub%20App-install-3fb950?style=flat-square&logo=github&logoColor=white&labelColor=21262d"></a>
  <a href="https://www.npmjs.com/package/@coldtea/pr-lens-cli"><img alt="The CLI on npm" src="https://img.shields.io/npm/v/%40coldtea%2Fpr-lens-cli?style=flat-square&logo=npm&logoColor=white&label=cli&labelColor=21262d&color=21262d"></a>
  <a href="https://discord.gg/nTEFnmBQMJ"><img alt="Join the Discord" src="https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white&labelColor=21262d"></a>
  <a href="https://prlens.dev"><img alt="prlens.dev" src="https://img.shields.io/badge/website-prlens.dev-21262d?style=flat-square&labelColor=21262d"></a>
  <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/github/license/coldteadotai/pr-lens?style=flat-square&labelColor=21262d&color=21262d"></a>
</p>

<h3 align="center"><a href="https://github.com/apps/coldtea-pr-lens">Install the GitHub App</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://skills.sh/coldteadotai/pr-lens">Install the Skill</a></h3>

<p align="center">
  <sub>Also runs on <a href="https://prlens.dev/gitlab">GitLab</a> and <a href="https://prlens.dev/bitbucket">Bitbucket</a></sub>
</p>

<p align="center">
  <sub>Free for open source &nbsp;&nbsp;·&nbsp;&nbsp; Or have your coding agent draw it: <code>npx skills add coldteadotai/pr-lens</code></sub>
</p>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/cta-strip.dark.svg">
    <img alt="Three steps: install the GitHub App on any repository, open a pull request, and the diagram shows up and updates on every push" src="docs/brand/cta-strip.light.svg" width="960">
  </picture>
</p>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/teaser.comment.dark.svg">
  <img alt="A PR Lens comment in a pull request: small labels with numbers about the change, a diagram of a small change, and checkboxes to pick other views" src="docs/showcase/teaser.comment.light.svg">
</picture>

<br />

## Features

<table>
<tr>
<td width="46%" valign="middle">

### Not Mermaid, better

We built a custom renderer from scratch. It draws rich animated visuals, reduces cognitive overload, represents code additions, removals and changes and still works for representing very large systems

</td>
<td width="54%" valign="middle">
<img alt="A code diff with a round lens moving over it. Inside the lens, the same change shows up as PR Lens cards and the paths between them" src="docs/showcase/welcome.not-mermaid.gif">
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### Architecture blast radius

The diagram shows the parts of your system that the code change touches, drawn against the system around it: the components involved, and the calls that run between them.

Colors show what changed: **green** is new, **amber** is changed, and **red** is removed.

</td>
<td width="54%" valign="middle">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/tier2-reference.architecture.dark.svg">
  <img alt="A diagram of a real change that reorganizes code: three lanes and ten parts, with the changed ones shown in color" src="docs/showcase/tier2-reference.architecture.light.svg">
</picture>
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### Intuitive Data flow

Understand how data flows through your any code change or codebase. The diagram plays the steps of the change in order with a moving dot one step at a time

</td>
<td width="54%" valign="middle">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/reference.data-flow.dark.svg">
  <img alt="A moving step-by-step diagram: seven steps, each taking its turn" src="docs/showcase/reference.data-flow.light.svg">
</picture>
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### See the payload on every data flow

Click any arrow to see the data it carries. A panel opens next to the diagram with the request and the response. Each one shows either the expected shape or a sample. New fields are green and removed fields are red, the same colors the diagram uses.

</td>
<td width="54%" valign="middle">
<img alt="Clicking the enqueue broadcast job arrow: a side panel opens with the request body. Added fields are green and a removed field is red. Then the Response tab opens and shows the expected shape" src="docs/showcase/welcome.payload.gif">
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### Zoom in without leaving the page

The comment has folding sections (`<details>`) that you can open and close. Each one has its own diagram for one part of the change. The whole change is on top. Below it is the new path, and then what was removed.

</td>

<td width="54%" valign="middle">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/reference.new-batch-path.dark.svg">
  <img alt="The same pull request zoomed into one section: two lanes, showing only the new batch path" src="docs/showcase/reference.new-batch-path.light.svg">
</picture>
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### Interactive canvas

Every comment or drawing can link to an interactive canvas. It has the same diagrams at full size. You can move around, zoom, and switch between a light and a dark theme. A big change gets all the room it needs instead of squeezing into a narrow comment or static image.

</td>
<td width="54%" valign="middle">
<a href="https://prlens.dev/c/uSdxMcPBFwhfgfaGh-dveQ"><img alt="The canvas: zooming into a small diagram, switching to the light theme, then fitting it back to the screen" src="docs/showcase/welcome.canvas.gif"></a>
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### Walk through the change

PR Lens ships with animated explainers called walkthroughs. Walkthroughs let you explore a system or code change step by step, without overwhelm. Start a walkthrough by pressing play on the canvas, or press W.

</td>
<td width="54%" valign="middle">
<a href="https://prlens.dev/c/uSdxMcPBFwhfgfaGh-dveQ"><img alt="A walkthrough on the canvas: the first step lights up the signup route and the new queue. The second step zooms in on the queue and the worker that empties it" src="docs/showcase/welcome.walkthrough.gif"></a>
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### Your agent, live on the canvas

Ask your local coding agent to connect to a canvas. Then use it to understand any codebase or code change. You can ask follow-up questions, zoom into any part of the diagram, or drag across a few cards and ask your agent about them. Watch it interact live with the canvas!

</td>
<td width="54%" valign="middle">
<img alt="A coding agent in a terminal next to a live canvas. A question typed in the terminal comes back on the canvas as a two-step answer, and the canvas follows the agent through each step" src="docs/showcase/welcome.live.gif">
</td>
</tr>

<tr>
<td width="46%" valign="middle">

### From one card to a whole monorepo

Every size of change uses the same look: lanes, cards, colors for what changed, and paths you can follow with your eyes.

For what it's worth, you should not open a pull request this big.

</td>
<td width="5
```
