AI Review Skills

View saved version →

---
name: documenting-with-sources
description: Common conventions for writing Markdown documents that cite external sources (survey reports, paper explainers, and any deliverable that surfaces facts from outside). Defines mandatory citation, in-text reference format, quotation-versus-prose separation, the ban on fabricated associations, and the source-list format. Referenced by survey, paper-details, and any skill that produces sourced output.
---

# Documenting with Sources

Common conventions for writing Markdown documents that pull from outside sources. Apply to any deliverable that surfaces facts taken from elsewhere — survey reports, paper explainers, and similar.

## Cite every factual claim

Every factual claim in the deliverable must carry a citation. A claim with no citation cannot be verified, and is worthless as a documented finding. If a claim cannot be tied to a source, mark it explicitly (e.g. "citation not confirmed"). Do not slip uncited claims in silently.

## Reference format

- In-text references take the shape `[label (YYYY/MM), location]`. How to fill the `label` slot (publication name, author short-form, position-only for the paper under review, etc.) is decided by the calling skill.
- Do not use bare numeric references such as `[1]` or `[2]`. Numbers alone force the reader to bounce between text and source list; readability drops.
- For the formatting of quotation blocks themselves (code-block fencing, original-and-translation pairing, where to place the source reference, anti-patterns), follow the `writing-quotation` skill. Read `writing-quotation` before drafting.

## Quotation vs prose

