Consensus Tafsīr in Seven Days

Ninety steps, nine windows, and the exact prompt to paste into each of them on each day — building toward a commentary of the whole Qurʾān drawn from the agreement of twenty-one mufassirūn.

What is being built, and why it is defensible

The eventual goal is a commentary on the whole Qurʾān in which each word carries the meaning most of the tradition agrees on. You are not a scholar and will not be adjudicating between the mufassirūn. That is precisely why the method must be reportorial rather than judicial: the work records what the commentators said and where they converge, and it never decides who is right.

The unit of work: the consensus entry

One record per lemma-sense — not per instance. A window reads a stratified sample of a lemma’s occurrences, decides how many distinct senses that lemma carries, and writes one entry per sense, each anchored to a representative āyah. A lemma with one sense yields one entry; maqām, which carries two, yields two — the worked pair in REFERENCE-ENTRY.json.

{
  "id"        : "CE-014-0079",         stable, never reused
  "lemma_bw"  : "maqAm",
  "ayah"      : "17:79",
  "surah"     : "Al-Isra",  "place": "Makki",  "rev_order": 50,

  "consensus" : {
     "gloss_en"   : "a station of honour; rank",
     "gloss_ar"   : "<the Arabic the commentators actually used>",
     "editions"   : ["tabari","baghawi","razi","qurtubi","ibnkathir_ar"],
     "n_agree"    : 5,
     "n_glossing" : 7,               editions that addressed the word at all
     "share"      : 0.71,
     "earliest"   : {"ed":"tabari","died":923}
  },

  "minority"  : [                     never discarded
     {"gloss_en":"the place of intercession","editions":["jalalayn"],
      "n":1,"note":"reads it as the Praised Station of intercession"}
  ],

  "evidence"  : [                     one per edition, quoted verbatim
     {"ed":"tabari","died":923,"lang":"ar","quote":"...","supports":"consensus"}
  ],

  "flags"     : ["none"],             contested | thin | verse-only | ...
  "confidence": "clear",              clear | argued | disputed
  "annotator" : "window-3",
  "reviewed"  : false
}

The five rules that make an entry admissible

1. Every edition that glosses the word is recorded — supporting or not. An entry that lists only agreement is inadmissible.
2. Every quote is verbatim from the corpus, never paraphrased into the evidence field. Paraphrase goes in gloss_en and is marked as the annotator’s.
3. n_agree can never exceed n_glossing, and both are counted, never estimated.
4. Silence is not agreement. An edition that does not address the word is absent, not supporting. The flag thin fires below three glossing editions.
5. If no reading has more editions than any other, the entry is contested and carries no consensus — it goes to the disagreements paper instead.

Scope

The 850 split three ways: 840 into the nine shards, 5 held as calibration (every window reads all five on Day 1, so nine readers can be compared before any real work is kept), and 5 held out blind (read last, by a window that has not seen them, to measure the layer against itself).

15 to 16 lemmas per window per day. Occurrence counts run from 9 to 2,699 with a median of 20, so lemma size is wildly uneven — which is exactly why the shards were balanced on estimated minutes rather than on lemma count. A spread of 1.007 means no window finishes days ahead of another.

1. Confirm the scope lock: content lemmas with 9 or more occurrences. Write it into SCOPE.md and do not move it again.
2. Confirm the rule: plain count, no seniority bonus. Seniority is recorded on every entry but weighs nothing.
3. Confirm the claim boundary: report agreement, never adjudicate. This sentence goes at the head of every window prompt.
4. Run tafsir_signal.py extract 9 999 to widen the evidence cache from the 9–30 band to the whole lock. One pass, ~5 minutes.
5. Run make_shards.py 9 to cut 850 lemmas into nine shards, interleaved by frequency rank so every window gets the same mix of hard and easy.
6. Verify each shard file exists and that the nine shards together contain every target exactly once. A duplicated lemma is two annotators disagreeing silently.
7. Create 04-SENSE-LAYER/entries/window-1..9/. Each window writes only to its own directory, for the whole seven days.
8. Open the nine windows and paste the Day 1 prompt below into each, changing only the window number.

9. Every window annotates the same five calibration lemmas — not its own shard. This is the only shared work in the plan.
10. Waleed compares the nine outputs on those five lemmas. Disagreement here is cheap; on day 6 it is fatal.
11. Where windows disagree on a consensus gloss, the lemma is marked contested and the reason recorded.
12. Compute and record cross-window agreement on the calibration set. This figure goes in both papers and cannot be produced later.
13. Where the disagreement traces to the instructions rather than the evidence, amend the prompt and re-run day 1. Do not proceed on an ambiguous rule.
14. Freeze the prompt. From day 2 it does not change.
15. Each window annotates its first 5 shard lemmas to confirm the pipeline end to end.
16. Run the gate across all nine directories. Zero failures before day 2 begins.

Day 1 prompt — paste into every window, changing only the number

You are WINDOW 3 of 9 on the Qur'anic consensus-tafsir project.

WORKING DIRECTORY
  C:\Users\walee\Downloads\Quran Research\

