Natural Writing

An evidence-driven agent skill for making prose less mechanical and more consistent with a user's own writing preferences.

This project does not optimize text to evade AI detectors. It focuses on writing quality: semantic density, clear mechanisms, restrained qualification, content-driven rhythm, and cautious learning from real user feedback.

简体中文

What it does

• Edits English or Chinese prose without changing facts or argument strength.
• Learns from annotations, before/after edits, approvals, and rejections.
• Separates Strong, Likely, Hypothesis, and Local preferences.
• Records contradictions and exceptions instead of silently overwriting rules.
• Runs regression examples so new preferences do not damage previously acceptable writing.
• Keeps every preference linked to anonymized evidence.
• Maintains persistent rules and counterexamples for individual papers.
• Uses separated Analyst, Skeptic, Editor, and Verifier roles for consequential edits.
• Provides dependency-free regex checks for fast mechanical screening.
• Unlocks independent editing and drafting only after evidence and regression gates pass.

Current model status

The current preference model is v0.3, based on 33 annotations across two independently annotated academic English documents.

• Strong personal preferences: 3
• Likely preferences: 1
• Explicit positive examples: 0
• Current autonomy level: Assisted

The second document's source manuscript is not public; its evidence is published only as anonymized, mechanism-level style descriptions and contains no source text.

Repository structure

File	Purpose
SKILL.md	Executable agent instructions
human_writing_model.md	Current interpretation of the user's writing preferences
annotation_analysis.md	Anonymized evidence table and inference process
writing_preferences.json	Structured preference state
regression_examples.md	Should-edit, should-preserve, and context-dependent cases
references/project-workflow.md	Project profiles, rule precedence, roles, artifacts, and stopping conditions
references/autonomy.md	Evidence gates for independent editing and drafting
scripts/project_profile.py	Persistent project-profile management
scripts/mechanical_check.py	Mechanical facts, candidates, and approved replacements
scripts/autonomy_check.py	Machine-readable autonomy gate evaluation
scripts/run_artifact_check.py	Role, regression, patch, output, and draft artifact validation
assets/project_profile.schema.json	Project-profile schema
assets/writing_preferences.schema.json	Global preference-store schema
assets/regression_manifest.json	Required regression cases by context
tests/test_tools.py	Dependency-free tool tests
CHANGELOG.md	Preference-model evolution
VERSION	Current model version
evals/evals.json	Behavioral evaluation prompts

Installation

GitHub Copilot CLI

git clone https://github.com/Yuki-zik/natural-writing.git \
  ~/.copilot/skills/natural-writing

Claude Code or another skill-compatible agent

Clone the repository into that client's user skill directory. For clients that use ~/.claude/skills:

git clone https://github.com/Yuki-zik/natural-writing.git \
  ~/.claude/skills/natural-writing

Restart or reload the client after installation.

Paper-specific rules

Create a profile inside a paper project:

python3 scripts/project_profile.py init \
  --project-root /path/to/paper \
  --project-id my-paper \
  --language en \
  --genre academic \
  --mode deliberated

The profile persists:

• project-specific style rules;
• protected claims and terminology;
• approved positive examples;
• counterexamples and rejected rewrites;
• approved mechanical replacements;
• execution and autonomy modes.

Project rules do not silently enter the global user model.

Record explicit autonomy authorization separately from the mode:

python3 scripts/project_profile.py authorize \
  /path/to/paper/.natural-writing/project_rules.json \
  --capability edit \
  --decision allow \
  --reason "Approved after reviewing maturity metrics"

Mechanical preflight

python3 scripts/mechanical_check.py \
  --profile /path/to/paper/.natural-writing/project_rules.json \
  --format json \
  manuscript.md

Built-in patterns locate possible meta-introductions, defensive non-claims, formulaic closers, and repeated obligation frames. They report candidates rather than deciding that the prose is wrong.

--fix-approved applies only built-in safe replacements or exact project rules marked approved: true.

Deliberated editing

Meaning-sensitive and whole-document edits use:

Analyst -> Skeptic/Adjudicator -> Editor -> Verifier

• The Analyst proposes evidence-linked candidates.
• The Skeptic searches for counterexamples and rules on value and meaning risk.
• The Editor applies only released changes.
• The Verifier checks meaning, protected content, regressions, and unapproved edits.

Independent editing and drafting

Natural Writing can eventually revise text or draft from a supplied content packet without item-by-item approval. Autonomy is disabled until the model has:

• evidence from multiple independently authored or edited documents;
• enough Strong preferences across different categories;
• user-approved positive examples;
• user-approved counterexamples and rejected transformations;
• clean regression results;
• successful user-reviewed editing history;
• explicit project authorization.

Independent drafting learns how the user writes. Claims, evidence, citations, scope, and intended meaning must still come from the user-provided content packet.

Check the numeric and authorization gates with:

python3 scripts/autonomy_check.py \
  --preferences writing_preferences.json \
  --profile /path/to/paper/.natural-writing/project_rules.json \
  --run-dir /path/to/paper/.natural-writing/runs/<run-id> \
  --capability edit \
  --require

Typical prompts

Use the natural-writing skill to revise this academic paragraph.
Preserve every scientific claim and show which AI-like mechanisms you removed.

Here are three new annotations and one before/after edit.
Update the writing preference model without overgeneralizing them.

Check this draft for repeated obligation templates, defensive non-claims,
and redundant paragraph closers. Do not use an AI-word blacklist.

Use the paper's .natural-writing/project_rules.json.
Run the mechanical preflight, deliberate the candidates with independent roles,
and return the verified patch plus any needs-user decisions.

Evidence discipline

The model evolves slowly:

1. Record new evidence before changing rules.
2. Match it to support, contradiction, exception, hypothesis, or local decision.
3. Update confidence in either direction.
4. Keep conflicting evidence visible.
5. Add user-approved examples when available.
6. Add rejected rewrites and should-preserve cases as counterexamples.
7. Run the regression set.
8. Keep project rules separate from global preferences.
9. Update the version and changelog only for material changes.

A preference reaches Strong only after at least three independent observations across at least two independently authored or edited documents.

Design principles

1. Make every sentence earn its place.
2. State the mechanism or judgment instead of naming an abstraction around it.
3. Keep qualification only when it changes interpretation.
4. Vary rhetorical structure when nearby passages perform similar work.
5. Keep concepts and paragraph-level links locally intelligible.
6. Learn both what to change and what must remain unchanged.

Privacy

The public evidence uses anonymous IDs (A001–A033) and contains no local file paths, raw annotation identifiers, or text from the unpublished second document.

When adapting the skill to your own writing, review evidence files before publishing them. Writing annotations can reveal personal preferences or unpublished text.

License

MIT