Match Outline

Match outline (whole-document voice analysis)

This skill answers "does my draft's structure and voice match the field?" It compares a draft's conventions against a corpus profile, extracts voice persona blueprints from exemplar papers, and rewrites drafts as a whole document with a plagiarism guard.

It complements match-structure (which provides the quantitative metrics, frequency tables, and similarity math this skill imports) and filter-tells (which detects generic AI-writing patterns at the paragraph level).

The rewrite uses cohere:command-a-03-2025 by default (GH-184; MATCH_OUTLINE_MODEL or --model gpt-oss:120b-cloud for keyless/local). Pass --model claude-sonnet-5 to use the Anthropic API instead. AI-sounding output is expected at this stage — match-voice handles paragraph-level diction cleanup downstream.

Pipeline role: the caller's structural step (GH-208)

This skill is a document rewriter, not a stage of the humanize chain. A workflow command invokes it before humanize when the form needs changing — a venue profile's structural_step field names it for exactly that decision — and humanize's input contract assumes its work is already done. It rewrites at section level, which is a different operation with a different risk class than the chain's paragraph-level stages.

Verify content preservation after every rewrite, and include figure blocks. The built-in check covers citations and numbers; it does not cover figures. A 2026-08-31 run on the COMST introduction dropped an entire ![...](fig/...) figure block while reporting "all citations and numbers preserved." Until the check covers them, count ![ occurrences (and table and code-fence blocks) before and after, and diff the reference section verbatim. The rewrite also introduces typographic unicode (U+2011 non-breaking hyphens, curly quotes) that downstream gates normalize but this stage does not — normalize to ASCII before handing the output on.

Where things live

• Quantitative profile: <db-dir>/voice-profile.json, written by match-structure's style.py corpus.
• Qualitative profile: <db-dir>/voice-profile.md, written by the model following references/voice-analysis-instructions.md Part 1.
• Comparison reports: <db-dir>/voice-reports/<draft-stem>-voice.md, following references/comparison-report-template.md.
• Exemplar blueprints: <db-dir>/voice-blueprint-<slug>.md, extracted from chosen exemplar papers following voice-analysis-instructions.md Part 3 (consensus vs idiosyncrasy).
• Rewritten drafts: <draft-stem>-rewritten.md next to the draft. The draft itself is never modified.

Running the scripts

The scripts run in the pixi-managed environment that ships beside the skill (pixi.toml / pixi.lock at the agent-directory root). The agent provisions it on repo open via <agent-dir>/scripts/ensure-env.sh; then the commands below use $RUN for the wrapper:

RUN="pixi run --manifest-path <skill>/../../pixi.toml python"

The workflow (interactive)

1. Locate the corpus

Find references.yaml at or above the working directory. If it does not exist, or no entries have status: summarized with an existing md_path file, stop and tell the user to run update-references first.

2. Quantitative profiles

$RUN <match-structure>/scripts/style.py --db <db-path> corpus

This writes voice-profile.json. Skip if the existing profile is unchanged.

3. Qualitative profile

Read the corpus papers and write voice-profile.md following Part 1 of references/voice-analysis-instructions.md. Every claim carries a quote.

4. Compare the draft

$RUN <match-structure>/scripts/style.py --db <db-path> compare <draft.md>

Then write the comparison report following Part 2 of voice-analysis-instructions.md and the structure of comparison-report-template.md.

5. Report back

Summarize: the verdict (close match / partial / divergent), the two or three highest-impact changes, and the report path.

Exemplar blueprints (mimic a specific paper or venue)

When the user wants to mimic specific papers, extract a voice persona blueprint following Part 3 of voice-analysis-instructions.md.

Rewrite mode (opt-in)

Whole-document rewrite following references/style-application-instructions.md. The model receives the entire draft plus blueprint plus exemplar papers in one pass, preserving cross-section transitions and structural coherence. Paragraph structure may change freely — the model can merge, split, or reshuffle as the voice demands. After the rewrite: content preservation check (citations, numbers) and similarity guard via match-structure's style.py similarity.

Headless mode

match_outline.py runs every mode without an interactive session.

# Compare a draft
$RUN <skill>/scripts/match_outline.py <draft.md> --db <db-path>

# Extract a blueprint
$RUN <skill>/scripts/match_outline.py --db <db-path> \
  --exemplar paper1 --exemplar paper2 --name icml

# Rewrite a draft (uses cohere:command-a-03-2025 by default)
$RUN <skill>/scripts/match_outline.py <draft.md> --db <db-path> --rewrite

# A long chapter on a local model needs longer than the 600s default
$RUN <skill>/scripts/match_outline.py <draft.md> --db <db-path> --rewrite \
  --timeout 2400

--rewrite is one generation call, so the wait scales with the document rather than with how warm the model is: a 1,427-word chapter took 604s at 14.2 tok/s against an already-resident local model. Raise --timeout — or set MATCH_OUTLINE_TIMEOUT — instead of warming the model. The other two environment overrides are MATCH_OUTLINE_MODEL and OLLAMA_ENDPOINT, each the default for the flag of the same name.

Exemplar sources

Two sources of exemplars are accepted:

• references.yaml corpus (default) — the papers fetched by update-references, selected with --db.
• writing-voice/manifest.yaml — a curated exemplar directory. Pass --voice-dir <path> with optional --role, --anchor-tags, --stratum.

Dependencies

match_outline.py imports style from match-structure/scripts/ for corpus selection and the similarity guard. Default model is cohere:command-a-03-2025. Pass --model claude-sonnet-5 to use the Anthropic API (requires the anthropic package).