Enrich Article

Article Enrichment Skill

Enrich an existing blog article with documentation cross-links, tooltips, admonitions, and content annotations: $ARGUMENTS

Layout reference: the full artifact layout is specified in .claude/article-pipeline.md. This skill reads the published article and the cumulative enrichment-notes.md from the matching session folder under .article-work/{date}-{slug}/. The notes file holds contributions from brainstorm, write, and grill — treat it as the layered baseline.

You are an automatic article enricher. Your job is to take a finished blog article and enhance it with mkdocs-material features that connect the article to the OpenCQRS documentation, provide readers with contextual explanations, and improve the reading experience. A key goal is to break up the wall of text — admonitions, annotations, and cross-links add visual variety and interactive elements that make the article more approachable and less monotonous. You do this without changing the article's content, structure, or wording — you only add enrichment on top.

Workflow

Step 1: Read the Article, the Companion Notes, and the Documentation Structure

1. Read the article file at the path provided in $ARGUMENTS. If no path is provided, list files in mkdocs/docs/blog/posts/ and ask which article to enrich.
2. Extract the article's slug from its frontmatter. Locate the matching session folder under .article-work/ by looking for a folder whose name ends in -{slug} (typical pattern .article-work/{YYYY-MM-DD}-{slug}/). If multiple match, pick the most recent date prefix.
3. Read enrichment-notes.md from that session folder if it exists. The file is cumulative: it contains one ## From {skill} ({date}) section per upstream contributor (brainstorm, write, grill). Read all contributor sections — they layer on top of one another. Treat the union of all sections as the starting baseline for enrichment. Apply each item unless it violates the global rules in this skill. The ## From grill-article section in particular contains Open for Reflection (sidebars / annotations that surface unresolved tensions the author wanted to acknowledge) and Intentional / Defended (companion admonitions for strong claims the author chose to defend) — both are first-class enrichment input. If the file is missing entirely, fall back to enriching the article on its own — do not fail.
4. Read mkdocs/mkdocs.yml to understand the full navigation structure and available documentation pages.
5. Read mkdocs/includes/glossary.md to know which abbreviations already have global definitions.
6. Scan the documentation pages under mkdocs/docs/reference/, mkdocs/docs/concepts/, mkdocs/docs/tutorials/, and mkdocs/docs/howto/ to build a mental map of what documentation exists and what terms map to which pages.

Step 2: Identify Enrichment Opportunities

If an enrichment-notes.md exists, use the union of all contributor sections as your baseline. Iterate through each item and translate it into the corresponding enrichment type below:

• Collapsible Deep Dives → collapsible ??? tip / ??? info admonitions
• Cross-Link Targets → cross-links
• Admonitions list → admonitions
• Abbreviation Tooltips → abbreviation definitions at the file end
• Content Annotations → { .annotate } markers
• Open for Reflection (grill section) → typically a ??? tip "Worth Considering" collapsible admonition, occasionally an annotation
• Intentional / Defended (grill section) → typically a ??? info "Why we chose this framing" collapsible admonition that acknowledges the trade-off without weakening the article's voice
• External References → grounding inside admonitions (do not invent links to external sites unless the URL is in the notes)
• Code Reference Hints → anchor points for annotations or admonitions
• Style/Voice Notes → constraints to respect throughout

If two contributor sections name the same target (e.g. brainstorm and write both flagged the same cross-link), treat it as one enrichment but mention both in the coverage report. Brainstorm and write contributions reflect the author's pre-grill intent; grill contributions reflect what the article looked like under adversarial inspection — both are signal.

In addition, analyze the article for further enrichment opportunities using the categories below. Good and sensible enrichments beyond what the notes contain are welcome — the notes are a foundation, not a ceiling.

A) Cross-Links to Documentation

Identify domain-specific terms and concepts that have a corresponding documentation page. Common linkable terms include but are not limited to:

This table is a starting point, not an exhaustive list. Always check the actual documentation structure for additional matches. Use relative paths from the blog post's location to the documentation target.

Linking frequency: once per section. Link a term the first time it appears within each ## section. Do not link the same term again within the same section. If the term reappears in a later section, link it again on its first occurrence there.

Link formatting: Follow the article's existing style conventions. In articles that bold all links, use **[term](path)**. In articles without bold links, use [term](path).

Do not link terms inside code blocks, headings, or admonitions.

B) Abbreviation Tooltips

Add *[Term]: Explanation definitions at the very end of the article for technical terms that benefit from a mouseover tooltip. These create automatic tooltips on every occurrence of the term throughout the article.

Do not duplicate terms that already exist in mkdocs/includes/glossary.md — those are auto-appended globally. Only add article-specific terms.

Good candidates for abbreviation tooltips:

• OpenCQRS-specific concepts (e.g., *[CommandRouter]: The core component in OpenCQRS that routes commands to their registered handlers and manages write model reconstruction)
• Domain-specific jargon used in the article's fictional domain
• Architecture patterns mentioned but not deeply explained in the article

Keep definitions concise (one sentence) and include the OpenCQRS connection where relevant.

Aim for 5 to 15 abbreviation definitions per article, depending on the density of technical terms.

C) Admonitions

Insert admonitions where they add genuine value. Use them to:

• !!! info "OpenCQRS Feature" — Point out that a concept discussed in the article maps directly to an OpenCQRS feature, with a brief explanation of how OpenCQRS implements it.
• ??? tip "Deep Dive" (collapsible) — Offer additional context or nuance that would interrupt the article's flow if inline, but is valuable for curious readers.
• !!! warning — Highlight common pitfalls or mistakes related to the topic.

Prefer collapsible admonitions (???) over static ones (!!!). Collapsible admonitions are visually appealing, invite exploration, and break up the wall of text without overwhelming the reader. They are a key tool for making the article feel interactive and layered. Use static !!! admonitions only for critical warnings or information the reader must not miss.

Placement rules:

• Place admonitions between paragraphs, never inside a paragraph.
• Do not place admonitions inside code block framing (between the intro paragraph and the code block, or between the code block and the explanation paragraph).
• Use 3 to 6 admonitions per article, distributed across sections. Collapsible admonitions (???) can be used more generously than static ones.
• Admonition content should be 2 to 4 sentences.

Admonition syntax:

!!! info "Title Here"
    Content of the admonition. This should provide
    additional context that connects to OpenCQRS or
    deepens understanding.