AI Assistant issues by goal

When the model should change or extend document blocks, it returns { "issues": [ … ] }. Pick the shape from what the author needs — not from the action name.

Related: Writing prompts · Backend examples · Annotations

Shared rules#

Every issue points at a block with id = that block’s uid.

Also:

• Return inner HTML only — no wrapping <p> / <h2> in the string.
• Only include blocks that actually change.
• Empty work: { "issues": [] }.
• JSON only — no markdown fences.

One rewrite for a block#

Need: replace the block with a single improved version (Improve, Shorter, Fix, Translate, Ask AI, …).

Use top-level content or items — no suggestions.

{
  "issues": [
    {
      "id": "uid-1",
      "type": "Rewrite",
      "description": "Clearer opening sentence.",
      "tag": "p",
      "content": "Revised inner HTML here."
    }
  ]
}

For lists, use items instead of content.

Several alternate rewrites#

Need: let the author pick among full draft variants (Expand ideas, Lead text with variants, …).

Use suggestions. Do not also put a top-level content when suggestions is present.

suggestions may be:

• strings — each string is one full body, or
• objects — { "content": "…" } or { "items": […] } for lists.

Optional options can add short labels aligned with suggestion order (same index = same variant).

{
  "issues": [
    {
      "id": "uid-1",
      "type": "Expand ideas",
      "description": "Three ways to develop this point.",
      "tag": "p",
      "suggestions": [
        { "content": "… explanation angle …" },
        { "content": "… example angle …" },
        { "content": "… contrast angle …" }
      ],
      "options": [
        { "type": "explanation", "text": "Explain the idea" },
        { "type": "example", "text": "Add a concrete example" },
        { "type": "contrast", "text": "Compare with the opposite" }
      ]
    }
  ]
}

String-only form (e.g. lead variants):

{
  "id": "uid-first",
  "type": "add",
  "description": "Opening leads for the piece.",
  "block": "text",
  "tag": "p",
  "suggestions": [
    "Lead variant one.",
    "Lead variant two.",
    "Lead variant three."
  ]
}

Ideas only — no body text#

Need: guidance or angles the author can follow, not ready-to-paste paragraphs (Explore directions, Suggest new angles).

Use options only. No content, items, or suggestions.

{
  "issues": [
    {
      "id": "uid-1",
      "type": "Explore directions",
      "description": "This claim can be developed further.",
      "tag": "p",
      "options": [
        {
          "type": "development",
          "text": "Continue the logic: what happens if the claim is true?"
        },
        {
          "type": "example",
          "text": "Add a short real-world example that supports the claim."
        },
        {
          "type": "next-step",
          "text": "State the practical next step for the reader."
        }
      ]
    }
  ]
}

Each options[].text should be concise and actionable. type is a short machine-friendly key for your UI.

One rewrite plus explanatory notes#

Need: a single accepted body, plus reference notes (why it changed, what was weak, how to go further) — e.g. Plain language.

Use content / items and options. Notes are read-only; they are not alternate drafts.

{
  "issues": [
    {
      "id": "uid-1",
      "type": "Plain language",
      "description": "Shorter sentences, everyday words.",
      "tag": "p",
      "content": "Revised plain-language HTML.",
      "options": [
        { "type": "why-changed", "text": "Why this rewrite is clearer." },
        { "type": "why-weak", "text": "What was unclear in the original." },
        { "type": "stronger", "text": "Optional idea to push it further." }
      ]
    }
  ]
}

Insert a new block#

Need: add a heading, paragraph, list or table before an existing block — not replace it (Headings, Enrich structure, Lead text).

Set type to "add" (or "insert"). id is the uid of the block before which to insert. Include block and tag, plus content or items.

{
  "issues": [
    {
      "id": "uid-of-existing-block",
      "type": "add",
      "description": "Breaks up a long section.",
      "block": "heading",
      "tag": "h2",
      "content": "Section title"
    }
  ]
}

To offer several insert bodies, combine "add" with suggestions (see Lead text above) instead of a single content.

Inline wording alternatives#

Need: keep most of the sentence, offer synonyms for key phrases (Better wording). Uses Annotations in the editor.

1. Wrap each phrase in <span data-block="wording">…</span> inside content.
2. Put matching alternative lists in annotations — same order as the spans.

{
  "issues": [
    {
      "id": "uid-1",
      "type": "Better wording",
      "description": "Alternative wordings for key phrases",
      "tag": "p",
      "content": "We should <span data-block=\"wording\">accelerate</span> the launch.",
      "annotations": [
        ["speed up", "bring forward", "fast-track"]
      ]
    }
  ]
}

Rules:

• Only data-block="wording" on spans — no data-ref, class, or other attributes.
• First span ↔ first annotations array, and so on.
• Each inner array: 2–3 non-empty strings.
• Skip blocks with nothing to mark.

Nothing to change#

Always allow an empty list:

{ "issues": [] }

Quick chooser#

Do not mix competing body fields on one issue: either a single content/items, or suggestions, or guidance-only options — not all at once (except the intentional “rewrite + notes” pattern).

Apply mode (better-wording)#

Most issue shapes above are reviewed in the UI (mode: review): the author accepts or rejects each card.

Apply mode applies the model result immediately. The built-in case is Better wording: same issues contract as Inline wording alternatives — wording spans in content plus annotations.

Your prompt should still return:

{
  "issues": [
    {
      "id": "<uid>",
      "type": "Better wording",
      "description": "Alternative wordings for key phrases",
      "tag": "<same as input>",
      "content": "<inner HTML with wording spans>",
      "annotations": [
        ["alternative 1", "alternative 2", "alternative 3"]
      ]
    }
  ]
}

The editor applies those spans and annotations without a separate review step. Keep the JSON identical to the review-style wording shape so one template works for both mental models; only the request mode changes how the client uses it.

Next: wire templates into an endpoint — AI Assistant backend examples.