---
name: etal
description: Write, edit and check scientific prose with the Et Al. models. QED drafts academic text from the author's notes, or polishes and revoices a draft, in the author's own voice. Sic scores each sentence of a text for machine authorship. A check compares every output with its source. Use when the user wants to draft, polish or rewrite part of a paper, thesis, abstract or grant proposal, rewrite the prose of a LaTeX or Markdown file, see which passages of a text read as machine-written, or prepare an AI-use disclosure statement.
compatibility: Needs Python 3.8 or later and network access to api.etal-labs.com. The first sign-in needs a browser.
metadata:
  version: "1.0"
  homepage: https://etal-labs.com/docs/skill
---

# Et Al.: QED and Sic

Two models for scientific writing, used through one script in this skill's directory.

- **QED** writes. It turns notes into academic prose, or edits a draft, in the voice of passages the author supplies.
- **Sic** reads. It scores each sentence of a text for machine authorship against two calibrated thresholds.

The commands below are written as `etal …`. That is short for `python3 <this skill's directory>/scripts/etal.py …`.
The script uses only the Python standard library. `etal <command> --help` lists every option, and `--json` returns
the raw API response.

## Who does what

You do the research, the outline and the fact-checking. QED cannot use tools and knows nothing beyond the text you
give it. It can drop or alter a number, a hedge or a citation, which is why every output is checked against its
source. The author decides what goes into the manuscript.

## First use

1. Run `etal status`. If it reports an account, you are set up.
2. If not, run `etal login --start`. It prints a link and a short code, opens the link in the user's browser if it
   can, and returns at once.
3. Tell the user in one message: open the link (sign in or create a free account there), confirm that the page
   shows the same code, and approve. If the output says no browser was opened, they need to open the link
   themselves.
4. Run `etal login`. It waits up to 100 seconds for the approval and stores the key. If it ends with "Not approved
   yet", run it again once the user has approved; it continues with the same code.

Never ask the user to paste an API key into the conversation. If `ETAL_API_KEY` is set in the environment, the
script uses it and no sign-in is needed.

Every command except `login`, `logout` and `status` sends the text you give it to the Et Al. API. Before the first
one, tell the user once that their text goes to the API to be processed, and that Et Al. states it is not stored.

## Workflow

### 1. Get the author's voice

Ask the author for two or three passages of their own writing, 150 to 350 words each, written without AI help.
Published text is best. Save them in one file, separated by lines of `---`, and pass it as `--voice voice.md`.

Without voice passages QED writes in a neutral academic register. Do not write the passages yourself, and do not
use text that a model wrote or edited: QED would imitate it. If the author can only give one passage, or short
ones, use them and say that the voice may come through weakly.

### 2. Draft from notes

Write the notes to a file, one point per line. Put in every fact, number and citation the passage should
contain; QED is told to add none.

    etal draft notes.md --title "Title of the article" --words 250 --voice voice.md --out intro.md

For a long document, draft one section per call and give QED the plan and the text so far:

    etal draft notes-3.md --title "…" --outline outline.md --section 3 --thesis "The overall point." \
        --so-far draft.md --voice voice.md --out section-3.md

`outline.md` holds one line per section, saying what the section does. `--title` and `--words` are optional. The
length follows the notes more than `--words`: for a longer passage, give more points. With `--out` the text goes
to the file and only the report is printed.

The draft is Markdown. To place it in a LaTeX file, turn `[@key]` into `\cite{key}`; math in `$…$` stays as it is.

### 3. Or rewrite existing text

A passage of up to about 400 words (Markdown in, Markdown out):

    etal rewrite passage.md --mode polish --voice voice.md      # light edit
    etal rewrite passage.md --mode revoice --voice voice.md     # full rewrite that keeps the content

Longer passages are edited lightly, and less towards the end. Do not split a long text silently; tell the author
what you are doing. Neither mode reliably corrects grammar or spelling: read the result and fix what is left.

A LaTeX or Markdown file:

    etal paragraphs paper.tex                                   # numbers the prose paragraphs; costs nothing
    etal rewrite-doc paper.tex --paragraphs 3-9 --mode revoice --voice voice.md

`rewrite-doc` writes a copy (`paper.etal.tex`) and never changes the original. Only prose paragraphs are
touched. Each paragraph is reported as:

- `rewritten`: the copy holds the new text;
- `unchanged`: QED returned the paragraph as it was (not charged);
- `reverted`: the rewrite lost a formula, citation, reference, label, footnote or macro, so the original was kept;
- `skipped`: the paragraph cannot be converted safely and was left alone.

It takes about 10 seconds per paragraph. For more than eight paragraphs, give the command a longer timeout or
work through the file in ranges; progress is saved to the copy as it goes. Show the author the difference between
the original and the copy before anything replaces the original.

`--voice-from-document` takes the voice from other paragraphs of the same file instead of from `--voice`. Use it
only when the author confirms they wrote the rest of the file themselves. On a machine-written or machine-edited
draft it would imitate that draft. Ask; do not assume.

### 4. Read the check

`draft` and `rewrite` compare the output with its source automatically, and `rewrite-doc` checks each paragraph.

- `[error]`: a number, citation key, formula or footnote is missing or new, or the claim check found a claim
  added, missing or changed. Fix every error before the text is used: correct it by hand against the source, or
  run the command again.
- `[review]`: a heuristic (hedging, negation, causal wording, length) with the sentence it fired on. It often
  fires on faithful text. Read the sentence and decide.

The claim check is one model's reading, not a validated scorer: verify what it quotes. After editing by hand, run
it again:

    etal check --source notes.md --output intro.md --kind draft
    etal check --source passage.md --output passage.new.md

### 5. See what reads as machine-written (optional)

    etal detect manuscript.md

Sic lists the sentences above its thresholds, and how often each threshold flags human-written text. Read it this
way:

- Only the two thresholds are calibrated. A score is not a probability, and a sentence below both carries no
  finding.
- Scores reflect the surrounding passage, so Sic locates machine-written passages, not single sentences.
- A flag is evidence, not proof. Do not use it to accuse anyone.
- Never rephrase text to lower a score. If a flagged passage is the author's and reads as generic, the remedy is
  substance: specifics, the author's own reasoning, their own wording.

Sic is calibrated on English scientific prose.

### 6. Offer the disclosure

Text made with QED is AI-assisted, and most journals ask authors to say so. At the end, offer:

    etal disclosure --style elsevier --sections "the Introduction and Discussion"

Styles: `generic`, `elsevier`, `icmje`, `springer`. The statement reports only what the account's request log
shows. Its last sentence, that the authors reviewed and edited the output, is theirs to confirm: show them the
"authors must confirm" list and do not present the draft as verified.

## Formats and limits

- Text is Markdown: math as `$…$`, citations as `[@key]`, footnotes as `[^1]`. LaTeX goes through `rewrite-doc`
  only. Convert Word files to Markdown first (for example with pandoc).
- Each call takes up to 2,000 words. Draft long documents section by section.
- Accounts are free within a monthly allowance. Every command that calls a model prints what it cost, and
  `etal status` shows how much of the allowance is used.

## Reporting to the author

Say plainly what QED wrote or changed, and show the check result with it. If a rewrite came back unchanged, say
so; do not present it as edited. If the check could not be run, say that too.

Documentation: https://etal-labs.com/docs/skill