Train mode

The agent writes a short passage. The user rewrites it in their own voice. The agent studies the difference and proposes rules. Over many rounds and topics, the profile learns how the user writes.

This is the most important mode. Run it with care and keep the user's effort low: one passage, one rewrite, a short report, three yes or no questions at most.

Before the first round

Load the profile: base.md, profiles/<name>/rules.md, lessons.md, topics.md. If the profile does not exist, offer to create it with python3 <skill>/scripts/vf.py init --profile <name>, and ask the user for one line on what the voice is for and who reads it. Put that line in rules.md.
If you can run a shell, run python3 <skill>/scripts/vf.py next-round --profile <name>. It prints the next round ID, the file path and the last 5 topics used.
Ask nothing else unless the user gave no profile and you cannot infer one.

One round

Step 1. Choose the topic and focus

If the user named a topic, use it. Otherwise pick one from topics.md that is not among the last 5 used. Vary the kind of topic across rounds.
The focus is mixed unless the user asks for openings, closings, transitions or data. A focus round still has 1 or 2 paragraphs, but the passage gives that part more weight: a full opening, a closing, a hinge between two ideas, or a paragraph that presents numbers.

Step 2. Write the passage

Own-text rounds. If the user gives a text of their own (a file, a link, pasted text) or asks to "use my own text", do not write a passage. Pick 1 or 2 paragraphs from that text as the passage, preferring paragraphs that an analysis flagged as inconsistent or weak. Mark the round focus: own. The user rewrites the paragraph as they would write it today. These rounds show which habits are still theirs and which came from coauthors or an older style.

Otherwise, write 1 or 2 paragraphs, 120 to 250 words, in the profile's language and register, following the profile's brief.

Write plainly, like a competent generic writer. Do not stuff the passage with slop. The goal is to learn what the user adds and changes, not only what they cut. Slop cleanup is already covered by the generic rules.
Give it substance. Include a claim, a reason, and an example or a figure. A rewrite of empty prose teaches nothing.
Do not invent precise facts. Use well known facts, round figures you are sure of, or clearly hypothetical examples ("Suppose a survey finds..."). No made up quotes or citations.
How much of the profile to apply: if the profile has fewer than 5 rules, write neutrally. Otherwise apply about half the rules, chosen at random. Rules you applied will show up as CONFIRMED or CONTRADICTION, which tests them.
Provisional profiles (stage: provisional, derived from another language): apply the rules whose support is still transferred first (vf.py rules --profile <name> shows it), so each round tests them. Remind the user once per session that the profile is provisional.
Vary the shape across rounds: start with a claim in one round, with an example in the next, with a question in another.
If the user asks for a hard round, write in a typical AI style on purpose. Mark such rounds focus: hard so their lessons can be weighed with care.

Present it like this, then stop and wait:

Round 20261005-01 · economics-en · topic: poverty-lines

(passage)

Rewrite it in your voice. Reply OK if you would keep it as is, skip for another topic, or stop to end.

Step 3. Save the round

As soon as the rewrite arrives, save the round file before you analyze (format in profile-format.md). Put the rewrite in exactly as given. Do not fix its typos.

With a shell, run python3 <skill>/scripts/vf.py dup --profile <name> <round file>. If it reports a duplicate, tell the user and do not count the round as new evidence.
If the user replied OK, save the round anyway. An OK confirms the rules you applied and teaches nothing else.

Step 4. Compare

Compare the passage and the rewrite. Separate two kinds of change:

Content changes: the user fixed a fact, changed an opinion, added an argument. Note them, but they are not voice lessons.
Voice changes: how the user says things. These are the lessons.

Look at the ten sections of schema-nonfiction.md: architecture (openings, closings, order of moves), argument, paragraphs, discourse (transitions, relations between ideas), sentences (length and rhythm), vocabulary, voice (stance, hedges, how the reader is addressed), evidence (numbers and sources) and constraints (punctuation, banned words). Also note what the user cut and what they added.

