Scope

---
description: Establish or confirm a piece of writing's audience, tone, and purpose before reviewing it. Phase 1 of the writing pipeline — run standalone or via writing:full.
---

# writing:scope

Every other check in this pipeline (`writing:tone`, `design-doc-review:readability`, `technical-writing-coach`, `writing-humanize`) needs to know who the text is for and what register it should hit. Getting that wrong produces confident, precise feedback aimed at the wrong target — a PR description reviewed as if it were a design doc, or a blog post held to a design doc's decision-focus standard. This phase exists so every later check shares one answer instead of each guessing its own.

**Target**: {{args}} — a file path, or text already in context.

## Step 1 — Detect what you can before asking

Read the target and check for signals that already answer some of this:

- **Design doc / RFC**: a Status/Tracking/Decision-requested header, or it lives under a `design-docs`-style repo with its own house-style `CLAUDE.md` (check for one). If so, audience and tone are largely fixed by that repo's convention — don't re-litigate them, just confirm.
- **PR description / commit message**: git context (is this text going into `gh pr create --body` or a commit?) — audience is reviewers of this specific change, tone is terse and evidence-first per this repo's own CLAUDE.md if one exists.
- **Blog post / external-facing**: no internal jargon assumed, audience is whoever the platform's readership is.
- **Personal note / journal**: audience is future-you; tone should stay in the author's own voice — this is the one case where `writing-humanize`'s AI-tell removal matters most, since a note in someone else's cadence is actively worse than one in the author's.

If the type is unambiguous from context, state your read and move to Step 3 without asking. Only ask when it's genuinely unclear or when a decision only the author can make is in play (see CLAUDE.md's escalation rule).

## Step 2 — Ask what you can't detect

When ambiguous, ask in one pass (not one question at a time):

```
questions:
  - question: "Who's the primary audience for this?"
    header: "Audience"
    options:
      - label: "Expert peers in this domain"
        description: "Can assume shared jargon and context"
      - label: "Cross-functional / mixed technical background"
        description: "Define terms on first use, less assumed context"
      - label: "External / general readership"
        description: "No internal jargon, no assumed org context"
  - question: "What register should this land in?"
    header: "Tone"
    options:
      - label: "Formal / decision-document"
        description: "Structured, evidence-cited, matches this repo's house style if one exists"
      - label: "Direct / conversational"
        description: "Plain sentences, contractions fine, minimal hedging"
      - label: "Match my own voice"
        description: "Preserve the author's existing cadence — flag AI-tells (writing-humanize) more aggressively"
```

Never infer "formal" as the default just because the source reads dense — that density might itself be the problem this whole workflow was invoked to fix. Ask rather than assume when the current draft's register and the target register might be the same mistake.

## Step 2.5 — Voice profile (only when `tone` = "match my own voice")

"Conversational" and "direct" are adjectives a model fills in from its own defaults — every check
downstream of a vague tone label drifts back toward generic AI prose no matter how the label is
worded. When tone resolves to "match my own voice" (the design-docs repo declares this as its
*always* value, per its `CLAUDE.md`; other repos may reach it by explicit user choice in Step 2),
replace the adjective with an evidence-backed profile instead of passing the label downstream as-is.

**Look for a cached profile first**: `<repo root>/.claude/voice-profile.md`, scoped to the
repo/author, not the individual doc — the same person's voice doesn't change doc to doc, so this is
built once and reused, not re-derived per review. If it exists and the author hasn't obviously
changed since (check its own date stamp against how stale it looks — no hard TTL), read it and
carry it forward as-is.

**If it doesn't exist, build it**: pull 2-3 *unmodified* passages of the author's own prior writing
in this repo (verbatim — a summarized/flattened sample loses the sentence-rhythm and pacing that
carry most of the voice signal). Run an extraction prompt framed as "a forensic linguist analyzing
writing samples from one author," producing a profile across these named dimensions, each backed by
a quoted phrase from the samples as evidence, not an abstract adjective:

- **Tone & formality** — where on the spectrum, with a quoted example at that register
- **Vocabulary** — characteristic word choices, avoided words
- **Sentence structure** — length pattern, fragment/run-on tolerance, punctuation habits
- **Rhetorical moves** — how they open a section, transition, close, use questions/lists/asides
- **Perspective** — first person vs. we vs. passive, and when each shows up
- **Quirks** — anything person-specific and recurring (a phrase, a structural habit)
- **Emotional texture** — where certainty/hedging/humor actually appears, not where a generic writer would put it

Write the result to `<repo root>/.claude/voice-profile.md` so the next review in this repo reads
instead of re-derives it.

**Set expectations honestly**: even rigorous profile extraction narrows the gap between generated
and authentic text, it doesn't close it — treat the profile as a real quality improvement over a
vague adjective, not a claim that output becomes indistinguishable from the author's own writing.

## Step 3 — Record the scope

Hold the answer as: `{audience, tone, doc_type, purpose, voiceProfile}` (`voiceProfile` is `null`
unless Step 2.5 ran). Don't write a sidecar file for a one-off review — that's persistence for
something used once in this session; the voice profile is the one exception since it's repo-scoped
and reused across every future review, not a one-off. Otherwise pass scope directly into the next
phase's agent prompts.

State the resolved scope back to the user in one line before proceeding: `Scope: <doc_type>,
audience=<audience>, tone=<tone>[, voice profile: cached|built|none].`

## Handoff

`writing:full` calls this phase first and threads its output into every check agent's prompt in `writing:tone` and (if the target isn't already a design doc using `design-doc-review:review`'s own checks) `technical-writing-coach`.