YOUR OUTPUT DIRECTORY - write ONLY here
  04-SENSE-LAYER\entries\window-3\

Never write to another window's directory, to any shard file, or to
the toolkit. If you believe a tool is wrong, report it - do not edit it.

WHAT THIS PROJECT IS
  For each Qur'anic word at each verse, record THE MEANING MOST OF THE 21
  COMMENTATORS AGREE ON, with every dissenting reading kept.
  You are reporting what the mufassirun said. You are NOT deciding who is
  right. Never write "this word means X". Write "N of M editions gloss it
  as X; the others say Y".

TODAY IS CALIBRATION. Do these five lemmas, which every window is doing:
  maqAm, >um~ap, dyn, rwH, xalyfp

FOR EACH LEMMA
  1. python 01-TOOLKIT\brief.py <lemma>
     Read the whole brief. Every occurrence, the Arabic with the word
     marked, both public-domain translations, and what the commentators
     say around the word at that verse.
  2. python 01-TOOLKIT\tafsir_signal.py stats <lemma>
     Read the full evidence file it writes.
  3. For EACH occurrence, decide:
       - what each glossing edition says the word means THERE
       - which reading the most editions share  -> consensus
       - every other reading -> minority, quoted verbatim
       - if no reading leads, flag "contested" and give no consensus
  4. Write one JSON entry per occurrence to your directory, in the schema
     at 02-RESEARCH-PAPERS\paper-sense-layer\PLAN-90-v2.html
  5. python 01-TOOLKIT\audit_entries.py window-3

RULES THAT MAY NOT BE BENT
  - Quote verbatim. Never paraphrase into an evidence field.
  - Silence is not agreement. An edition that does not discuss the word is
    absent, not supporting.
  - n_agree may never exceed n_glossing.
  - Fewer than 3 glossing editions -> flag "thin".
  - If you are unsure, flag it. An honest flag is worth more than a
    confident guess, and Waleed reviews every flag.
  - Record how long each lemma took.

REPORT AT THE END OF THE SESSION
  - the five lemmas, with consensus gloss and n_agree/n_glossing for each
  - every flag raised
  - minutes per lemma
  - anything in the instructions that was ambiguous

17. Each window works only its own shard from here to day 6.
18. Order within a shard: highest frequency first. If time runs out it must run out on rare words.
19. Target 14 lemmas per window per day. Record the actual figure.
20. Every window runs the entry gate at the end of every session.
21. Waleed reviews only flagged entries, not all of them.
22. Any entry Waleed overturns is logged with the reason — this log becomes the reliability section of the paper.
23. No window may look at another window’s entries. Independence is what makes day 6’s re-check meaningful.
24. Commit at the end of every session, with the lemma count in the message.

Day 2–5 prompt — the daily working prompt

You are WINDOW 3 of 9, day [2|3|4|5], continuing the consensus-tafsir work.

Write ONLY to 04-SENSE-LAYER\entries\window-3\
Your shard: 04-SENSE-LAYER\shards\shard-3.json

START OF SESSION
  1. python 01-TOOLKIT\progress.py window-3
     - tells you what is done and what is next
  2. Take the next 14 lemmas, highest frequency first.

FOR EACH LEMMA - the loop you calibrated on day 1
  python 01-TOOLKIT\brief.py <lemma>
  python 01-TOOLKIT\tafsir_signal.py stats <lemma>
  read every occurrence
  write one entry per occurrence
  python 01-TOOLKIT\audit_entries.py window-3

REMEMBER
  - report agreement, never adjudicate
  - quote verbatim, never paraphrase into evidence
  - silence is not agreement
  - flag rather than guess; Waleed reviews every flag
  - if a lemma takes more than 40 minutes, flag it "hard" and move on

END OF SESSION
  python 01-TOOLKIT\audit_entries.py window-3 --summary
  git add -A && git commit -m "window 3 day N: X lemmas"
  Report: lemmas done, flags raised, minutes each, anything unclear.

25. Each window re-annotates 5 of its own earliest lemmas without looking at what it wrote on day 2.
26. Compare. Self-agreement is the honest measure of repeatability and belongs in the abstract of the dataset paper.
27. Every window annotates the same 5 held-out lemmas nobody has touched, for a second cross-window agreement figure.
28. Compute both figures. Publish them whatever they are. A resource with a stated agreement rate is usable; one without is not.
29. Where self-agreement is below 80% for a window, its entries are re-reviewed before release.
30. Finish or formally cut the remaining shard. Cut lemmas, never evidence.
31. Merge the nine directories. Any duplicate ID is a tooling bug, not a data decision.
32. Run the clean-room checker — recount every n_glossing straight from the corpus, importing nothing from the annotation tools.

Day 6 prompt

You are WINDOW 3 of 9, day 6: INDEPENDENCE CHECK.

PART A - re-annotate yourself
  Take the FIRST 5 lemmas you completed on day 2.
  Do NOT open your previous entries. Do not look them up.
  Annotate them again from the brief, exactly as before.
  Write to 04-SENSE-LAYER\entries\window-3\recheck\

