danicat/speedgrapher/publish

Publish: Editorial Review, Inline Annotations & SEO/GEO Release Gate

publish is Speedgrapher's unified quality and release gate. It operates in two progressive stages mirroring Speedgrapher's two-plane architecture:

• Stage A (Prose & Structural Review — All Markdown Files): Audits readability (fog), AI-trope density (slop), static grammar/style (vale), macro-narrative flow, and bidirectional inline review comments (<!-- review: ... -->).
• Stage B (Second-Plane Technical SEO, GEO & Localization — Blog Posts & Web Pages): Audits discoverability via the seo MCP tool (doc_type: "page" or "doc"), enforces the dual-purpose frontmatter split (summary vs. description), validates Generative Engine Optimization (GEO) signals, and guides idiomatic multi-language localization.

1. Two-Stage Review & Release Pipeline

flowchart TD
    Target["Target Markdown File (.md)"] --> Comments{"Inline `<!-- review: ... -->`\nMode?"}
    Comments -->|Resolve Human Comments| Resolve["Rewrite targeted paragraphs\n& remove resolved comment tags"]
    Comments -->|Annotate File In-Place| Annotate["Insert `<!-- review: [Dim] ... -->`\nbelow flagged paragraphs"]
    Comments -->|Standard Audit| StageA["Stage A: Prose & Narrative Audit\nRun `fog`, `slop`, `vale`"]
    Resolve --> StageA
    Annotate --> StageB
    StageA --> StageB["Stage B: Second-Plane `seo` Gate\nRun `seo` (`page` or `doc`), GEO & Localization"]
    StageB --> Output["Deliver Scorecard, Indexed Fixes\n& Release Checklist + Speedgrapher Pill"]

Whenever you review or prepare a .md file for release, always surface the side-panel pill at the top of your response:

Open file.md to inspect live diagnostics, inline comments, and SEO telemetry in the side pane.

2. Stage A: Prose Quality Gate & Inline Review Comments (All Markdown Files)

A. Quantitative MCP Prose Diagnostics

Run fog, slop, and vale on the target .md file using its absolute path:

B. Qualitative Editorial Audit Criteria

Inspect the manuscript line by line against six qualitative standards:

1. Inverted-Pyramid & Macro-Narrative Momentum: Does the opening 150 words state the core problem, solution, and headline metric? Do later sections maintain forward momentum without re-litigating the introduction?
2. Functional Precision vs. Status-Signaling Jargon: Are domain acronyms defined on first use? Have bureaucratic noun stacks been replaced with active verbs?
3. Canonical Citation Hygiene: Are tools, libraries, and open standards hyperlinked by their canonical name on first mention (for example, [Model Context Protocol](https://modelcontextprotocol.io)), with zero bare URLs printed in prose?
4. Grounded Code Pedagogy: Is every code block introduced with why before how?
5. Sentence-Case Headings: Do all headings (H1–H4) use strict sentence case?
6. Google Developer Brand & Legal Safety: Flag unverifiable superlatives ("fastest", "best"), possessives on product names ("Google's Cloud Run's"), unsubstantiated claims, or mentions of unreleased roadmaps ("coming soon").

C. Bidirectional Inline Review Comment Workflow (<!-- review: ... -->)

Speedgrapher uses HTML comments placed immediately below a paragraph as a zero-lock-in review bus, written either as plain <!-- review: ... --> tags or with UI metadata attributes <!-- review(id="...", quote="...", ts="..."): ... -->:

1. Resolving Human Comments (`Human -> Agent`):

• When the file contains <!-- review: ... --> or <!-- review(...): ... --> comments added by the author, locate every comment block.
• Edit the preceding paragraph (or add the requested code/table) to fulfill the author's note while keeping fog ($12\text{–}14$) and slop ($< 20$) in bounds.
• Delete each resolved `<!-- review: ... -->` or `<!-- review(...): ... -->` comment from the file once addressed.

1. Injecting Agent Annotations (`Agent -> Human`):

• When the user asks you to annotate the file in place or leave inline review comments (instead of rewriting the prose directly), insert concise <!-- review: [Dimension] Concrete recommendation --> comments directly beneath the affected paragraphs:

``markdown The orchestration layer utilizes a distributed lock methodology to facilitate state synchronization across worker nodes. <!-- review: [Readability / Slop] Replace noun stack and corporate verbs ("utilizes", "methodology", "facilitate") with direct active prose: "The coordinator acquires a Redis lease before syncing state across worker nodes." --> ``

D. Mandatory Stage A Output: Scorecard + Line-Indexed Recommendations

Structure every editorial review using this exact template so the author can evaluate and apply findings by ID:

## Editorial Review: `<filename.md>`
 
Open [file.md](sidecar://speedgrapher/panel/?file=/absolute/path/to/file.md)
 
### 1. Editorial Review Scorecard
 
| Dimension | Score / Status | Target | Assessment |
| :--- | :--- | :--- | :--- |
| **Readability (`fog`)** | `<score>` (`<N>` hotspot paragraphs) | `12.0 – 14.0` | `[Pass / Needs Simplification / Check Depth]` |
| **AI Slop (`slop`)** | `<score>/100` | `< 20` (Warn `>= 25`) | `[Pass / Minor Tells / High Slop Warning]` |
| **Static Analysis (`vale`)** | `<E> errors, <W> warnings` | Grammar clean; style informational | `[Grammar errors resolved; style warnings summarized for discussion]` |
| **Technical SEO (`seo`)** | `<score>/100` (`<N>/7` checks) | `>= 85` (`7/7` passed) | `[Summary of metadata, heading, alt-text, and link checks]` |
| **Narrative & Jargon Hygiene** | `[Strong / Needs Tightening]` | Inverted pyramid & plain English | `[1-sentence assessment of 150-word lead, jargon, and citations]` |
 
### 2. Executive Assessment
[2–3 concise sentences summarizing the draft's core strengths, voice alignment, and highest-leverage improvements.]
 
### 3. Line-Indexed Recommendations
[Exhaustive numbered list of every specific issue identified. Never group distinct line edits.]
 
-`[1] Line <N> | Dimension: <Fog|Slop|Vale|SEO|Jargon|Narrative> | Context: "<exact excerpt>" | Suggestion: "<concrete rewrite or structural fix>"`
-`[2] Line <N> | Dimension: <Fog|Slop|Vale|SEO|Jargon|Narrative> | Context: "<exact excerpt>" | Suggestion: "<concrete rewrite or structural fix>"`

Unless the user explicitly asked you to auto-fix or annotate the file in a single pass, invite them to respond with selective commands ("apply all", "apply 1, 3, 5", "annotate in file", or "discuss 2").

3. Stage B: Second-Plane Technical SEO, GEO & Localization Gate

For blog posts, tutorials, and web documentation (doc_type: "page"), execute the full second-plane discoverability audit using the seo MCP tool.

A. The Dual-Purpose Metadata Split (title, summary, description, canonical)

Static site generators (Hugo, Astro, Next.js) and AI retrieval pipelines consume frontmatter fields for distinct purposes. Always separate the human feed teaser from the search/LLM factual answer:

---
title: "Zero-allocation JSON parsing in Go 1.27"
date: 2026-10-12
summary: "When our telemetry cluster hit 40% CPU in reflection stalls, we replaced encoding/json with a pre-compiled column reader."
description: "Learn how to build a zero-allocation JSON column reader in Go 1.27 that cuts CPU overhead by 44% and keeps p99 latency under 1.2 ms."
canonical: "https://example.dev/blog/zero-alloc-json-go/"
tags: ["go", "performance", "json", "memory-management"]
---

B. The 7-Point seo Verification Gate (checks[])

Run speedgrapher's seo MCP tool (path, doc_type: "page" for web posts or "doc" for repository docs, and target keyword) and verify all seven checks[] pass:

1. `Title Tag` (`30–60 chars`): Clear title frontmatter key or document # H1 between 30 and 60 characters (and containing the target keyword when provided).
2. `Meta Description` (`120–160 chars`): description frontmatter field (or <meta name="description">) present and between 120 and 160 characters (skipped in doc_type: "doc" mode).
3. `H1 Tag`: Exactly one H1 (# or <h1>) on the page, or a frontmatter title that renders as the page H1.
4. `Image Alt Text`: Every Markdown image (![alt text](path.png)) and HTML <img> tag carries non-empty alt text.
5. `Links`: At least one hyperlink ([anchor](url) or <a href="...">) connects the document to upstream documentation or related resources.
6. `Content Length`: At least 300 words for doc_type: "page" (or 100 words for doc_type: "doc").
7. `Canonical Tag`: canonical frontmatter key (or <link rel="canonical">) present for doc_type: "page" (skipped in doc_type: "doc" mode).

C. The 6-Point Generative Engine Optimization (geo_checks[]) Checklist

Alongside the 7 SEO checks, seo evaluates six geo_checks[] to maximize accurate citation by LLM search engines, RAG pipelines, and developer agents: