Schema & profile design

A profile is a readable specification for one voice in one context. Its rules.md is the source that both writer and reviewer use. Evidence stays in rounds, analyses and lessons, cited by ID.

The ten nonfiction sections

Section	What belongs here	What code can help with
1. Identity and context	Purpose, readers, register, field, genres, venues, conventions and scope	Required brief fields
2. Document architecture	Openings, closings, moves, sections and organizational formatting	Human judgment
3. Argumentation and reasoning	Claims, warrants, support, objections and qualifications	Human judgment
4. Paragraphs	Claim placement, support, endings and variation	Paragraph words and sentences
5. Discourse and coherence	Relations between ideas and thematic progression	Connector counts as hints
6. Sentences and rhythm	Length, variation, constructions and complexity	Sentence length and spread
7. Vocabulary and register	Word choice, terms, repetition and audience fit	Lexical diversity (MATTR)
8. Voice and metadiscourse	Stance, tone, self mention and reader engagement	Marker counts as hints
9. Evidence and sources	Numbers, citation, quotations and uncertainty	Human judgment
10. Anti-patterns and constraints	Rejected wording, punctuation, formatting and rhetorical habits	Several automatic checks

The schema draws on genre and move analysis, argumentation, discourse relations, thematic progression, corpus methods and metadiscourse. It is Voice Forge's synthesis, not a single established research standard. The complete schema includes its sources and explanations.

Section status

Sections 2 to 10 start with a status:

unknown: no rules yet. This is normal, and structurally valid.
established: at least one approved rule.
not_applicable: the section does not fit this profile, with a required Reason: line.

A lack of evidence is unknown, not not applicable. Section 1 has the brief rather than a status or rules. Exact headings and order matter to validation. Complete file layout.

The rule contract

This is a synthetic stated rule. It describes one observable action, with a deliberate scope and exception.

- R01 Give an everyday example before a new technical term.
  - strength: preferred
  - kind: preference
  - applies: public explanations introducing a technical term
  - except: glossary entries and quoted text
  - check: PASS if an everyday example precedes the first use of the new term.
  - transfer: any
  - evidence: stated 2026-10-21
  - status: approved 2026-10-21

Do not copy its approval date into your profile as evidence that you approved it. Your agent should show your own proposed block and save it only after your yes.

Field	Values or purpose
Instruction	One checkable action after an ID
`strength`	`mandatory`, `prohibited`, `preferred`, `optional`
`kind`	`constraint`, `tendency`, `preference`
`applies`	Where and when it applies
`except`	Exclusions, or `none`
`check`	Observable pass condition for the reviewer
`evidence`	Round IDs, analysis IDs, a stated or adopted date, or transfer evidence
`status`	`approved YYYY-MM-DD`
`auto`	Optional mechanical check
`from`	Optional source lesson ID
`transfer`	Optional `any`, `adapt`, `en-only` or `es-only`

R IDs are profile rules. N IDs are prohibited rules. B IDs belong to base rules. IDs are not reused after retirement. A measured average should become a tendency, rather than a hard cap on every sentence.

Mechanical checks and support

Automatic checks include phrase and paragraph opening bans, regular expression bans, punctuation, quote style, length limits, mean sentence ranges and the share of long sentences. Read every supported check and its syntax.

Code cannot decide scope, exceptions or rhetorical function. A flagged passage may be a lead for the reviewer. Measures such as sentence length and MATTR describe surface habits; they do not measure whether you recognize your voice.

Support is generated from evidence, not typed as an extra field: trained, stated, adopted, thin, transferred or confirmed. Exact support thresholds.

State a rule directly

/vf-rules explainer-en add give an everyday example before a new technical term

The agent checks for overlap, proposes the complete block and asks for yes, no or reword. A direct rule uses stated evidence. A requirement for this one task should stay a task instruction unless you deliberately approve it as a lasting preference.

/vf-rules explainer-en edit R01 apply this only to first introductions of a term
/vf-rules explainer-en drop R01 I no longer want to require this

Inspect your real IDs before editing. The complete rules method explains adding, replacing, dropping and retiring.

Shared rules and precedence

base.md holds the few rules true across your profiles. transfer: es-only can make a shared quotation rule apply only in Spanish. Base uses the same rule contract, selected section headings and no section status lines.

Conflicts follow this order: your task instructions, meaning, language rules, profile rules and brief, base rules, then generic slop rules. Within a profile, mandatory and prohibited outrank preferred, which outranks optional.

Profiles remain independent. Deriving creates a copy for another language; later source changes require a separate update and approval. Derivation workflow.

Fiction profiles

Fiction is supported as type: fiction, with a free layout. There is no fixed fiction schema yet. The validator checks rule fields, rather than enforcing the ten nonfiction sections or evaluating narrative craft.

Ask vf-new for a fiction profile explicitly. From the terminal, with your voice home already set up:

cd ~/voice-forge
python3 skills/voice-forge/scripts/vf.py init --profile stories-en --type fiction --purpose "Short fiction" --audience "Adult readers" --register "Literary"
python3 skills/voice-forge/scripts/vf.py validate --profile stories-en

The generated fiction template has ## Brief, ## Rules and ## Notes. It does not write a nonfiction register field merely because that option was supplied; describe the desired register in your brief. Keep scene, narrator and dialogue preferences concrete and approve their rule fields. Do not treat validation as proof that plot, characterization or narrator fidelity was tested.

type: unclassified is available in migration for profiles whose scope is undecided. It also receives rule-field validation without a defined schema. New profile creation supports nonfiction and fiction.

Validate, export and migrate

From the app checkout:

python3 skills/voice-forge/scripts/vf.py validate --profile explainer-en
python3 skills/voice-forge/scripts/vf.py export --profile explainer-en

Validation errors include missing fields, wrong headings, duplicate IDs, TODOs and unapproved adaptation markers. Empty brief fields produce warnings. Export prints JSON generated from rules.md; do not keep an edited JSON copy as another source of truth.

Profiles created before version 2.7 can be migrated:

/vf-migrate explainer-en
/vf-migrate base

Migration writes a proposal in rules.migrated.md, preserving the original. Approve missing fields, validate the proposal, then deliberately replace the original through the skill workflow. Complete migration method.