| name | publish-insight |
| description | Author and publish a Mneme HQ insight article end to end. Use when asked to
"write an insight", "publish an article", "scope an article", turn a ChatGPT
"Post-*" scope thread into a page, or react to a report / launch / paper with
a governance-angle article. Encodes the SEO patterns, the publishing contract,
internal-link mesh, funnel, and accessibility so a new insight is born compliant.
|
publish-insight — author + register a Mneme insight, correctly, first time
The canonical contract is docs/site/insight-publishing-contract.md and
scripts/check_insights.py (the gate). This skill is the generation procedure;
the validator is the enforcement. Follow both.
1. Scope + SEO intent
- Lead the
<title>, <h1>, and meta with a recognizable entity (report
name + year, vendor, paper, launch, OSS project), then pivot to the governance
interpretation. Avoid abstract category-only titles (good for LinkedIn, weak
for SEO).
- Report response? Lead title/H1/meta with
[Report Name] [Year], add an
early What [Report] Shows H2, plant the report's own vocabulary in the body
and FAQ, and nest the source as isBasedOn → Report in the TechArticle
JSON-LD. Otherwise use the entity-anchor pattern.
- Read the source(s) in full and use verified facts/stats only; do not
attribute anecdotes to unverifiable named people — generalize them.
- One authoritative outbound reference (
target="_blank" rel="noopener"),
cited once.
2. Overlap check (do this before writing)
Grep site/insights/*/index.html for the theme. If a close article exists
(especially same source/report), either pick a genuinely differentiated angle
or update the existing page instead of shipping a near-duplicate. Shipping a
near-duplicate is a failure.
3. Write — clone the scaffold
Copy a recent exemplar (site/insights/ai-coding-agent-verification-tax/
standard, or bcg-ai-era-operating-models-governance/ for report-response).
Keep the <style>, global <nav>, site <footer>, and trailing <script>
blocks byte-identical (nav-footer-check + sticky-nav-check are strict).
Efficient method for a batch: write one golden file, Copy-Item to the other
slug dirs, then Edit only the per-article regions (title, meta, JSON-LD,
breadcrumb label, <article> body). A 5-line Read of a copy satisfies Edit's
read-precondition for whole-file edits.
Body structure: eyebrow + <h1> + .article-lede + byline; <h2> sections;
.callout; .gov-table; an <ol> Record/Retrieve/Check/Reject/Return loop
where it fits; 4-item FAQ (<details>); two .related-panel asides (concepts +
essays); .article-footer with .cta-block.
CTA ladder (order matters — highest-intent first): the .cta-block leads with
<a href="/pilot/" class="btn-primary">Request a pilot →</a> as its primary;
demote demo/GitHub to inline text links (style="display:inline-block; margin-right:1.25rem;color:var(--accent);font-family:'DM Mono',monospace; font-size:0.85rem;text-decoration:none;"). The newsletter subscribe <aside aria-label="Mneme HQ newsletter"> goes below the .cta-block (nurture for
the not-yet-ready reader — never above the pilot CTA).
4. The three quality rules check_insights now enforces
- Accessible links (HARD): include
.article-body a { color: #8be0c8; text-decoration: none; border-bottom: 1px solid rgba(139,224,200,0.4); transition: border-color 0.15s; } .article-body a:hover { border-bottom-color: #8be0c8; }. Teal (not the lime --accent/CTA colour), underlined (WCAG 1.4.1
— never colour alone), ~12.6:1 on #0c0c0d.
- Mesh (WARN, aim ≥3 inbound): cross-link 3–4 existing insights + 3–4
concepts in the body/related panels, AND add a reciprocal
related-essays
<li> into each neighbour article pointing back, matching that file's own
related-list format. A page reachable only from the hub is under-meshed.
- Funnel (WARN): include at least one contextual bottom-funnel link
(
/demo/, /pilot/, or /use-cases/...) in the body/CTA, beyond the GitHub
CTA and global nav — especially on buyer-intent (report/cost) pieces.
5. Register (every item; check_insights gates them)
site/sitemap.xml — add <url><loc>https://mnemehq.com/insights/<slug>/</loc><changefreq>monthly</changefreq><priority>0.8</priority></url>.site/insights/index.html — add the <a class="insight-card-link"> card in the right cards-grid and a matching {"@type":"Article",...} entry in the CollectionPage hasPart (both checked independently).- OG image — add a tuple to
TEMPLATES + NEW_MAP_ENTRIES in scripts/ensure_og_coverage.py, run it, then render only the new slug(s) (a temp Playwright loop or a narrowed TEMPLATE_MAP) — never the full generate_og_images.py. Confirm site/insights/<slug>/og.png exists.
- Head: canonical,
og:image + twitter:image → the article-local og.png; <nav class="breadcrumb-nav"> (3 items); BreadcrumbList JSON-LD (positions 1/2/3, exact item URLs); TechArticle JSON-LD (url == canonical, non-empty headline; isBasedOn Report for report responses).
6. Validate, then PR
Run python scripts/check_insights.py (must exit 0; read its WARN lines and
close the mesh/funnel gaps), plus check_nav_footer.py, check_sticky_nav.py,
check_encoding.py (save UTF-8, no BOM, preserve CRLF). Branch site/...,
squash-merge with a taxonomy-compliant title. Merge order matters if a deploy
tooling fix is in flight (see the deploy notes); the live deploy submits changed
URLs to IndexNow on success.
Anti-slop
Match the house voice: concrete, declarative, short sentences, specific worked
examples (the BillingService ADR). No "in today's fast-paced world", no
furthermore-chains, no em-dash-as-connective-tissue overuse. Two-quotes-max from
any copyrighted source; paraphrase practitioner quotes.
