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/<slug>/locked-facts.json, and entity-profile.json (for voice/audience).

Workflow

0. 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, target_query, intent, entities_covered, internal_links, schema_type, locked_facts_used (start empty), sources (start empty).

2. 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.

3. 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.

4. Insert internal links from the brief with varied, descriptive anchors (internal-linking-rules.md).

5. 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.

6. 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 <draft.md> \
     --locked brands/<slug>/locked-facts.json --brief brands/<slug>/briefs/<slug>.json \
     --brand-terms "<Brand>" --json
   # (b) QUALITY — the number to optimize (target >= 80)
   python ../../scripts/draft_quality.py --draft <draft.md> --floor <800+ per node type> --json
   # (c) AEO — a FLOOR to clear (target >= 80), NOT a number to maximize
   python ../../scripts/aeo_score.py --draft <draft.md> --schema-dir brands/<slug>/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×.

7. 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.

8. Emit brands/<slug>/drafts/<node-slug>.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.