Skip to content

oliverv/caro / .agents/skills/oma-explanation

oma-explanation

Unverified

Create an offline HTML explanation of a code diff, PR, or branch. Use when an interactive code-change walkthrough is requested.

FileKindSize
SKILL.mdskill md9.9 KB
resources/document-structure.mdmarkdown5.6 KB
resources/html-contract.mdmarkdown6.7 KB

resources/document-structure.md

View on GitHub
# Document Structure — oma-explanation

> The structural and rhetorical contract for all generated HTML explainer documents.
> Read this document to understand WHAT content is generated and in what tone.
> For HOW the HTML is styled and behaves, see `html-contract.md`.

---

## 1. Overall Shape

Every explainer document must be a **single long scrolling page**.
Do **not** use top-level tabs or multi-page navigation.
The document must begin with a Table of Contents (TOC), followed strictly by these four fixed sections in order:
1. **Background**
2. **Intuition**
3. **Code**
4. **Quiz**

---

## 2. Background

The Background section establishes context before presenting any code changes. It is composed of two tiers:

- **Tier A (Deep Background)**: Broadly explains the surrounding system or architecture. Must be explicitly marked "skippable if you already know the system."
- **Tier B (Narrow Background)**: Directly explains the context relevant to the specific change.

*Note on Reader Level:* If the requested reader level is `reviewer`, aggressively condense Tier A (Deep Background).

---

## 3. Intuition

The Intuition section conveys the core essence of the change without diving into full implementation details.

- **Toy-Data Examples**: Concrete toy-data examples are **mandatory**. Show, don't just tell, how the inputs and outputs change.
- **Visuals**: Liberally use diagrams (see Section 6) to establish mental models early.

---

## 4. Code

The Code section is a high-level walkthrough of the changes.

- **Comprehension Order**: Group and order the code walkthrough for human comprehension. Do **not** simply list files in alphabetical or git-diff order.
- **Reference**: Reference code using `file:line` notation where useful.

---

## 5. Quiz

The Quiz verifies understanding. While `html-contract.md` defines the interaction and JS behavior, this document governs question quality:

- **Count**: 5 questions by default (this count is parameterizable).
- **Difficulty**: Medium. Questions must be answerable only if the reader understood the substance of the change. No trick questions or gotchas.
- **Coverage**: Each question must target a distinct aspect of the change.
- **Distractors**: Wrong options (distractors) must be highly plausible.
- **Feedback**: **Every** option (correct and incorrect) must have accompanying feedback text explaining exactly why it is right or wrong.

---

## 6. Diagram Families

Visual consistency is critical. Pick **2–3 diagram families** per document and **reuse** them across sections to build continuity.

### Family Catalog
Choose from the following conceptual families:
- **Simplified UI Mock**: Abstracted representation of what the user sees.
- **System/Data-Flow Diagram**: Component interaction flows carrying **example data** directly on the arrows.
- **Before/After State**: Visual comparison of the system state before and after the change.

### Format & Responsiveness Constraints
- Diagrams must be rendered using **HTML/CSS** or **inline SVG** only.
- **ASCII art is strictly forbidden.**
- **Responsive Container**: Every diagram must be wrapped in a `<div class="diagram-wrapper">` container with `overflow-x: auto; max-width: 100%;` to prevent horizontal clipping on mobile devices (375px+). Inline SVGs must declare `viewBox` and responsive width (`width="100%"`).
- **Theme-Aware Colors**: All diagram elements (borders, text, arrows, node backgrounds) MUST use CSS variables (e.g. `var(--border-color)`, `var(--text-primary)`) or `currentColor` rather than hardcoded hex colors, ensuring seamless adaptation to Dark/Light theme toggling.
- **Accessibility (a11y)**: Diagrams must include `role="img"` and a descriptive `aria-label` or `<title>` element summarizing the diagram flow for assistive technologies.
- Use semantic HTML lists (`<ul>`, `<ol>`, `<dl>`) for textual lists.
- **archify sidecar (optional)**: an interactive archify diagram is a *separate* `.archify.html` file linked by a plain `<a href>` — it is never embedded (no `<iframe>` / `<object>` / `<script src>`), and the inline SVG/CSS diagram above stays in place so the explainer remains complete offline. See `_shared/conditional/diagram-engine.md`.

---

## 7. Callouts

Use styled callout blocks to highlight:
- Key concepts and definitions.
- Important edge cases and gotchas.

These should visually interrupt the prose to draw the reader's attention to critical information.

---

## 8. Writing Style and Language

The explainer must read with authoritative clarity, smooth transitions between sections, and an engaging tone.

- **English Prose**: Aim for Martin Kleppmann-like clarity. Classic style, engaging, logically rigorous but accessible.
- **Punctuation restraint**: Em-dashes are limited to a handful per document. Prefer commas, colons, parentheses, or a second sentence. CJK prose avoids em-dashes entirely (mirrors the repo's `cjk-em-dash` lint rule for translated docs).
- **CJK Output**: Follow the `translation_voice` register configured in `.agents/oma-config.yaml`.
- **i18n Rules**: Prose and quiz content must be in the user's requested language. However, following `.agents/rules/i18n-guide.md`, **code blocks, identifiers, and inline code are always in English**. Do not translate technical terms or variable names.

---

## 9. Provenance Footer

Every document must end with a provenance footer containing:
- **Generated-from reference**: The commit range, PR number, or branch used as input.
- **Generation Date**: The timestamp localized to the `Asia/Seoul` timezone.
- **Excluded Files**: If the diff was oversized and files were dropped, list the excluded files in a footnote. Never silently truncate.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall