# Building a Content Format in the CSA When you have a documented content format—a spec like [What to Know Next]({{ "/docs/what-to-know-next" | relative_url }})—and you need the CSA to actually generate it, you translate that spec into the **Content Format form** in the Admin Panel. This page is the durable how-to: what the form controls, where each kind of spec requirement belongs, and what lives outside the form entirely. Read it once before building any format; keep it open the first few times. This is a how-to for editors, not a content format spec. The format pages listed above it in the sidebar are the specs it references. ## The one thing to understand first **The form controls generation only:** the prompt, the word floor, the tone settings, and the extraction rules the AI follows when it writes a draft. Two consequences shape everything below: 1. **It never rewrites content.** No field shortens, edits, or alters what the AI produces. If a draft comes back too long, the system asks the AI to revise; the form only ever *extracts* pieces (like the headline) out of the output. 2. **It does not control the whole spec.** SEO title, dek, meta description, focus keyphrase, hero image, URL structure, tags, and the pre-publish review all live in the CMS / CUE (the McClatchy CMS) / editorial workflow—**not** on this form. Much of translating a format is knowing which requirements the form can hold and which it can't. See [What the form doesn't cover](#what-the-form-doesnt-cover). --- ## Three truths before you start - **Every save is a draft.** New format or edit, saving creates a draft that a `super_admin` reviews and approves. Plan for a short review cycle, not an instant change. Approved edits go live immediately; approved new formats land **Inactive** until you activate them (full mechanics in [What happens after you save](#what-happens-after-you-save)). - **Some choices are permanent.** The **Name (slug)** and the **Organization** scope cannot be changed after creation. Everything else is editable later. - **System formats are locked.** If the Edit button is greyed out, the format is marked `system` to protect core functionality. Ask a `super_admin` if it genuinely needs a change. **Where to find it:** Admin Panel → Content Formats → **+ New Format** (from scratch), or **Edit** on any format card. --- ## The translation pattern This section is the reusable core: a format spec is a bundle of different *kinds* of requirements, and each kind has one right home in (or outside) the form. Route by type: | The requirement is… | It goes in… | Why | |---|---|---| | Baseline tone / house style / sourcing standards shared with other formats | **System Prompt** (a dev-maintained file the format points to) | Keeps one source of truth; the file itself is changed only by a developer in the codebase. | | A rule that should apply to more than one format (quote handling, headline rules, citation integrity) | **Instruction Block** (ask a developer to add it, then toggle it on) | Inlined shared rules drift out of sync across formats over time. | | The format's **structural identity**: section order, callouts, pull quotes, fixed value lists, word-count split | **Prompt Template** | This is what makes the format unique; general rules belong above it. | | The shortest a draft may be | **Word Minimum** | A floor only—not a target, not a ceiling. | | A length **range or cap**, or section proportions (e.g. 25/30/45) | **Prompt Template** | The form has no upper-bound field; spell the cap and the split out in the prompt. | | How much creative variation is wanted | **Temperature** | 0.7 default; 0.9–1.1 for lifestyle/creative; 0.3–0.5 for structured formats (recaps, listicles) where consistency matters. A structured skeleton with a directional voice sits between—just below the 0.7 default (≈0.6). | | Pulling the headline out / measuring length / de-duplicating the headline | **the three output checkboxes** | Extraction only—they never change the writing. | | The generation token ceiling | **Max Tokens** | Default (65536) fits almost every format; change only on a developer's advice. | | SEO/meta, hero image, URL, tags, human review | **outside the form**—see below | The form doesn't reach these; routing them here silently drops them. | The easiest requirement to misroute is a **structural** one: putting a mandatory callout or a section split into a shared block, or hoping the System Prompt covers it. Structural identity always goes in the **Prompt Template**, stated explicitly—models otherwise default to the generic explainer shape. --- ## The form, field by field ### The basics | Field | What it controls | How to set it | |---|---|---| | **Name (slug)** *(required, permanent)* | The internal ID. | Lowercase with underscores (`what_to_know_next`). Appears in logs; can't be changed. Never name it after an internal project or vendor. | | **Display Name** *(required)* | What editors see in the picker. | Clear and brand-accurate ("Woman's World", not "Womans World"). Never use "AI", "generate", or "automated"—those are internal words, not user-facing. | | **Icon** | The emoji on the format card. | One distinctive emoji; defaults to a plain document. Pick something that reads at a glance against similar formats. | | **Category** *(required)* | The picker group. | When in doubt, **Editorial**—it fits most formats and is easy to change later. | | **Organization** *(permanent)* | Everyone vs. one org. | Default to **system-wide**. Restrict only for a real reason (brand voice, legal, contract). Org-specific copies fragment the library. | | **Description** | The card blurb. | One sentence on *when* to use it—not a restatement of the name. | ### Who can see it | Field | What it controls | How to set it | |---|---|---| | **Visible to Roles** | Which roles see the format in the picker. | Leave empty to show everyone (the usual choice). Restrict only for a specific reason—e.g. keeping marketing formats away from editorial users. | ### How the story gets written | Field | What it controls | How to set it | |---|---|---| | **System Prompt** | Which shared editorial-rules file the format follows. | Point to the shared baseline other explainer/recap formats use; leave **none** for a self-contained format. If no baseline in the dropdown fits, ask a developer whether one exists before defaulting to none. The file's *contents* are changed only by a developer—this field just picks the file. | | **Word Minimum** | The floor on draft length. | Default 300. Set it to your publication's real minimum (250–400 short-form, 800+ longform). Use 0 only when any length is fine. | | **Instruction Blocks** | Shared, reusable rule sets. | Toggle on the existing ones that apply. Need a brand-new rule for more than one format? Ask a developer to add it as a block—don't type it into the prompt. | | **Prompt Template** *(required)* | The format-specific instructions. | Carry the format's structural identity here. Keep general rules in the System Prompt / Instruction Blocks. See [Preview before you save](#preview-before-you-save) for how to test it. | ### Fine-tuning the AI | Field | What it controls | How to set it | |---|---|---| | **Max Tokens** | Upper limit on generation. | Default (65536) is fine for almost every format. | | **Temperature** | Creative variation. | 0.7 standard; 0.9–1.1 for creative/lifestyle; 0.3–0.5 for structured formats where consistency matters. A structured format that still needs a directional voice sits between—≈0.6. Pick one value; the field takes a single number. | ### Cleaning up the output These three checkboxes pull pieces out of what the AI writes—they never change the writing itself: - **Extract Headline**—pulls the headline out separately. - **Calculate Word Count**—measures the draft against the Word Minimum. - **Strip Headline From Body**—removes the headline from the body so it doesn't appear twice. For a standard editorial format, turn on all three. Turn off **Strip Headline From Body** only when repeating the headline in the body is intentional (e.g. social posts). --- ## What the form doesn't cover Several common spec requirements live outside the Content Format form. Flag these to whoever owns CMS/publishing configuration rather than forcing them into a form field: | Spec requirement | Where it actually lives | |---|---| | SEO title, dek, meta description, focus keyphrase | CMS metadata fields, filled at the article level | | Hero image specs (size, ratio, no logos/text/stock) | Image/asset guidelines enforced in CUE or the publishing checklist | | URL structure and suffix pattern | URL slug settings at the publishing level | | Tags (e.g. TH-CSA, The Commons) | The tagging step in CUE, per-article or per-org | | Pre-publish checklist / human review requirement | Editorial workflow, enforced by the team, not the form | Before assuming the Prompt Template must generate the H1 formula, SEO title, dek, and meta, **confirm with a developer which CMS fields this format's generation step actually populates.** Some are filled by the same generation step; some are not configured through this form at all. --- ## Worked example: What to Know Next The [What to Know Next]({{ "/docs/what-to-know-next" | relative_url }}) spec, mapped onto the form, shows the pattern in action: | Field | Enter | Why | |---|---|---| | Name (slug) | `what_to_know_next` | Matches the format name; permanent. | | Display Name | What to Know Next | Exactly as editors see it. | | Icon | 🔭 | Signals "looking ahead"; distinct from other explainers. | | Category | Editorial | A news explainer, not marketing. | | Organization | system-wide | Spec says all platforms, no org constraint. | | Visible to Roles | empty, or exclude `assuredintel_user` | An editorial format; exclude the marketing role, or leave empty if all editorial roles should see it. | | Word Minimum | 700 | The spec's 700–1,000 range is a floor here; the 1,000 cap and the 25/30/45 section split go in the prompt. | | System Prompt | the shared explainer baseline, if one is in the dropdown | The format needs no prompt of its own for tone/sourcing; ask a developer if you don't see a fitting baseline. | | Instruction Blocks | toggle the existing blocks for named-source attribution + headline rules | The spec requires named-source attribution for every causal claim in Section 2; if no such block exists, that's a developer ask. | | Temperature | 0.6 | A structured skeleton (fixed Status Bar values, exactly three signals) but a directional voice—between the 0.3–0.5 recap band and the 0.7 default, so just below default. | | Output checkboxes | all three on | Standard editorial; the headline shouldn't repeat in the body. | **Everything structural goes in the Prompt Template,** in order: the italicized **Status Bar** under the headline (all three fields filled from their fixed lists, never blank); a short forward-looking lede; **Section 1—What's Happening** (~25%, a snippet-ready, facts-only news lede); **Section 2—Why It's Happening** (~30%, 2–3 named/sourced causes); a **Forecaster Pull Quote** (named, titled, affiliated, forward-looking) placed anywhere in Section 2 or 3; **Section 3—What Could Be Next** (~45%, the longest section, 2–3 predictions paired with reader actions, closing on one clear takeaway); a boxed **Three Signals to Watch** callout (exactly three concrete, monitorable signals). State explicitly that Section 3 must be the longest section: models otherwise front-load the earlier sections and shortchange the payoff. The Prompt Template is prose instructions to the model. A skeleton for this format, which you'd flesh out with the spec's full wording: ``` Write a forward-looking explainer on {topic}, 700–1,000 words. Open with a one-line italicized Status Bar (Stage, Momentum, Forecast confidence — fill each from its fixed value list, never blank), then a 2–3 sentence forward-looking lede. Section 1 — What's Happening (~25%): a snippet-ready, facts-only news lede. Section 2 — Why It's Happening (~30%): 2–3 causes, each with a named source. Section 3 — What Could Be Next (~45%, the LONGEST section): 2–3 predictions, each paired with a concrete reader action; close on one clear takeaway. Place one Forecaster Pull Quote (named person, title, institution; forward-looking, not a definition) in Section 2 or 3. End with a boxed "Three Signals to Watch" — exactly three concrete, monitorable signals. ``` The [What to Know Next spec]({{ "/docs/what-to-know-next" | relative_url }}) is the authoritative source for the exact wording; use its Article Structure block as the scaffold. **Living outside the form for this format:** the SEO title, dek, meta description, focus keyphrase, hero image specs, URL pattern, tags, and pre-publish checklist—all routed to CMS/CUE/editorial per the table above. --- ## Preview before you save Every format has a **Preview** button that runs it against a pasted draft or a recent article, without creating a draft or touching anything live—so you can see what a format actually produces: whether the style guide and instruction blocks come through, and how word-minimum and headline handling behave. **One catch: Preview runs the currently saved version of a format, not your unsaved edits.** A brand-new format has nothing to run until you save it as a draft first. And editing an existing live format and then previewing won't show your change—so to test a change safely, ask a developer to clone the format into a scratch copy and preview there, the reliable path, since an approved edit to a system-wide format goes live immediately. For a structured format, confirm the unique pieces render (callouts, pull quote), that Section 3 comes out longest, the length lands *inside* the range rather than just above the floor, and any generated pull quote reads as forward-looking rather than a definition in disguise. --- ## What happens after you save - **You'll see a confirmation:** *"Draft submitted — awaiting super_admin approval."* Nothing is live yet. - **Where it goes:** an *edit* shows a pending-edit badge on the card; a *new format* appears in the Approval Queue. - **A `super_admin` reviews it** and either approves (with optional notes) or rejects (with a reason). - **If approved:** edits go live immediately; new formats are created **Inactive**—flip them to Active from the card when you're ready. - **If rejected:** the reason appears in the toast and the version history. Make the requested changes and resubmit. --- ## Common mistakes to avoid - **Editing System Prompt content in the form**—the field only *picks* the file; the content lives in the codebase and needs a developer. - **Scoping a format to one org "just in case"**—system-wide is almost always right; copies fragment the library. - **Typing shared rules into the Prompt Template**—inlined rules drift out of sync across formats; use an Instruction Block. - **Treating Word Minimum as a target**—it enforces a floor only. - **Using "generate", "AI-generated", or "automated" in the Display Name or Description**—reserved for internal messaging. - **Naming a slug after an internal project or vendor**—slugs appear in logs and are effectively permanent. --- ## When to loop in a developer or super_admin Ask *before* submitting the draft—it saves a review cycle: - You need a **new Instruction Block**, or a change to a **System Prompt** file. - You're unsure whether a format should be **system-wide** or org-scoped. - You want to **clone a format** into a scratch copy for testing. - A prompt pattern (a Status Bar, a Three Signals structure) is getting **reused** across formats—that's the signal to promote it into a shared Instruction Block instead of copy-pasting prompt text.