Revision Methodology

This document describes how committed drafts are revised, who does the revising, and what changes qualify as a revision vs. a redraft. It complements METHODOLOGY.md which covers the initial AI-drafting pipeline.

Why there's a revision stage

Every committed draft gets a second read. The drafting pipeline (tools/draft.py) produces schema-valid YAML with full provenance, and most verses ship as drafted — but a second-model review pass gives every verse a second editorial eye before it's considered final. Committing that pass as its own layer keeps the drafter's provenance intact and makes every editorial change inspectable in git history. See What triggers a revision below for the specific criteria.

What triggers a revision

A verse is revised when a reviewer identifies one of these:

1. Real English-grammar awkwardness — stranded prepositions ("being testified to by"), literal-but-unnatural constructions ("in that by which you judge another"), double-noun stacks ("the one who justifies the one who"), or participial forms that don't parse cleanly in English ("becoming in the likeness of").
2. Rhetorical-force loss — when the Greek has a concessive, emphatic, or adversative force that a flat translation suppresses (Phil 2:6 ὑπάρχων → "though he was" rather than "existing").
3. Wordplay that the draft flattens — when the Greek pairs or echoes words the English could preserve more elegantly (Rom 3:26 δίκαιον/δικαιοῦντα → "just and the justifier").
4. Scholarly-preference shifts — when a defensible but unusual rendering deviates from mainstream consensus for no textual reason (Rom 1:17 "from faith for faith" → "from faith to faith").
5. Project-wide inconsistencies — when per-verse drafter decisions produce corpus-level drift (see the Χριστός normalization below).

What does NOT trigger a revision

• Stylistic preference. If the existing rendering is defensible and reads cleanly, it stays. The revision bar is "materially better," not "my preference."
• Theological re-interpretation. Revisions don't change the meaning the translator intended — they polish the expression of that meaning. If a rendering is theologically contested, that's handled via theological_decisions and footnotes, not revision.
• Lexicon-entry quibbles. The drafter's lexicon call stands unless it's plainly wrong. BDAG entry disputes go through public issues on the GitHub repo, not silent revision.

How a revision is committed

Each revision is a discrete git commit attributed to the revising model. The commit message states:

• Which verses changed
• The specific rendering(s) replaced
• Why the change (category from the list above)
• What was preserved as an alternative (in footnote or lexical_decisions.alternatives)

The original AI draft's ai_draft metadata (model_id, prompt_sha256, output_hash, timestamp) is preserved exactly — the drafter's provenance stands. The revision is visible only in git log, not in the verse YAML's top-level metadata. This keeps the chain of custody clean: GPT-5.4 drafted this verse on such-and-such date; Claude Opus polished it on such-and-such date; git shows both.

Global-scope normalizations

Some corrections apply across every verse at once, not per-verse. These are scripted and committed in a single pass.

Χριστός → Messiah (accepted 2026-04-18)

After reviewing ~20 verses and noticing per-verse drift, the project adopted a consistent rule for rendering the Greek title Χριστός:

Rationale. Χριστός literally means "anointed one" — it is the Greek translation of Hebrew מָשִׁיחַ. In modern English, "Christ" has drifted so far toward proper-name status that Paul's messianic claim is skipped by most readers. DOCTRINE.md's principle — translate titles rather than transliterate them — points toward consistent "Messiah." Per-verse judgment between "Christ" and "Messiah" produces corpus-level drift that can't be defended to a critic.

The one concession: standalone "Christ" in iconic English phrases (e.g., Phil 1:21 "to live is Christ") is currently left as-is. A follow-up pass may address these; for now, they're left for per-verse judgment.

Execution. A mechanical script (/tmp/normalize_messiah.py at time of writing; not committed) applied the compound-form rules to every drafted verse in a single pass (68 substitutions across 68 verses). Footnotes, lexical_decisions, and theological_decisions were left untouched so they continue to preserve "Christ" as the traditional alternative where the drafter documented it.

Χριστός → Messiah: liturgical carve-outs (accepted 2026-04-18)

After the mechanical pass, two classes of verse were reverted from "Jesus the Messiah" back to "Jesus Christ" because the phrases function as fixed liturgical forms in English-speaking Christian use, not as fresh theological claims where the titular force of Χριστός is in play:

1. Pauline benediction formulas — the closing "the grace of our Lord Jesus Christ [be with you]" appears as a fixed liturgical stamp at the end of most Pauline letters and is used verbatim in church benedictions. Reverted verses: Rom 16:20, Rom 16:24, 2 Cor 13:13, Gal 6:18, Phil 4:23, 1 Thess 5:28, 2 Thess 3:18, Philemon 25. Also 2 Cor 8:9 ("the grace of our Lord Jesus Christ, that though he was rich…"), which functions as a mid-letter fixed phrase rather than an argued titular claim.
2. The Phil 2:11 confession — "Jesus Christ is Lord" (κύριος Ἰησοῦς Χριστός) is the earliest recorded Christian creed and is recited verbatim in liturgy across traditions. Keeping "Messiah" here would sound like a scholarly gloss intruding on a confession.

