# Explain Implementation

> Explains a completed implementation as a decision-oriented walkthrough of what changed, how it works with file:line references, and why key choices were made. Uses session-verified documentation and a persistent knowledge memory to avoid repeating known concepts. Invoke only when the user explicitly enters `/explain-implementation` in Claude Code or `$explain-implementation` in Codex. Do not invoke for natural-language requests to explain or walk through code, unsolicited post-task summaries, general concept tutorials, changelogs, or docstrings.

- Skill: `theedoran/explain-implementation` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add theedoran/explain-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theedoran/explain-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: TheEdoRan (https://skillmd.com/u/theedoran)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theedoran/explain-implementation

---


# Explain Implementation

On explicit request, help the user actually learn from the code you wrote for
them. Two pillars: **verified sources** (never cite a URL you did not check
this session) and a **personal knowledge memory** (don't re-teach what the
user has already seen or knows).

## Why these rules exist

- URLs recalled from memory are the single most common hallucination in
  "cited" output: they look plausible and are wrong just often enough to
  destroy trust. A source you haven't verified this session is worse than no
  source — omit the citation (or the whole item) instead.
- Repeating explanations the user already has teaches nothing. The memory
  file exists so novelty is real novelty.

## The knowledge memory

Keep data in the current agent's configuration directory:

- Claude Code: `$CLAUDE_CONFIG_DIR/explain-implementation/` when
  `CLAUDE_CONFIG_DIR` is set, otherwise `~/.claude/explain-implementation/`
- Codex: `$CODEX_HOME/explain-implementation/` when `CODEX_HOME` is set,
  otherwise `~/.codex/explain-implementation/`

The knowledge memory is `known-concepts.md` in that directory. It is shared
across projects that use the same agent, but it is not shared across agents.

Format — one line per concept:

```
react-use-sync-external-store | 2026-07-16 | shown
postgres-advisory-locks | 2026-07-02 | known
css-anchor-positioning | 2026-06-20 | re-explain
```

States:
- `shown` — a previous walkthrough already presented this concept. Cover it
  briefly, don't re-teach from scratch.
- `known` — the user explicitly said they know it. Skip it unless they ask.
- `re-explain` — the user asked to see it again. Treat as unknown; after
  re-explaining, set it back to `shown`.

Maintenance: when the user says they already know a concept ("I know this",
"I already know that"), update its line to `known` (add the line if missing).
When they ask to have something re-explained, set it to `re-explain`. Create
the file and parent directory on first use. Keep slugs kebab-case and stable
so the same concept always matches.

## Source verification protocol

Full details and edge cases:
[references/source-verification.md](references/source-verification.md).

The short version: before citing anything, resolve it against real
documentation **in this session** — Context7 first (library/framework APIs),
WebFetch/WebSearch as fallback (specs, RFCs, platform docs). Cite only URLs
that a tool call actually returned or confirmed. If verification fails or the
tools are unavailable, say what the concept is and name the authoritative
place to look ("the React docs page on useSyncExternalStore") WITHOUT a URL —
never fabricate one.

## The walkthrough

Explain the implementation just completed in this conversation (if ambiguous,
the most recent one; if the user names a diff/commit, use that scope).

Structure it around decisions, not files:

1. **What was built** — two or three sentences of outcome.
2. **How it works** — the key flow, referencing real files as `path:line`.
3. **Decisions and techniques** — for each non-trivial choice: what it is, why
   this over the alternative, and a verified source for every technical claim
   about an API, language feature, or documented behavior. Cite inline with a
   numbered footnote marker `[1]` right after the claim; the number matches an
   entry in the Sources list. Repo-specific rationale ("this matched the
   existing pattern in X") needs no external source — point to the code
   instead. Cover `shown` concepts briefly; respect `known` ones unless asked.
4. **Sources** — a final numbered list where entry N is the verified link for
   marker `[N]` above.

Ground every claim in either the actual diff/code (cite the location) or a
verified document (cite the URL). A claim you cannot ground gets labeled
"(not verified — check before relying on this)". Never silently guess. After
the walkthrough, record newly explained concepts in the memory as `shown`
with today's date.

## Browser view

After delivering the walkthrough in chat, produce a browser-viewable copy:

1. Copy [references/walkthrough-template.html](references/walkthrough-template.html)
   and fill in its `{{PLACEHOLDER}}`s (title, date, project, slug, content,
   markdown source) — the header comment in the template documents each one.
   Author the `{{CONTENT}}` HTML directly from the walkthrough you just wrote
   (no pandoc or other converter), as `<section>` blocks with one `<h2>` per
   walkthrough section — the template numbers them automatically. Do not
   add external scripts, fonts, or images: the file must stay self-contained
   and render offline.
2. The template's toolbar already provides **Copy markdown** and
   **Download .md** buttons wired to the embedded `{{MARKDOWN}}` source —
   paste the walkthrough's markdown verbatim there, escaping any literal
   `</script` as `<\/script`.
3. Save it to `walkthroughs/YYYY-MM-DD-<topic-slug>.html` inside the current
   agent's explain-implementation data directory defined above
   (create the directory on first use). The file persists there, so the user
   can re-open, copy, or share it later.
4. Open it in the default browser: `open <file>` on macOS,
   `xdg-open <file>` on Linux, `start "" <file>` on Windows.
5. End the chat message with the saved file path so the user knows where the
   file lives.

Sources in the HTML are the same verified links from the walkthrough — the
verification protocol applies unchanged. Render each footnote marker as
`<sup><a href="#src-N">[N]</a></sup>` and give the Sources list items matching
ids (`<li id="src-N">`), so markers click through to the entry at the bottom.

## Scope guard

This skill explains work done in this conversation by the agent, on explicit
request only. If asked to explain pre-existing code the agent didn't write,
the walkthrough still works, but say explicitly that the rationale ("why") is
inferred from the code, not known from authorship.