Skip to Content
Cheat Sheet/eli5

/eli5

Post a plain-language explanation comment on a ticket or PR so a non-engineer reader — a founder, a workshop attendee, an investor — can follow what’s happening without prior context.

When to use it

Run this when an engineer-audience ticket or PR needs to be legible to a stakeholder who doesn’t know what a JWT, RLS policy, or CI gate is. The command reads the target (issue or PR), translates the technical content into plain language with inline definitions for every technical term, optionally adds a Mermaid diagram if it clarifies the flow, and posts the translation as a comment. The original body is never modified — agents keep reading the canonical spec; humans read the comment.

Use it for: founders watching the board who want to follow shipped work, workshop attendees following along during a session, investors scanning the project’s velocity, and non-engineer stakeholders who need to understand a specific decision. The output reads like a friendly explanation, not a marketing rewrite.

Don’t use this on every ticket — it’s busywork. Use it when a specific ticket or PR has stakeholder visibility and the engineer- audience body would lose them on the second sentence.

How it fits

The comment is additive — the original body stays the canonical spec for engineer readers; the comment serves the non-engineer audience. Two audiences, one ticket.

What it does (quick)

  • Resolves the target (issue or PR — gh auto-detects)
  • Reads the body + parent epic + recent comments for context
  • Detects any prior ELI5 comment (marker <!-- eli5-generated -->) and deletes it before posting fresh — re-runs always replace, never append
  • Translates the content into plain language with inline definitions for every technical term on first use
  • Optionally adds a Mermaid diagram when it clarifies the flow (skipped for pure-deletion or trivial tickets)
  • Render-checks Mermaid via mmdc before posting; drops the diagram if it fails to avoid broken renders in the GitHub UI
  • Posts the comment with the marker line so re-runs can detect it
  • /log-session — sibling; this command translates per-ticket, that command summarizes per-session
  • /review-pr — engineer-audience review; this command is the non-engineer-audience parallel
  • /release-decision — when a release lands, /eli5 on the release PR makes the announcement legible to non-engineer readers

Canonical spec: .claude/commands/eli5.md

Last updated on
/report-issueReference