PART B - the held-out five
  Every window today annotates the same five lemmas, untouched so far:
    [Waleed names them - held back from all shards]
  Write to 04-SENSE-LAYER\entries\window-3\heldout\

PART C - report honestly
  Where your day-6 answer differs from your day-2 answer, say so plainly.
  Do NOT quietly correct the old one. The disagreement is the measurement.

Then: python 01-TOOLKIT\audit_entries.py window-3 --recheck

33. Validate the merged dataset: every entry schema-valid, every n_agree <= n_glossing, every quote traceable to the corpus.
34. Verify every ayah reference resolves and every edition key exists.
35. Take a random sample of 40 entries and check each by hand against the tafsīr. Publish the sample error rate. Above 5%, stop and fix.
36. Produce the dataset in JSON and in tab-separated form.
37. Write README, SCHEMA, LIMITATIONS — the last carrying the flags, the contested entries and both agreement rates.
38. Licence: CC BY 4.0 on the annotation. Credit the Quranic Arabic Corpus, Tanzil and every tafsīr source prominently.
39. Deposit on Zenodo, mint a DOI, tag v1.0.0. Include the tooling — the dataset without the gates is not reproducible.
40. Draft Paper A: the consensus resource. Lead with the gap: no published Qurʾānic dataset carries sense. Report both agreement rates in the abstract.
41. Draft Paper B: the disagreements. Every contested entry, with the editions on each side. This paper exists only because minority readings were kept.
42. Re-run the literature search the morning you submit.
43. Submit A to LREC or the Journal of Open Humanities Data; B to the Journal of Digital Islamicate Research.
44. Write the v2.0 roadmap: the 5–8 occurrence band, the deferred lemmas, and the scholar review that must precede any claim to be a tafsīr rather than a dataset.

The dataset is the scholarly deliverable. Phase 2 is what turns it into something a Muslim with a phone can use, and it is now part of this plan rather than a wish-list beside it. Twenty-one items, in the order they should be built.

Tier 1 — unblocked, build first

Tier 2 — blocked on the sense layer

Tier 3 — the twelve that save someone a day

Tier 1 makes the reader better. Tier 3 is what makes someone forward it. Each of these replaces work a Muslim is doing by hand today.

Source verification — 2026-08-17

Steps 45–90: the checks that run underneath all seven days

These are not a phase. They are the standing obligations, and they are numbered so a window can be told “you skipped 61”.

45. No window writes outside its own directory. Ever.
46. No window edits a tool. Tool problems are reported, not fixed locally.
47. Entry IDs are allocated from the shard, never invented.
48. Every entry names its annotator window.
49. Every entry carries a timestamp.
50. Quotes are copied from the evidence file, never retyped.
51. Arabic is never typed by hand into any file.
52. Edition keys come from the corpus metadata, never from memory.
53. Death dates come from the corpus, never from memory.
54. An edition with no death date is recorded as unknown, not guessed.
55. miqbas is flagged on every entry it appears in — attribution disputed, and measured to share text with a 1973 work.
56. Identical quotes across editions are merged and the duplication recorded.
57. English and Urdu editions are recorded with their language.
58. Urdu evidence may support a consensus; it may not create one alone.
59. An entry resting only on translations, with no tafsīr, is flagged verse-only.
60. An entry with fewer than three glossing editions is flagged thin.
61. A consensus below 50% of glossing editions is flagged weak.
62. A tie is contested and carries no consensus.
63. Contested entries are never dropped; they are Paper B.
64. Minority readings are quoted at the same length as the consensus.
65. No entry may be edited after review without a logged reason.
66. Waleed’s overrides are logged, with the reason, always.
67. The override log is published with the dataset.
68. Progress is recorded daily per window, not estimated at the end.
69. Time per lemma is recorded, because the v2.0 plan depends on it.
70. Any window falling two days behind cuts lemmas, never evidence.
71. Any rule found ambiguous is fixed once, centrally, and all nine windows told the same day.
72. Any defect found in a tool goes into the defect register with its detector.
73. The defect register is published with the dataset.
74. The gate runs at every session end, not only at release.
75. A failing gate blocks the commit.
76. The clean-room recount shares no code with the annotation tools.
77. Disagreement between the recount and the dataset is a defect in the dataset.
78. Sample-checked entries are marked as sample-checked.
79. The sample error rate is published even if it is bad.
80. Both agreement rates are published even if they are bad.
81. No claim of completeness is made anywhere.
82. The scope statement names exactly what is covered and what is not.
83. Sources are credited on every page of every output.
84. Copyrighted translations are never quoted; only Pickthall and Yusuf Ali.
85. Tafsīr quotations are kept to the length the argument needs.
86. The digital-text caveat appears in both papers: these are digital editions and may carry transcription errors.
87. Anything carrying argumentative weight is marked for checking against a printed edition.
88. The list of passages needing printed-edition checking is published.
89. The scholar-review requirement is stated plainly in both papers.
90. Nothing is called a tafsīr until a scholar has reviewed it. Until then it is a dataset of what commentators said.
91. The v2.0 roadmap is published with v1.0, so the gaps invite collaborators rather than criticism.