# Copywriting

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 29-38 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 39-43 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 44-53 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 54-69 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 70-76 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 77-86 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 87-98 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 99-117 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 118-130 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 131-142 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 143-156 |
| [Verification](#verification) | Evidence required before reporting success. | 157-172 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 173-183 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 184-193 |
<!-- END GENERATED: guide-map -->

Create, critique, and verify grounded outbound copy and personalization.

## Purpose

Copywriting owns the message from evidence brief through reviewed, rendered
variants. It turns verified recipient, company, sender, offer, and timing facts
into specific language that fits the requested channel and commercial goal.

It does not own discovering those facts or delivering the message. Research,
sequence activation, and external sends stay with their outcome guides so a good
draft cannot silently become an unsupported claim or an unintended action.

## Use This When

Use this guide for email or LinkedIn copy, sequence language, personalized
snippets, or copy review. Sending and publishing remain separate effects.

## Do Not Use This For

| Task | Owning Reference |
| --- | --- |
| Finding or enriching recipients and companies | `contact-search.md`, `contact-enrichment.md`, `company-search.md`, or `company-enrichment.md` |
| Building and activating a multistep campaign | `outbound-campaigns.md` |
| Sending a reply in an existing conversation | `inbox-and-replies.md` |
| Performing a LinkedIn connection, message, or post action | `linkedin-outreach.md` |
| Proving the final artifact or report rather than its copy | `artifacts.md` |

## Mental Model

Treat copy as a traceable transformation:

1. An evidence brief states what is known, what is inferred, and what remains
   unknown.
2. A message contract defines recipient, sender, channel, objective, offer,
   CTA, constraints, and required variables.
3. Drafting produces variants without promoting an inference into a fact.
4. Critique tests evidence, specificity, usefulness, tone, and channel fit.
5. Rendering substitutes representative values and exposes broken variables,
   awkward fallbacks, and variants that only look correct as templates.

Personalization is not the presence of a merge field. It is a relevant,
supportable reason for this recipient to care now.

## Choose A Path

1. Establish the recipient, sender, value proposition, evidence, offer, and CTA.
2. Draft from verified facts and the requested channel constraints.
3. Run the copy critic and AI-tell review before showing or saving final copy.
4. Keep missing evidence visible instead of inventing personalization.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.personalization.generate` | Use to generate grounded one-off personalization after sender context, value proposition, CTA, and evidence are known. | `cta`, `sender_context`, `sequence_brief`, `type`, `value_prop` | `personalization_job` | [`copy.md`](copy.md) · installed SDK: `verbiflow/personalization.py:14-57` |
| `vf.copy.lint` | Use for fast local detection of mechanical AI tells, banned phrases, placeholders, and unsupported variables. | `text` | `copy_lint_result` | [`copy.md`](copy.md) · installed SDK: `verbiflow/copy.py:325-475` |
| `vf.sequences.verify_copy` | Use for backend sequence-channel and template-variable checks before saving or publishing sequence copy. | `steps` | `copy_verification` | [`sequence_authoring.md`](sequence_authoring.md) · installed SDK: `verbiflow/sequences.py:3682-3728` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`copy.md`](copy.md) | Grounded outbound drafting, personalization, review, and data contracts. | capability |
| [`sequence_authoring.md`](sequence_authoring.md) | Sequence structure, copy, variables, staging, and audience data contracts. | capability |
| [`copy_ai_tells.md`](copy_ai_tells.md) | Detect and remove predictable synthetic-writing patterns. | policy |
| [`copy_critic.md`](copy_critic.md) | Mandatory evidence, specificity, and quality review before copy ships. | policy |
| [`testing.md`](testing.md) | Semantic verification for rows, artifacts, Play outputs, reports, and effects. | policy |

## Preflight

Before drafting, establish:

- the intended recipient or audience and their stable identity;
- the sender identity, voice, and relationship to the recipient;
- the channel, length, formatting, and sequence-step constraints;
- the commercial objective, value proposition, offer, and one clear CTA;
- the evidence allowed for personalization, including source and observation
  time when freshness matters;
- required variables, their source fields, and the fallback or stop behavior
  when a value is absent;
- whether the request ends at a draft, saves platform state, or eventually
  hands off to an external action.

If a material claim has no evidence, stop at a clearly labeled assumption or
ask for the missing input. Do not make the sentence smoother by making it less
true.

## Risk And Side Effects

| Stage | Risk And Boundary |
| --- | --- |
| Brief and draft | Local or draft work. Preserve uncertainty and source identity. |
| Personalization or semantic review jobs | May consume credits. Bound the rows and preserve job or artifact handles. |
| Saving copy or sequence steps | Reversible platform write. Verify the saved draft or revision. |
| Publishing or sending | External effect owned by the campaign, inbox, or LinkedIn guide. Require clear intent at that boundary. |

The most common correctness risks are wrong-recipient facts, unsupported
flattery, stale events presented as current, variables with no value, and
generic claims disguised as personalization.

## Canonical Operating Pattern

1. Build the evidence brief and separate facts from inference.
2. Define the message contract and required variables.
3. Choose the smallest copy child that owns the work.
4. Draft a bounded set of materially different variants.
5. Run the evidence and specificity critic, then remove synthetic-writing
   patterns without flattening the voice.
6. Render every final variant with representative real values.
7. Verify the final copy and either return the draft or hand the exact reviewed
   revision to the owning effect guide.

## Data Contracts

Preserve enough structure to reproduce and review the copy:

| Record | Required Meaning |
| --- | --- |
| Evidence brief | Recipient/company identity, claim, source, observation time, confidence, and limitation. |
| Message contract | Channel, sender, audience, objective, offer, CTA, tone, length, and prohibited claims. |
| Variable contract | Variable name, source field, requiredness, example value, and missing-value behavior. |
| Final variant | Stable variant identity, rendered subject/body or message, evidence used, review status, and owning draft/revision when saved. |

Do not let copy depend on hidden conversation context. Facts and variables used
by a saved draft must travel with its durable row or revision contract.

## Verification

Verify factual grounding, recipient relevance, specificity, channel fit, CTA,
variable coverage, and every final rendered variant.

Inspect both the template and representative rendered messages. Confirm that:

- every personalized claim resolves to evidence for the same recipient;
- the first lines communicate relevance without relying on vague praise;
- the value proposition and CTA are concrete and mutually consistent;
- required variables have coverage and missing values fail or fall back as
  designed;
- sequence variants preserve their intended role instead of repeating the same
  message;
- the exact reviewed revision is the one saved or handed to an effect owner.

## Troubleshooting

| Symptom | Likely Cause | What To Do |
| --- | --- | --- |
| Copy sounds polished but generic | The brief has no specific evidence or commercial tension | Return to the evidence brief; do not add decorative personalization. |
| Personalization belongs to another person or company | Identity was lost during a join or row transform | Re-check stable recipient and company keys before redrafting. |
| Rendered text contains blanks or placeholders | Variable mapping or fallback behavior is incomplete | Measure variable coverage and render representative rows before saving. |
| Variants repeat the same idea | Steps lack distinct objectives | Give each step one role in the sequence narrative, then rewrite. |
| Review removes all personality | AI-tell cleanup was treated as a style template | Preserve the sender's voice while removing unsupported or synthetic patterns. |
| Draft is correct but the sent message differs | The reviewed revision was not the effect input | Compare revision identity and rendered bytes at the handoff boundary. |

## Related References

| If You Are Doing This | Read Next |
| --- | --- |
| Grounded drafting and personalization mechanics | `copy.md` |
| Evidence and specificity review | `copy_critic.md` |
| Removing synthetic-writing patterns | `copy_ai_tells.md` |
| Sequence variables and step structure | `sequence_authoring.md` |
| Semantic verification before handoff | `testing.md` |
| Publishing or sending a campaign | `outbound-campaigns.md` |
