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.

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