Reviewing the Meaning Changes Hidden in a Rewrite

Compare these two sentences:

Guests must not reshare documents within 24 hours unless an owner approves the action.

Guests may reshare documents within 48 hours.

The second is shorter. It also changes the obligation, removes a negation, changes a quantity, and drops an approval condition. A request to simplify a specification can produce a cleaner sentence while changing what an engineer would implement.

A normal diff contains those edits. The difficulty is giving them attention amid punctuation fixes, reordered paragraphs, and other harmless revisions. Meaning Diff adds a focused review pass over a small set of literal patterns.

Give the reviewer a reason to stop

The tool compares two Markdown documents, aligns sentences, and reports changed quantities, obligation words, negations, condition suffixes, and added or dropped sentences. It retains the before and after text with source line numbers.

For the example above, a reviewer should investigate several independent questions:

Change	Question for the reviewer
must becomes may	Was the policy intentionally relaxed?
not disappears	Did the permitted behavior reverse?
24 hours becomes 48 hours	Was the time window intentionally changed?
The unless condition disappears	Is owner approval still required anywhere?

The report does not answer those questions. It gives the reviewer located evidence for asking them.

Try it on the shipped specification

Use Python 3.11 or newer. There are no third-party runtime dependencies:

git clone https://github.com/asadani/meaning-diff.git
cd meaning-diff
out_dir="$(mktemp -d)"

python -m meaning_diff compare \
  fixtures/sharing-before.md fixtures/sharing-after.md \
  --format markdown --out "$out_dir/review.md"

python -m meaning_diff compare \
  fixtures/sharing-before.md fixtures/sharing-after.md \
  --format json --out "$out_dir/review.json"

Both comparison commands exit with status 1 because the fixture produces review signals. That exit status is an expected result, not an operational failure. Status 2 is reserved for problems such as invalid input or an unreadable file.

The fixture yields five changed sentence pairs and seven signals. It also includes a harmless paraphrase that appears as a changed pair without a configured signal. Exact unchanged sentences are omitted, and fenced code is excluded from prose comparison.

Sentence alignment is a design choice

Meaning Diff uses normalized exact matches as anchors. Within replacement blocks, it uses lexical similarity to pair remaining sentences. The alignment threshold is configurable; the default is 0.45.

That approach makes the implementation inspectable, but it also creates failure modes. A large paraphrase may not align with its predecessor. Similar wording can join unrelated sentences. Unmatched text remains visible as additions and drops, and the report retains the alignment method and scores so a reviewer can inspect suspicious pairs.

A signal's priority is a fixed hint about review order. It is not a measured probability of harm. A changed number can be an intentional correction; a seemingly harmless paraphrase can introduce a subtle policy error outside the detector's patterns.

Add a focused pass to the existing review

This is useful when a document contains obligations, limits, or conditional behavior: requirements, operational procedures, or internal policies. Keep the full diff and source documents available. Use the focused report to inspect changes that could alter an action or expectation.

For a practical evaluation, take a few realistic revisions and label the changes that a reviewer should notice. Compare ordinary diff review with diff plus the report. Record missed consequential edits and irrelevant flags, as well as the effort of reading the extra output.

The project has not established an accuracy rate on a labeled real-world corpus. Its current contribution is a small, reproducible way to surface specific patterns without asking another model to declare that the rewrite preserved meaning.

The MIT-licensed source includes the report schema, fixture revisions, and the comparison algorithm.

AI disclosure: This article was drafted with AI assistance using the project's source and fixtures. The examples are demonstrations, not a measured claim that the tool detects every consequential edit.