All other occurrences of Ἰησοῦς Χριστός remain as "Jesus the Messiah" per the normalization rule. The carve-outs are narrow and named: benediction formulas and the Phil 2:11 confession. Any future carve-out must be documented here with rationale.

Execution. A second mechanical script (/tmp/renormalize_liturgical.py at time of writing; not committed) applied three phrase-level reverts across the 10 verses above. Footnotes and lexical_decisions.alternatives continue to preserve "Messiah" as the alternative rendering.

Repentance: contextual reassessment (2026-10-13)

The October 13 maintainer request reopens every October 11-12 terminology change. The new decision ledger covers exactly the same 397 English POB, Simplified POB and extra-canonical records. It restores recognizable repent-family language where appropriate, retains contextual exceptions, and repairs specific errors from the earlier application. This is neither a blind Git revert nor a runtime thesaurus filter.

The earlier plans and their pinned historical test fixtures remain evidence of what was done, not the active terminology rule. The controlling policy is DOCTRINE.md: Repentance terminology. The new plan records a decision, reason, input hash, source hash and exact output for every affected record. tools/repentance_reassessment.py preflights all inputs and rejects drift before writing. Existing source/generation layers and revision histories are preserved; new editorial choices remain drafts needing independent review.

Roles

Community suggestions and public credit

Readers can suggest a revision from the public Bible reader after signing in with a Cartha account. The suggestion is treated as an input to the same revision process as model findings: it is checked against the source text, compared with the existing rendering, and resolved by the best available combination of human judgment and AI-assisted source reasoning.

If a suggestion is approved, the public revisions: entry on that verse may include a credit block:

credit:
  source: community
  display_name: "Contributor Name"
  issue_url: "https://github.com/zackseyun/peoples-open-bible/issues/..."

That credit is intended to be durable. Once the approved revision is committed, the contributor's public credit travels with the verse's revision history and is surfaced by downstream public revision pages. Private account details should not be published unless the contributor explicitly chose that public credit string.

Public counters should keep this distinction clear: the complete revision index still reports every accepted applied edit from the machine-assisted and maintainer workflows, but the reader-facing "approved revisions" metric is narrower than the full applied-edit log. It counts explicit reader/contributor/maintainer approvals plus material source-grounded review findings that were accepted into the public text (mistranslation, lexical, missing-nuance, source-correction, theological-weight/clarity, doctrine-realignment, verse-boundary, truncation/regression, and stacked-review fixes). It intentionally does not count routine Tier-1 cleanup, grammar-only polish, or purely metadata-only alignment as "approved revisions."

What revisions are NOT

• A redraft. Revisions take the drafter's rendering as the starting point and make targeted improvements. They don't ignore the draft and produce an alternative.
• Silent. Every revision is a git commit with rationale. Critics can read the commit log to see exactly what changed and why.

Sentinels in adjudicator output (READ BEFORE APPLYING ANY REVISION)

Adjudicator agents (claude-opus-4-7-doctrine-aware, gemini-3.1-pro-preview, etc.) sometimes emit a finding whose to: field is not a literal replacement string but a command describing the structural edit they want applied. These look like ALL-CAPS imperatives (e.g. DELETE FOOTNOTE, REMOVE MARKER, DROP ENTRY).

Never write the sentinel string into a YAML field. A sentinel is an instruction to the human or agent applying the finding, not the new value. Writing it verbatim ships the literal word "DELETE" to the CDN, where readers see it in their Bible app. (This actually happened on Jubilees 26:25 in the 2026-04-28 doctrine-aware pass — the heal is documented in translation/extra_canonical/jubilees/026/025.yaml.)

When to: is a sentinel, do the structural edit, not a string replacement:

If you encounter an unfamiliar ALL-CAPS imperative in to:, treat it as a sentinel and stop. Don't guess the structural edit — escalate to the human maintainer. A literal sentinel that has already leaked into a YAML field is a regression, not a translation choice; heal it by restoring the pre-sentinel state and re-evaluating the original finding from scratch.

Self-check before applying a revision pass:

git grep -nE '^\s+text:\s+(DELETE|REMOVE|DROP|TODO|FIXME)\b' translation/

Should return zero hits. If it returns anything, a sentinel has been written to a real field — fix it before the next CDN publish.