- Keep quotations and prose (the writer's own summary or interpretation) visually and structurally separate. Even when not quoting, write in a way that prevents the source's claim and the writer's interpretation from blending.
- When quoting a source written in a language other than the writer's working language, place the translation alongside the original inside the same code block (see `writing-quotation`).

## No fabricated associations or interpretations

Do not write interpretations, speculation, or associations that the source itself does not contain.

- Do not invent connections such as "this relates to X", "this could be applied to Y", or "this suggests Z" when the source does not say so.
- Do not import context from the surrounding conversation or the calling project into the body of the document. Descriptions of a source must stay within the source's own content.
- Good: "Main criticism: even with flipped labels, accuracy does not always drop, and the text-gradient is mathematically distinct from classical gradient descent" (states what the source actually says).
- Bad: "Relation to AI writing improvement: feedback-based improvement is mathematically different from gradient descent..." (the source does not say this; the connection is fabricated from conversation context).

## Source-list format

The source list at the end of the document uses this format:

`[label, YYYY/MM] Author. "Title." Publication. URL`

Do not use the `- [n]` list format.

View saved version →

---
name: explain
description: Conventions for writing a Markdown explainer that walks the reader through a concept or system. Lays out term-list formatting, Mermaid diagram rules, granularity expectations, and a fixed five-part structure. Use when the user asks for an explainer, a concept write-up, a glossary section, or otherwise wants a system or idea documented for another reader.
---

# Explainer Document Conventions

## Term handling

- Put a term list at the top of the document in table form (`| Term | Description |`). Every specialised term used in the body must be defined in this list at first occurrence.
- A term-list entry defines what the term *is* in one or two sentences. The functional or behavioural detail goes in the body, not in the term list.
- Even widely recognised proper nouns (industry-standard product names, infrastructure components, etc.) get defined here. Assume the reader does not know them.
- When defining a compound term, define the constituent words too. If the compound has three words, give all three their own entries — readers cannot be expected to infer one from another.

## Diagram conventions

- Use Mermaid for diagrams. Do not use ASCII art.
- Every node label is a term that exists in the term list. Do not introduce a new term inside a diagram.
- Do not put `<br/>` inside a Mermaid node. Many renderers display the literal HTML tag. If a line break is needed, separate with ` / ` or shorten the text to fit one line.
- For diagrams with four or more nodes, or where any label is long, use `graph TD` (top-down). `graph LR` (left-right) collapses long-label graphs into an unreadable horizontal strip.

## Granularity of the description

- Do not gloss details with vague language. Subjects, objects, and verbs must be explicit.
- A phrase like "A uses B to do X" must specify what A is and why A is needed for X.
- Avoid vague verbs like "receives" or "passes". Spell out who does what to bring the state about (e.g. "receives the address" → "the platform allocates the address automatically").
- Do not require the reader to make a leap between steps. Every step's causal connection to the next is explicit.
- Describe the mechanism in its general form first; tie it to specific named instances afterwards as "in case X, ...". Do not anchor the whole description to a single proper-noun example.

## Structure

1. Term list
2. Background (why this thing is necessary, or what problem it addresses)
3. Mechanism (how it works — includes the diagrams)
4. Concrete steps (commands, procedures, or worked examples)
5. Current state (where things stand today — for ongoing systems)

View saved version →

---
name: html
description: Explicitly invoked only. 概念・仕組み・調査内容をHTMLで説明する。通常回答やMarkdown依頼では自動実行しない。
---

# HTML による説明ドキュメント

明示指定時だけ実行する。最初に `../../references/runtime-capabilities.md` を読み、実際の能力を確認する。

## 文章

説明内容と日本語表現を補うため、次のスキルの併用を推奨する。

- `explain`：概念や仕組みを説明するときの用語定義、説明の粒度、構成
- [`japanese-tech-writing`](https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d)：日本語の技術文書、記事、解説文の構成と文章規範
- [`cognitive-rhythm-writing`](https://gist.github.com/k16shikano/eb2929f13ed19c97188393d297be8432)：読み物としての緩急が必要な長文の文章規範

いずれも推奨スキルであり、`html` の必須依存ではない。

## 成果物

- HTML を作る
- ビルドなしでブラウザが直接描画できる状態にする
- 保存先が指定されている場合は従う。指定がなければ現在の作業ディレクトリへ保存する
- ファイル名は `{yyyymmdd}-{内容を表すケバブケース}.html` とする。既存ファイルの更新では名前を変えない
- 個別の文書管理システム、メタデータ、Viewer、公開先に関する規則は、このスキルを参照する上位スキルの指示に従う

Work Local / Work Cloud / 不明環境ではCSSと最小JSをインライン化し、利用可能な画像をdata URIにした単一HTMLを既定とし、CDNを必須にしない。Codex Localでは共有CSS/JS/相対画像を再利用でき、要求時は単一HTMLも作る。方式と制約を成果物に記録する。

## デザインシステム

作成前に `design-system/component-samples.html` を確認する。コンポーネント集は `design-system/document.css`、数式コピー機能は `design-system/math-copy.js` を正とする。

既定では、成果物と一緒に必要なファイルを配置し、次の相対パスで読み込む。上位スキルが共有アセットのパスを指定した場合は、その指定を優先する。

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Ubuntu+Sans:wght@400;500;700&family=Noto+Sans+JP:wght@400;500;700&family=Ubuntu+Mono:wght@400;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="./design-system/document.css">
<script src="./design-system/math-copy.js"></script>
<script async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>
<script>document.addEventListener("DOMContentLoaded", () => hljs.highlightAll());</script>
```

主要規則は次のとおり。

- 背景は `#FAF9F6`。部品は白地、黒罫線、角丸を基本とする
- 自然言語は Ubuntu Sans と Noto Sans JP、コード・URL・日付は Ubuntu Mono を使う
- 有彩色はリンク青 `#2990DA` とアクセント赤 `#D63A2F` に限定する
- 赤い強調は原則として 1 ページ 1 箇所までとする
- シンタックスハイライトとコード差分の色は、意味を区別する機能色としてこの制限の対象外とする
- 余白は上下左右の均衡を保つ
- 引用は `.mb-quote` を使い、原文と訳文を同じ文字サイズ・色で上下に並べる
- `.mb-chip` は並列の固有名や分類名の列挙にだけ使う
- 絵文字や矢印文字を図記号として使わない。必要な記号はインライン SVG で描く
- 表は短い対応関係に使い、3 列までを基本とする
- 行見出しのセルには `.mb-rowlabel` を付け、語中の折り返しを防ぐ
- コード差分は `pre.mb-diff` を使い、変更理由を散文で説明してから必要な断片を示す
- ページ固有の `<style>` は図の配置調整など最小限にとどめる

## 構成とフォーマット

説明対象に合わせて、並置、図解、タイムライン、要約、折りたたみを使い分ける。
一方向の単純な手順を、必要性なくフローチャートにしない。

基本構成は次の順とする。

1. 背景と要点
2. 本論
3. 具体例
4. 補足・限界・関連事項

h1 とリード文の後に `.mb-toc` の目次を置き、各 h2 に対応する `id` を付ける。

### 用語リスト

専門用語は本文の初出で定義する。
用語リストは、複数箇所から参照する用語がある場合だけ設ける。
用語リストの位置は文書ごとに変更しない。
ブラウザ幅 1400px 以上では、本文右側の専用欄へ表示する。
ブラウザ幅 1399px 以下では、本文末尾へ表示する。
配置の切り替えは共有 CSS だけが担当し、用語リストによってヘッダー、リード、目次、要約、本文の幅を縮めてはならない。
マークアップは `aside.mb-glossary` と `dl`、`dt`、`dd` を使う。
正解例は `design-system/component-samples.html` を参照する。

## 図

- `.mb-figure` は、画像・SVGなどの視覚資料とキャプションを一つにまとめる外枠である。特定の図形や「矢印で結んだ箱」を意味しない
- `.mb-figure-frame` は視覚資料の表示面、`figcaption` は図番号・説明・出所の表示領域として使う
- 原典に重要な図がある場合は、出所を明示して引用する
- 原典の図があるのに模倣図を作らない
- 自作図はインライン SVG とし、アスキーアートを使わない
- 黒一色の線画を基本とし、`.mb-figure-frame` に載せる
- ノード数が多い場合は縦方向を優先する
- 矢印が交差する構成を避ける
- 単なる直列手順は番号付きの説明として表現する

## コード

- Highlight.js を必ず読み込み、言語に応じたシンタックスハイライトを適用する
- `pre code` には `language-javascript`、`language-python`、`language-html` などの言語クラスを必ず付ける
- ハイライトしないテキストには `language-plaintext` を付ける
- 独自の色付けでコードを装飾せず、`document.css` の `.hljs-*` 規則を使う
- `pre.mb-diff code` には `nohighlight` を付け、差分専用の色と行頭記号を使う

## 数式

- MathJax 3 を使う
- インライン数式は `$...$`、ディスプレイ数式は `$$...$$` とする
- ベクトルと行列は `\boldsymbol{...}` を使う
- スカラー、添字、集合名は装飾しない
- 名前付きの演算は `\mathtt{...}`、標準 LaTeX コマンドはそのまま使う
- `math-copy.js` により、すべての数式から LaTeX 原文をコピーできるようにする
- ページ側で `window.MathJax` を再定義しない
- 未知のコマンドを別記法へ勝手に置換しない

## 印刷と PDF

印刷対応は `document.css` の `@media print` を使う。
PDF 化はユーザーから明示的に依頼された場合だけ `render-pdf.sh` を実行する。

Referenced files: 5

View saved version →

---
name: html-review
description: Explicitly invoked only. Convert canonical Markdown, JSON, Evidence, and test results into a human-readable HTML snapshot without making HTML the source of truth.
---

# HTML Review

Render an integrated Review Packet for human review. This projection layer does not research, judge correctness, launch agents, approve, replace tests, mutate canonical inputs, publish, or act as an agent return contract. Invoke only by explicit skill selection, never for ordinary HTML/Markdown/JSON responses.

Read `references/review-packet.schema.json` and `../../references/runtime-capabilities.md`. JSON and referenced Markdown/Evidence/tests remain canonical; HTML is `derived_snapshot`. Preserve wording, IDs, paths, URLs, timestamps, citations, verification and test states. Render absent optional values as `未提供`/`未確認`; never invent or silently omit. Reject missing/invalid canonical packets before rendering.

Keep conclusion, P0/P1, Blocked, Warning, Human Decision, and unresolved items expanded. Use semantic text, not color alone. Escape all input; do not runtime-fetch. Work/unknown outputs one offline HTML with inline CSS/JS and data-URI images (or locator plus `画像は未埋め込み`). Codex Local may reuse relative shared assets and must retain a portable option. Use one HTML writer.

When Python exists: `python scripts/render_review.py <packet.json> <output.html>`. Otherwise fill `assets/template.html` under identical rules. Validate all IDs/locators/citations/quotes/statuses, unchanged canonical hashes, no external dependencies, and truthful audit mode. Report HTML and canonical paths together; agents continue exchanging the packet, never HTML.

Referenced files: 4

View saved version →

---
name: paper-details
description: Produce a detailed Markdown explainer of an academic paper. The skill aims for faithful description, not critical review. Section structure mirrors the original paper, equations render as LaTeX with variable tables, citations to the paper under review use position only, and citations to other works use author-short form. Use when the user asks for a detailed paper write-up, a thorough paper explainer, or invokes "paper details". Depends on documenting-with-sources and writing-quotation.
---

# Paper Details

Conventions for producing a detailed Markdown explainer of an academic paper. The aim is faithful description, not critique. First read `../../references/runtime-capabilities.md` and detect PDF, filesystem, Python, uv, image-output, and subagent capabilities.

Before analysis, obtain `product` and `execution_location` from explicit task or host metadata and record them separately. Filesystem, Python, or shell availability does not prove Codex Local because Work Local can expose the same tools. If metadata is absent, record `Unknown`.

This skill follows the shared sourced-writing conventions defined in `documenting-with-sources`. Read `documenting-with-sources` before drafting.

## 1. Deliverable structure

### 1.0 Output location

Write the explainer as a `.md` file under the project's `reports/` directory, where "the project" is the root that contains the source paper PDF. Create the directory if it does not exist.

- Path: `{project-root}/reports/{paper-filename-base}.md`
- Example: if the PDF is at `/path/to/project/papers/foo.pdf`, the output is `/path/to/project/reports/foo.md`

Do not write next to the PDF, and do not write at the project root. Do not ask the user for the output path — determine it mechanically by the rule above.

### 1.1 Opening

In this order:

1. Title (`# {paper title} — Detailed Explainer`)
2. Bibliographic info (authors, affiliations, venue, year, arXiv/DOI, URL)
3. Full abstract — quote the original in a code block per `writing-quotation`; if the original is in a non-working language, place the translation alongside as a separate paragraph in the same block.

### 1.2 Body section structure

The body's section structure follows the paper's. If the paper has Section 1 Introduction, Section 2 Method, Section 3 Results, ..., the explainer uses the same order and the same headings.

Add explainer-only sections (e.g. "Strengths of the paper", "Limitations of the paper", "Source list") *after* the paper's own section structure.

### 1.3 Bullet lists vs prose

Pick the form by the nature of the content.

- Bullet lists fit enumerations of parallel items — variable lists, definitions of evaluation metrics, table-column descriptions, comparison points between methods, etc. When the content is genuinely list-shaped, the prose form blurs the boundaries between items.
- Prose fits relationships, causal flow, contextual explanation. When the reader needs to understand why items appear together or how they form a single argument, prose is what holds it together.

### 1.4 Figures and tables: extract as images

Never reconstruct a figure or table from scratch (no hand-written HTML tables, no redrawn SVG figures). Extract them as images from the source paper and insert those images into the deliverable (`.md` or HTML). Hand reconstruction introduces transcription errors and loses the original layout — bold, underline, colour-coded legends — so it is forbidden.

When Python, `uv`, PyMuPDF, and file output are available, use the bundled script:

```
uv run {this-skill-dir}/scripts/extract_images.py <PDF path> --out {project-root}/images-from-papers
```

- The script finds `Figure N` / `Table N` captions in the PDF and clip-renders the figure/table region directly above each caption — the bounding box of vector drawings, rules, and embedded images — at 300 dpi. Figures and tables are usually drawn as vectors with no embedded raster, so extraction is region rendering, not pulling out an embedded image.
- Output defaults to `{project-root}/images-from-papers/` as `{paper-filename-base}-fig{N}.png` / `{paper-filename-base}-table{N}.png`. The extraction list is recorded in `{base}-manifest.json` in the same directory.
- A multi-panel float (e.g. one Table float that contains panels (a)–(f)) is extracted as a single image, matching the single float in the paper.
- After extraction, insert the images from `images-from-papers/` into the deliverable. In `.md`, reference them by relative path, e.g. `![Figure N](../images-from-papers/{base}-fig{N}.png)`. In an HTML deliverable created with `html`, embedding as a base64 data URI is acceptable.
- Add the translated caption as a separate paragraph below the image. The caption text inside the image stays in the original language (it is not redrawn), so the translation goes outside the image.
- Verify the manifest against PDF captions; an empty manifest is not proof of no figures.
- If extraction is unavailable, errors, or misses required items, continue complete body-text analysis. Add `図表画像は未抽出` to metadata and relevant sections, record the reason/command, and never fail the entire explainer solely for figure extraction.
- Do not reconstruct missing visuals. Mark visual-only details unverified. An unreadable PDF body is a separate blocker requiring an accessible source.

### 1.4.1 Portable report copies

Never copy a Markdown report alone when it contains local image links. For export to Downloads, `outputs/`, or another root, create a portable directory containing the Markdown and all referenced local images, with links rewritten inside that directory. When Python is available, run `python {this-skill-dir}/scripts/package_report.py <report.md> <destination-directory>`. Verify every rewritten link. If an image cannot be copied, stop the copy and report it; do not deliver a known-broken Markdown copy. The canonical project report may keep its existing `../images-from-papers/` layout.

## 2. Quotation and source reference

### 2.0 Output is built around translated quotation blocks

Build the explainer primarily out of "original quotation + translation" blocks that cover the paper's body in full. Do not make summarised, paraphrased prose the main act. Keep the reader able to check the original against the translation throughout the document.

Prose — the writer's own text — is a complement to the quotation-led flow, added only when one of the following holds:

- The connection between quotation blocks is unclear, and the relationship or logical flow between sections or paragraphs needs bridging.
- A supplementary explanation — variable definitions, prerequisite knowledge, how to read a figure or table, the first-occurrence definition of a term — is genuinely useful to the reader.

Where neither holds, do not re-summarise the original in prose; let the quotation block speak for itself. Do not settle into a "quotes carry the gist, prose summarises" split.

To convey the paper's claims accurately, include direct quotations from the original. A summary alone does not let the reader judge whether the writer's interpretation is correct.

Within the `[label (YYYY/MM), location]` structure defined in `documenting-with-sources`, the `paper-details` skill fills the label slot differently depending on which work is referenced.

### Reference to the paper under review

When referring to the paper under review, omit the author and year and cite the position only, in the form `[p.X, Section Y.Z]`. Since the entire explainer is about a single paper, the author does not need to be repeated each time.

Examples: `[p.4, Section 1]`, `[p.21, (15)]`, `[p.31, Figure 2]`.

### Reference to other works

For other works that the paper cites, use `[author-short (YYYY)]` inline.

- Pin location with a section, page, table, or figure number.
- Do not abbreviate the list of cited works with phrases like "...and others". List each work individually with its author and year. The reader of the explainer depends on this list — citing the explainer's host paper alone does not substitute for naming the works the paper references.

## 3. Equations

### 3.1 Syntax

- Equations are written in LaTeX. Inline as `$...$`, display as `$$...$$`.
- Forbidden: putting equations inside a code block. Forbidden: writing equations in plain-text form, pseudo-code form, or anything other than LaTeX syntax.

### 3.2 Variable definitions

Every symbol in an equation is unknown to the reader until it is defined. Before presenting an equation, define every variable and symbol that appears in it. Do not place an equation without its variable definitions in scope.

In equation-heavy sections (theory, method formalisation), put a variable table at the top of the section. Group variables by role. Each entry includes:

- The symbol (in LaTeX).
- What it means (one sentence).
- A note that helps intuition (concrete example, value range, behaviour in special cases).

Example:

```
Inputs:

- $n$: number of characters in the input text. The length of the user's prompt.
- $K$: the model's context-window length in characters. Inputs longer than this cannot be passed to the model directly.

Planner outputs:

- $k^*$: branching factor at each level — how many chunks to split into. With $k^*=5$ the input is split into five chunks at each level.
- $\tau^*$: threshold below which the chunk is sent to the LLM as-is, without further splitting. With $\tau^*=26{,}000$, chunks of 26,000 characters or fewer go straight to the LLM.
```

In sections with few equations, defining variables in-line before and after each equation is acceptable — but the principle that no equation appears with undefined symbols still holds.

## 4. Numerical results

- Present experimental results in tables when possible.
- Place the proposed method and baselines side by side.
- Transcribe numbers exactly as they appear in the paper. Do not round or approximate.
- Before showing the table, define each column and each metric in a preceding bullet list. By the time the reader sees the numbers, the meaning of each column is clear.
- Do not use generic words like "accuracy" or "performance" loosely. Use the metric name the paper itself defines (classification accuracy, pass rate, pass@1, etc.).
- If the same word is used in different senses across the paper (e.g. a method name that means "the best single result" in a table but "the entire procedure" in the body), call out the polysemy explicitly.

## 5. Describing experiments

### 5.1 Spell out the procedure

In experiment sections, the reader must be able to follow what was actually done. Do not omit:

- The concrete task steps (what the input is, what each step produces, what the final output is).
- The data-split structure (search set / validation set / test set — what each is for, and which result corresponds to which split).
- The search or optimisation procedure (initial state, number of iterations, what each iteration generates, the criterion under which the final result is selected).

### 5.2 Independence between sections

Each experiment section reads on its own. Do not refer back to "the method defined in Section X" with an unspecified abbreviation. Even when two experiments share a search procedure, restate it with the experiment-specific parameters in each section.

### 5.3 Consistent granularity

When the paper has multiple experiment sections, keep the level of detail consistent across them. Do not write the search procedure thoroughly in one section and dismiss it in one sentence in another.

### 5.4 Define concepts before use

Define every concept the first time it appears in the explainer, before using it. Do not omit concepts the paper itself defines. In particular, before presenting a table or a number, make sure every concept needed to read that number has already been defined.

## 6. Source list

Place the source list at the end of the explainer, formatted per `documenting-with-sources`. In addition to the paper under review, include every other work the explainer mentions.

## 7. Section-by-section audit

A first-pass draft typically contains errors that a single re-read misses. Audit section by section using parallel subagents when available, or the identical checks sequentially in the main agent.

### 7.1 Output location

Write audit results to `{cwd}/subagent-reviews/{NN-section-name}.md`, one file per section. Create the directory if it does not exist. Audits are separate artifacts from the explainer; do not put them under `reports/`.

### 7.2 Sectioning

Split the explainer into independent units that align with the paper's section structure:

- Abstract and bibliographic info (one unit)
- Each top-level section of the paper body (Introduction, Background/Related Work, Method, Experiments, Limitations, Conclusion, etc.)
- The source list at the end of the explainer

Larger sections (e.g. an Experiments section with multiple sub-experiments and tables) can be split further if a single auditor would face too much material. Keep one auditor per file.

### 7.3 Auditor brief

In parallel mode, use one subagent per section. In sequential mode, apply the same brief one section at a time:

1. Read the paper PDF and the corresponding section of the explainer.
2. Verify factual accuracy: claims, equations, numbers in tables and inline numbers in prose, citation-number ↔ reference correspondence.
3. Verify translation accuracy when the explainer is in a non-source language. Look for: dropped words, added implications not in the original, inappropriate word order, untranslated source-language idioms.
4. Verify formatting compliance: citation form (`[p.X, Section Y.Z]` for the paper under review, `[author-short (YYYY)]` for other works), no `**` bold decoration, quotation rules from `writing-quotation` (code-block quotes, original-translation pairing, source reference on its own line outside the block).
5. Verify terminology consistency across the section.

Each audit file uses three headings: overall assessment, findings, suggested edits. Findings point at specific lines or quoted passages in the explainer; for translation issues, quote both the source and the explainer's rendering so the synthesis step can compare them side by side.

Record exactly one effective mode in the explainer and audit artifacts: `audit_mode: parallel-subagents` or `audit_mode: sequential-single-agent`. List completed sections/checks. If dispatch fails, finish missing checks sequentially and record the failed attempt and effective completion mode.

### 7.4 Synthesis and edits

After all audits return:

1. Read each audit file in full.
2. Cross-check audit claims against the paper itself before applying them. Auditors can be wrong, and two auditors may disagree on the same fact (for example, two reviewers may map a numeric citation `[16]` to different references). When that happens, consult the paper's References list and resolve the conflict from the source.
3. Apply confirmed edits to the explainer.
4. When applying overlapping edits across sections (e.g. a citation-label change that recurs throughout), make the change consistently in every occurrence.
5. Move on once findings have been resolved — there is no need to write a separate "responses to audit" document; the audited explainer itself is the artifact.

### 7.5 Vocabulary

The artifact this skill produces is a detailed explainer, not a review. Audit outputs are reviews. Keep these terms separate in conversation with the user and in titles: do not call the explainer a "review", and do not call the audit a "detailed explainer". This separation prevents ambiguity when the user asks "update the review" partway through the workflow.

Referenced files: 2

View saved version →

---
name: survey
description: Investigate a topic across papers, articles, social-media posts, and industry signals, then deliver an indexed Markdown report. Use when the user asks to investigate, survey, gather sources, build an index, collect evidence, round up references, or otherwise wants a thorough cross-source roundup on a specific topic. Depends on documenting-with-sources and writing-quotation.
---

# Survey

Gather sources from the web, papers, social media, and industry on a specific topic, and produce an indexed Markdown report. First read `../../references/runtime-capabilities.md`.

This skill follows the shared sourced-writing conventions defined in `documenting-with-sources`. Read `documenting-with-sources` before drafting.

## Quality criteria

Apply to every source.

- Prefer trustworthy sources (peer-reviewed papers > official blogs > major industry media > personal blogs).
- If the author is an individual, list their affiliation and role. If unknown, look it up.
- For papers, in addition to bibliographic info (authors, affiliations, venue, year), include citation count.
- Always attach a URL.
- Always attach a date.
- Treat official documentation and third-party articles as different reliability tiers. Do not mix them; the reader must be able to tell which is which.

## Prose structure: Assertion-Evidence form

Write the body in Assertion-Evidence form — claim first, then evidence.

1. Prose: the writer states the claim or summary in their own words first.
2. Immediately after, a code-block quotation from the source backs up the claim, formatted per `writing-quotation`.
3. On the line after the closing fence, place the source reference `[source-name (YYYY/MM)]`.

The reader grasps "what is being said" first, then checks "what is the basis". The reverse order (quotation first, claim later) is forbidden — the reader cannot tell what the quotation is for until they have read past it.

Bad example (quotation first):

```
The standard recipe of pretraining on huge corpora and then running classical preference-label RLHF is now widely treated as obsolete.
```

[industry-tracker (2026/03)]

The mainstream has shifted to a modular post-training stack.

Good example (claim first):

The classical RLHF pipeline (human preference labels → reward model → PPO) is no longer used in leading models; it has been replaced by a modular stack that separates concerns.

```
The standard recipe of pretraining on huge corpora and then running classical preference-label RLHF is now widely treated as obsolete. Every leading model released in the past year uses a different post-training stack.
```

[industry-tracker (2026/03)]

## Source-reference label

Within the `[label (YYYY/MM), location]` structure defined in `documenting-with-sources`, the survey skill fills the label slot with the publication or source name (media name, site name, etc.). The location is omitted when it cannot be pinned down.

## Heading-content alignment

Section headings and the items placed under them must match exactly.

- If a heading is "human-side guardrails", only human conduct and discipline goes underneath. Tooling and CI/CD belong under a separate heading.
- If a heading is "failure cases", do not mix in success stories or recommendations.
- If a source spans multiple angles, either split it across the relevant sections, or place it under the most appropriate one and add an explicit note about the other angles.
- Before finalising, walk every heading and check that everything underneath it actually belongs there.

## Output destination

Write the deliverable to `{CWD}/reports/` as a `.md` file. Create the directory if it does not exist. Sub-agents that emit intermediate artefacts use the same directory.

## Workflow

1. From the user's request, identify the claim or hypothesis and the collection scope.
2. Design search queries for the scope (in multiple languages where appropriate).
3. Use parallel subagents by angle when available; otherwise investigate the identical angles sequentially with the same checklist.
4. Consolidate the results; the main agent assembles the final version.
5. Write out the deliverable to `{CWD}/reports/` as a `.md` file.
6. Record `audit_mode: parallel-subagents` or `audit_mode: sequential-single-agent`, completed checks, and limitations.

## Sub-agent delegation rules

When delegating to sub-agents, follow these. If unavailable, apply every item sequentially; do not skip checks.

- Split by angle and dispatch in parallel (e.g. "papers & academia", "media & blogs", "social media", "industry signals").
- Give each sub-agent the quality criteria and the conventions from `documenting-with-sources`. Re-emphasise "no fabricated associations or interpretations" specifically — sub-agents are particularly prone to drifting toward the calling-conversation context and inventing connections.
- Sub-agent output is not the final deliverable. The main agent performs:
  - Deduplication.
  - Information completion (filling in missing affiliations, citation counts, etc. via additional lookups).
  - Structural unification (tables, consistent section structure).
  - Separation of criticism from supporting evidence.
  - Explicit listing of investigation limits (information that could not be retrieved, unverified URLs, etc.).
  - Removal of fabricated associations (see the corresponding section in `documenting-with-sources`).
  - Heading-content alignment check (see above).

## Deliverable structure

```
# Survey of {topic}

Date: YYYY-MM-DD
Scope: {scope description}

## Table of Contents

1. [{angle 1}](#1-angle-1-slug)
2. [{angle 2}](#2-angle-2-slug)
...
N. [Criticism & concerns](#n-criticism-concerns)
N+1. [Overall assessment](#n1-overall-assessment)
N+2. [Investigation limits](#n2-investigation-limits)

## 1. {angle 1} (e.g. academic papers)
## 2. {angle 2} (e.g. media coverage)
## 3. {angle 3} (e.g. social-media reactions)
## 4. {angle 4} (e.g. industry signals)
## N. Criticism & concerns
## N+1. Overall assessment
## N+2. Investigation limits
```

Adjust the section layout for the topic.

## Table-of-contents requirements

Always place a table of contents at the top of the report, directly after the metadata block and before the body. Writing the report without a ToC is forbidden.

- If there are ten or more sections, or fifteen or more individual items (papers, articles, etc.), use a two-level ToC. Level 1 is the section name; level 2 is the section's main items (paper titles, article headlines, ...).
- For short reports (five or fewer sections, few items per section) a single-level ToC is fine.
- Provide anchor links. Use the renderer's slug rules (lowercased, spaces → hyphens, special characters dropped) for the link targets.
- Even when the slug rule is uncertain, write the link rather than dropping it; let the renderer slugify.
- ToC entries and section headings must match word for word. No abbreviation or paraphrase.

View saved version →

---
name: writing-quotation
description: Formatting rules for quoting external sources inside Markdown. Use fenced code blocks, pair original and translation, and place labeled source references after the fence. Use whenever writing or editing quotation blocks.
---

# Writing Quotation

Formatting rules for quoting external sources inside a Markdown document. Other skills that produce sourced deliverables (`survey`, `paper-details`, and similar) reference this one.

## 1. Why quote the original

A summary alone does not let the reader judge whether the writer's reading of the source is correct. Placing the original alongside lets the reader cross-check the writer's interpretation against the source itself. Quotations and prose (the writer's own summary or interpretation) must stay visually and structurally distinct.

## 2. Quotations always go inside code blocks

Quote external sources inside a fenced code block, regardless of content type — prose, prompt templates, code, XML-tagged text, anything. Do not use the blockquote syntax (`>`).

## 3. Structure of a quotation block

A quotation block has the following shape.

- Opening code fence
- Original text
- One blank line
- Translation into the writer's working language (only when the source is in a different language)
- Closing code fence
- The source reference `[label (YYYY/MM), location]` on the line immediately after the closing fence

Rules:

- Original and translation sit together inside the same code block.
- One blank line separates them.
- Do not insert a horizontal rule (`---`) between original and translation.
- Do not move the translation outside the code block. Do not put it in parentheses next to the original.
- The source reference belongs on the line after the closing fence as an independent line. Never inside the code block.

## 4. Examples

### 4.1 Same-language quotation

When the source and the writer share a working language, no translation is needed:

```
Composability is the property by which a system's behaviour is determined by the behaviour of its parts and the rules under which they are combined.
```

[example-handbook (2026/04), Section 2.1]

### 4.2 Cross-language quotation

When the source is in a language other than the writer's working language, place the translation as a separate paragraph inside the same code block:

```
Le sens d'une expression complexe est déterminé par le sens de ses constituants et par les règles qui les combinent.

The meaning of a complex expression is determined by the meaning of its constituents and the rules that combine them.
```

[example-handbook (2026/04), Section 2.1]

### 4.3 Prompt-template quotation

Prompt templates use the same rule. Wrap inside a code block; place the source reference after the fence.

```
Human: You are an assistant who summarises research papers. The paper is enclosed in <paper> tags. Produce a summary enclosed in <summary> tags. <paper>P</paper> Assistant:
```

[example-prompt-library (2026/04), template 03]

### 4.4 Short-form role markers in translations

When translating a prompt template (Human/Assistant style), the translation side may abbreviate role markers to reduce cognitive load and to make it easier to tell original from translation at a glance.

- `Human:` → `H:`
- `Assistant:` → `A:`

Keep the original side unabbreviated (`Human:` / `Assistant:` in full). The trailing `Assistant:` at the very end of a chat template (the position that signals where the response begins) carries structural meaning and may be left as `Assistant:` on the translation side as well.

## 5. Source-reference format

Format: `[label (YYYY/MM), location]`.

- `label`: an identifier for the source. The calling skill decides the convention (author short-form, publication name, etc.).
- `(YYYY/MM)`: year and month. Do not include the day. If only the year is known, use `(YYYY)`.
- `location`: where in the source the cited passage lives (`p.4`, `Section 3.1`, `Figure 2`, `(15)`, `opening`, `final paragraph`, etc.). Omit when it cannot be pinned down.

If there is no location, write `[label (YYYY/MM)]`.

### 5.1 No bare numeric references

Do not use bare numeric references like `[1]` or `[2]`. The reader has to bounce between text and bibliography to learn what each number means. Use a label-based form that identifies the subject directly inside the text.

## 6. Anti-patterns

Anti-pattern 1 — using blockquote syntax (`>`):

A line starting with `>` is not acceptable for an external quotation. Always wrap inside a code block (see Section 2).

Anti-pattern 2 — translation outside the code block:

```
Composability is the property by which ...
```

The translation appears here as prose, outside the code block. [example-handbook (2026/04), Section 2.1]

Fix: place original and translation inside the same code block, separated by one blank line.

Anti-pattern 3 — translation in parentheses next to the original:

```
Composability is the property by which ... (Inline translation in parentheses ...)
```

[example-handbook (2026/04), Section 2.1]

Fix: original and translation are independent paragraphs inside the same code block, separated by one blank line.

Anti-pattern 4 — source reference inside the code block:

```
Composability is the property by which ...

Translation here ...
[example-handbook (2026/04), Section 2.1]
```

Fix: the source reference goes on the line after the closing fence as an independent line.

Anti-pattern 5 — bare numeric source reference:

```
Composability is the property by which ...

Translation here ...
```

[1]

Fix: use a label that identifies the source directly (author short-form or publication name).

Anti-pattern 6 — horizontal rule between original and translation:

```
Composability is the property by which ...
---
Translation here ...
```

[example-handbook (2026/04), Section 2.1]

Fix: separate original and translation with one blank line. No horizontal rule.

## 7. Scope

This skill defines the format of quotations only. *When* to quote (Assertion-Evidence ordering, what label to use, etc.) is decided by the calling skill.

- `survey`: Assertion-Evidence ordering — state the claim in prose first, then back it up with a quotation. The `label` slot holds the publication or source name.
- `paper-details`: References to the paper under review omit the author and use position only (`[p.X, Section Y.Z]`). References to other works use `[author-short (YYYY/MM)]`.