Semantic Draft Writer

semantic-draft-writer

Turn a brief into publishable copy that is deep, specific, extractive, and — the part other tools skip — factually honest. "Passes the validator" is the floor, not the goal: the goal is a piece genuinely worth reading. The draft is done when it is fabrication-clean AND clears the quality bar (or its remaining gaps are explicitly surfaced).

Read first: ../../framework/semantic-writing-rules.md (especially the Craft & depth rules 22–28), ../../framework/macro-micro-semantics.md. Load the brief, the node, brands//locked-facts.json, and entity-profile.json (for voice/audience).

Workflow

1. Scope depth and surface fact gaps FIRST. Before writing, list the concrete

specifics a strong piece needs — real examples, named entities, figures, a point of view — and check them against locked-facts.json + the brief. If the piece can only be written generically because the facts aren't there, that is a signal to ask the user for the missing specifics (real customer result, actual feature names, a workflow detail) rather than writing vague filler. Thin facts are the #1 cause of thin drafts.

1. Front-matter first. Emit the required block (semantic-writing-rules.md): node_id,

targetquery, intent, entitiescovered, internallinks, schematype, lockedfactsused (start empty), sources (start empty).

1. Draft for a reader, section by section along the brief's contextual vector. Lead a

section with the extractive answer (rules 3–4) THEN go deep: mechanism, a concrete example (rule 23), a trade-off, a real point of view (rule 26). Do not turn every H2 into a tiny Q&A (rule 27) — vary the shape. Declarative, specific, filler-free.

1. Honour the locks while writing:

• State a brand fact ONLY if it exists in locked-facts.json; when you use one, add

its key to locked_facts_used.

• State an external factual number ONLY with a citation; add the URL to sources.
• Where a figure would help but isn't grounded, write the honest version (mechanism/

range/"depends on…") — never invent one. Pull from the brief's do_not_fabricate.

1. Insert internal links from the brief with varied, descriptive anchors

(internal-linking-rules.md).

1. Editorial self-critique pass (before the gates). Re-read the draft as a skeptical

editor: Which section is thin? Where is there no example? What's the non-obvious point, and is it actually there? Cut every filler sentence. Rewrite the weakest section. Do this once before running the scorers — the gates confirm quality, they don't create it.

1. Three-gate loop — fabrication is a hard gate; quality is the target; AEO is a floor:

`` # (a) HARD GATE — must be 0 high, or surface remaining violations python ../../scripts/validate_draft.py --draft \ --locked brands//locked-facts.json --brief brands//briefs/.json \ --brand-terms "" --json # (b) QUALITY — the number to optimize (target >= 80) python ../../scripts/draft_quality.py --draft --floor --json # (c) AEO — a FLOOR to clear (target >= 80), NOT a number to maximize python ../../scripts/aeo_score.py --draft --schema-dir brands//data/schema --json ` Repair in priority order: fabrication first (never fix a fabrication by inventing a source — tell the truth or cut the claim); then work the draft_quality.py` fixes (deepen shallow sections, add the missing examples, cut filler, reach length through depth); then confirm AEO ≥ ~80. Do not sacrifice depth to push AEO past ~85 — a formulaic all-Q&A page is the failure mode this loop exists to prevent. Repeat ~2–4×.

1. Surface, don't hide. If violations or an unavoidable quality gap remain (e.g. the

piece stays generic because a brand fact the user hasn't confirmed is missing), STOP and list them with the exact sentences and the specific facts you need — rather than shipping filler or faking a source. These usually map to _pending_owner_confirmation.

1. Emit brands//drafts/.md; set node status: drafted.

Definition of done

• validate_draft.py: 0 high-severity violations (or remaining ones surfaced with rationale).
• draft_quality.py: >= 80 — every section has depth and a concrete example; filler

is gone; length reached through substance. This is the bar the writer is judged on.

• aeo_score.py: >= 80 (floor cleared; not maximized at the cost of depth).
• Front-matter accurate; reads as a genuine expert with a point of view, not a padded FAQ.

Grounding ladder

• T0: research external facts via web_search (cite them); brand facts from locked

ledger only.

• T1+: same rules; richer sourcing. Grounding tier never relaxes the fabrication

guard — it only changes where legitimate numbers come from.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: siddiqss
• Source: siddiqss/semantic-seo-suite
• License: MIT

Install and usage instructions live in the source repository linked above.