The Sense Layer in Thirteen Days

Ninety steps to a releasable v1.0 — the annotation layer that no published Qurʾānic dataset supplies.

The scope, measured

1. Write a one-page definition of "sense" for this project and commit it. Proposal: a distinct dictionary meaning of one lemma, such that a competent translator would render it with a different English word.
2. Write the exclusion rule: grammatical function, syntactic role and metaphorical extension are not separate senses. Only lexical meaning is.
3. Decide the evidence standard: every sense must be supported by at least one of — divergence between Pickthall and Yusuf Ali; explicit discussion in a tafsīr; a distinct grammatical construction.
4. Freeze the target set: content lemmas (N or V, with a root) having 20 or more occurrences. Write the selection query into the repository so it is reproducible.
5. Generate targets.json — the 440 lemmas with counts, root, POS, forms and āyah list.
6. Assign each lemma a stable sense-layer ID (SL-0001 …). IDs never change, even if a lemma is later dropped.
7. Create the repository: 04-SENSE-LAYER/ with shards/, build/, docs/.
8. Write SCOPE.md stating what v1.0 covers and, explicitly, what it does not. This becomes a section of the paper.

9. Define the record schema. One JSON object per lemma. Fields: id, lemma, root, pos, total, status, senses[], annotator, date.
10. Define the sense object: name, gloss, basis, confidence, and either forms[] or refs[].
11. Allow two assignment modes: by form (fast, when spelling separates the senses) and by reference (slow, when it does not). Record which was used.
12. Write sense_schema.py validating every field and type.
13. Write the exhaustiveness gate: the declared senses must account for every occurrence of the lemma. No occurrence unassigned, no form claimed twice.
14. Make the gate refuse to load on failure rather than warn. This is the mechanism that stops a count being quietly reduced.
15. Write make_shards.py: split the 440 targets into four shards by frequency rank (rank 1,5,9… to shard A; 2,6,10… to B) so each shard has a comparable mix of hard and easy.
16. Each shard writes to its own file only: shards/shard-A.json … shard-D.json. No window ever writes another window's file.parallel-safe
17. Write brief.py <lemma-id>: prints everything needed to judge one lemma — every occurrence with āyah reference, the Arabic, both public-domain translations, and the surface form.
18. Extend brief.py to flag translation divergence: mark occurrences where Pickthall and Yusuf Ali choose different English head words. This is the strongest cheap signal for polysemy.
19. Add tafsīr retrieval to brief.py: pull the commentary on the āyah from the 21 editions, so a disputed occurrence can be checked against the tradition.
20. Write record.py: appends a completed lemma record to the correct shard, validating the schema and running the gate before writing.
21. Write progress.py: prints how many of the 440 are done, by shard, with a projected completion date.
22. Write merge.py: combines four shards into one dataset, failing loudly on any duplicate ID.
23. Test the whole chain end-to-end on three lemmas you already know — barr, ākhir, rajul — whose senses are already declared. The tool must reproduce them exactly.
24. Commit the tooling. Do not change the schema after this point without re-validating every completed record.

The purpose of triage is to separate the 440 into those needing real work and those that do not. Two to three minutes per lemma. Do not annotate here — only decide.

25. Open one window per shard. Give each the shard brief from the appendix below.parallel
26. For each lemma, run brief.py and read the divergence flags first.
27. Mark status: "single" when both translators consistently use one English head word and no tafsīr dispute is visible.
28. Mark status: "split" when translators diverge systematically, or the lemma clearly names two things.
29. Mark status: "defer" for anything you cannot decide in three minutes. Deferring is not failure — it is the honest signal that the lemma needs a scholar.
30. For every single, write the single sense and its gloss immediately. It is a complete record and needs no revisit.
31. Never mark a lemma single just to move faster. The exhaustiveness gate cannot catch a wrong judgement, only a missing one.
32. Log the triage decision time per lemma. You will need the rate to project completion honestly.
33. At the end of each session run progress.py and record the number in a running log.
34. After the first 40 lemmas, stop and compare the four windows' decisions on a shared sample of five lemmas.sync
35. Where windows disagree on the same lemma, that lemma is defer by definition. Record the disagreement — it is data about annotation difficulty and belongs in the paper.
36. Adjust the written definition from step 1 if the disagreements reveal ambiguity in it, then re-triage everything done so far under the revised definition.
37. Complete triage of all 440.
38. Publish the triage counts: how many single, split, defer. This is your first real finding.

Expect roughly 110 lemmas here. Twenty to thirty minutes each. This is the work.

39. Sort the split list by frequency, highest first. If time runs out, it must run out on the rare words, not the common ones.
40. For each lemma, read every occurrence before naming any sense. Naming senses early biases every assignment after it.
41. Name each sense with a short English gloss and a one-line basis stating why it is distinct.
42. Prefer assignment by form where spelling separates the senses — it is faster and independently checkable.
43. Use assignment by reference where it does not. List every āyah explicitly.
44. Set confidence per sense: clear, argued, or disputed.
45. Any occurrence you are unsure of goes into a sense named unresolved. The gate must still pass — unresolved is an assignment, not a gap.
46. Where a tafsīr explicitly discusses the ambiguity, cite it in basis. That single line raises the record from opinion to evidence.
47. Where the two translators diverge, quote both renderings in basis. It is the cheapest defensible evidence you have.
48. Never let a sense have zero occurrences. The gate rejects it, and it means the sense was imagined rather than found.
49. Run record.py after every lemma. Do not batch — a crash must never cost more than one lemma.
50. Commit after every session, with the count in the commit message.
51. Every 20 lemmas, re-run the full gate over your whole shard.
52. Every 20 lemmas, re-annotate one lemma you did earlier without looking at your previous answer.self-check
53. Compare the two versions. Disagreement with yourself is the honest measure of how repeatable the annotation is, and it belongs in the paper.
54. Log every self-disagreement. Do not quietly fix them.
55. At day 7, run progress.py and project the finish date. If it falls past day 9, cut scope, not care — drop the lowest- frequency splits and say so in SCOPE.md.
56. Never solve a schedule problem by lowering the evidence standard.
57. Windows must not discuss individual lemmas mid-phase. Independence is what makes the day-10 agreement check meaningful.discipline
58. Keep a QUESTIONS.md of anything needing a scholar. It is a deliverable, not an embarrassment.
59. Finish the top 60 splits by day 7 whatever else slips.
60. Finish all splits, or formally cut the remainder, by end of day 9.
61. Freeze annotation. No further edits except to fix validation failures.
62. Merge the four shards. Resolve any duplicate ID as a tooling bug, not a data decision.

63. Run the exhaustiveness gate over the merged dataset. Every occurrence of every annotated lemma must be assigned.
64. Assert the arithmetic: for each lemma, the sum of sense counts equals the corpus count. Any mismatch is fatal.
65. Verify every āyah reference resolves to a real verse.
66. Verify every declared form actually occurs for that lemma.
67. Check for senses that differ only in wording — the same distinction named twice across different lemmas. Harmonise the vocabulary.
68. Check no lemma has more than five senses without an explicit note. More than five usually means the definition is being stretched.
69. Compute and publish self-agreement from the step-52 re-annotations: the proportion where you reproduced your own assignment.
70. Compute the cross-window agreement from the step-34 sample.
71. Report both figures whatever they are. A resource with a stated agreement rate is usable; one without is not.
72. Write a clean-room checker that recomputes the counts from the raw morphology, importing nothing from the annotation tooling.
73. Run it. Any disagreement is a defect in the layer, not in the checker.
74. Take a random sample of 30 assignments and check each by hand against the āyah.
75. Publish the sample error rate. If it exceeds 5%, stop and fix before release.
76. Add every check above to a single audit_sense.py that must pass before any release.

77. Produce the dataset in two formats: JSON for machines, and a tab-separated file for people who will open it in a spreadsheet.
78. Write README.md: what it is, what it covers, what it does not, how to validate it, how to cite it.
79. Write SCHEMA.md documenting every field, with an example record.
80. Write LIMITATIONS.md. Include the deferred lemmas, the disputed senses, and the agreement rates.
81. State the licence. CC BY 4.0 for the annotation; note that the underlying morphology is the Quranic Arabic Corpus under its own licence.
82. Credit the Quranic Arabic Corpus and Tanzil explicitly and prominently. You are adding a layer to their work, not replacing it.
83. Deposit to Zenodo and mint a DOI. Tag it v1.0.0.
84. Publish the annotation tooling in the same deposit. The layer without the gate is not reproducible.

85. Draft the data descriptor, about 3,000 words: motivation, method, scope, format, validation, limitations, reuse.
86. Lead with the gap, stated exactly: published Qurʾānic datasets supply morphology, syntax and topic. None supplies sense.
87. Report the agreement rates and the sample error rate in the abstract. A resource paper that hides them will be asked for them.
88. Re-run the literature search the morning you submit. Confirm no sense-annotated Qurʾānic resource appeared while you worked.
89. Submit to LREC or the Journal of Open Humanities Data, with the DOI already live.
90. Add the deferred lemmas and the open questions to the paper as the stated roadmap for v2.0. The gaps are what invite collaborators.

Running four windows without collisions

Copy this brief into each window

You are working on shard [A|B|C|D] of the Qur'anic sense layer.

WORKING DIRECTORY
  C:\Users\walee\Downloads\Quran Research\04-SENSE-LAYER\

YOUR FILE - write ONLY this one
  shards/shard-[A|B|C|D].json

DO NOT touch any other shard file, or targets.json, or the tooling.

TASK
  For each lemma in your shard:
    1. python brief.py <id>      - read every occurrence
    2. decide: single / split / defer
    3. python record.py <id>     - writes to YOUR shard only

RULES
  - A sense needs evidence: translator divergence, a tafsir discussion,
    or a distinct construction. Record which.
  - Every occurrence must be assigned. "unresolved" is a valid
    assignment; leaving a gap is not.
  - If undecidable in three minutes, mark defer. Do not guess.
  - Never mark "single" to go faster.
  - Commit after every lemma.

REPORT AT SESSION END
  python progress.py   and paste the output

Day by day