With a shell, python3 <skill>/scripts/measure.py stats on the passage and on the rewrite shows sentence length, hedges and connectors before and after. Quote those numbers; do not estimate them.

Check each finding against rules.md, base.md and lessons.md:

NEW: not yet recorded.
CONFIRMED: matches a rule or lesson.
CONTRADICTION: the user did the opposite of a rule or lesson.

Step 5. Report briefly

Show at most 6 findings, most important first. Each finding gets one line and, when useful, one short before → after pair quoted from the texts.

Then propose at most 3 lessons. A good lesson:

is one checkable sentence the agent can follow when drafting;
would apply to other topics, not only this one;
names its section slug ([paragraphs], [voice]...) and scope (this profile, or base if it looks true in every language and register);
is a tendency, not a hard limit, when it comes from a measurement.

Ask for a decision on each: yes, no, or a better wording. Example:

Lessons

[paragraphs] Open the paragraph with the claim; give the figure after it. → yes / no / reword?

...

Step 6. Apply the decisions

yes, new lesson: add it to lessons.md with status candidate, its section slug as category, and this round as its first evidence. Add your draft of strength, kind, applies, except and check; the user approves them at promotion.
yes, matches a candidate: add this round ID and topic to its evidence, unless the ID is already there.
yes, matches a rule: nothing to change; the finding is a confirmation. Note it in the round's Decisions. If the rule is transferred (copied from another language), ask "Confirm <ID> for this language?" On yes, add this round's ID and topic to the rule's evidence; the rule becomes confirmed. That changes evidence, not wording.
contradiction confirmed by the user: add the round to the lesson's against (training rounds only; counterexamples from Analyze mode stay in the analysis record). If a rule has 2 or more rounds against it, propose to reword or drop the rule.
no: record it in the round's Decisions. If it was a new lesson, add it with status rejected so it is not proposed again.
Write the user's reworded version exactly as they wrote it.

Then fill the Findings and Decisions sections of the round file.

Step 7. Commit and continue

Save: python3 <skill>/scripts/vf.py save -m "train <profile> <round id>". It commits and pushes to the private repo if one is linked.

Then offer the next round in one line: "Next round? (new topic / same topic, other focus / stop)".

Promotion

Check for promotions every 5 rounds, when the user says "promote" or "status", and at the end of a session.

Run python3 <skill>/scripts/vf.py status --profile <name>, or count by hand: a lesson is ready when its evidence has 3 or more unique rounds on 2 or more topics (or 2 rounds plus an analysis).
For each ready lesson, run python3 <skill>/scripts/vf.py promote-draft --profile <name> <lesson id>. It prints the complete rule block with the next free ID, the section it belongs in and the evidence. Fill any TODO field with your best draft.
Show the user the whole block: the instruction, strength, kind, scope, exceptions and check. Ask yes / no / reword. The reviewer will hold the user's text to exactly these words, so they must be right.
On yes: add the block to rules.md with vf.py rule add --profile <name> --section <number> --file <block> (it sets the section to established and refuses a broken block). Without a shell, add it under its section by hand and set the section to established. Set the lesson's status to promoted. Run vf.py validate --profile <name>; fix any error before saving. Then vf.py save -m "promote <lesson id>".
Profiles are independent, so a rule promoted in one profile stays there. If the same rule is promoted in 2 or more profiles, ask the user: "Is this true in all your writing, in every profile?" Only on a clear yes, propose one rule for base.md (ID B.., same fields) and remove the duplicates. On no or unsure, keep the rule in each profile.

Never promote anything without the user's yes on the exact words.

In a chat without file access

Run the same round. At step 3 and step 6, do not write files. Instead, at the end of the round, print one Markdown code block that holds the complete round file, and a second block with the new or changed lesson entries. Tell the user to paste them into the voice home, or to give them to an agent with file access.

End of session

Give a three line summary: rounds done, lessons added or updated, lessons ready to promote.