About
The Quran Logic Engine
A first-principles methodological apparatus for engaging the Quran as a system of formally classifiable statements.
Methodological Apparatus

The Quran as a
Logic-Gated Rule System

A first-principles framework for treating revealed statements as formally classifiable propositions. 54 rules across 7 statement types, with explicit limits on what the apparatus can and cannot do.

54Rules
7Statement Types
20Gate Forms
20Particles
9Tensions
6Mechanisms

This is a methodological apparatus for engaging the Quran as a system of formally-classifiable statements — gates that govern moral, civilizational, eschatological, and ontological reality. The Quran itself supplies the warrant: it explicitly declares its established patterns invariant سنة الله [Q 33:62, 35:43, 48:23].

The work consolidates seven phases into a single navigable tool: methodological foundation, gate-form taxonomy, sunan map, rule-engine seed, consistency-checking, integrated reference, and limits.

Key principle: the text is primary; the apparatus is a tool for engaging it more rigorously, not a system that replaces or extends it. See the Limits section before treating any output as authoritative.

§Choose Your Entry Path

Path A · Newcomer-Friendly Plain-English Tour If you don't have classical Islamic studies background or formal logic training. A guided walkthrough that explains each key concept in plain language, with all technical terms glossed. Start the tour → Path B · Direct Methodological Foundation If you have background in logic, philosophy, or Islamic studies. Goes straight to the four logical layers, statement-type taxonomy, and gate-form catalog. Open apparatus →

§The Three Tiers

§Recommended Reading Order (Specialist)

If you have classical or logical background. For newcomers, start with the Plain-English Tour instead.

  1. Apparatus → Logic & Notation~5 min
    The four logical layers and the ⟨MA⟩ meta-condition.
  2. Apparatus → Statement Types~8 min
    The seven kinds of Quranic statement and their inference behaviour.
  3. Apparatus → Gate Forms~10 min
    The 20 formal gate-shapes organised in 6 families.
  4. Apparatus → Particles~10 min
    Twenty Arabic logical particles with inference behaviour and worked examples.
  5. Rules → filter to M warrant~10 min
    All six explicitly-tagged sunnat Allāh rules — the strongest invariance warrant in the corpus.
  6. Analysis → Tensions~22 min
    Nine worked cases showing how apparent contradictions resolve.
  7. Analysis → Composition~5 min
    How multiple gates combine when simultaneously active for one agent.
  8. Practice → Reading a Verse~10 min
    Step-by-step workflow with worked examples — putting the apparatus to work.
  9. Limits~10 min
    Required reading before treating any output as authoritative.
Reference
Apparatus
Logical machinery: the four layers (predicate / deontic / alethic / epistemic), the ⟨MA⟩ meta-condition, and notation conventions.
In plain terms

Most of what the Quran says isn't simple statements like "the sky is blue." It says things like "whoever does X, then Y" or "every soul will Y" or "do not do X." Each of these has different logical force — a command isn't a prediction, a universal-quantifier isn't a particular instance, a counterfactual isn't a forecast. To engage Quranic statements rigorously, we need vocabulary that distinguishes these. That's what this section sets up.

1.1Why propositional logic alone fails

Propositional logic operates on whole statements (P, Q, R) joined by connectives (∧ ∨ ¬ → ↔). Quranic gate-statements almost always quantify over agents or objects — whoever, every soul, those who believe — which propositional logic cannot represent. We need at least four layers, each handling a distinct dimension of what the text does.

1.2The four required layers

Predicate (first-order) logic

Adds quantifiers ( universal, existential) and predicates with arguments. Required for nearly every gate-statement.

Example · [Q 99:7]
فَمَن يَعْمَلْ مِثْقَالَ ذَرَّةٍ خَيْرًا يَرَهُ
∀x . DOES(x, atom_weight_good) → SEES(x, it)

Deontic logic

Distinguishes prescriptive force from descriptive truth. Operators: O(p) obligatory (wājib — what must be done), F(p) forbidden (ḥarām — what must not be done), P(p) permitted (mubāḥ / ḥalāl — what is allowed). A juristic statement of obligation is not a prediction that the action will occur. Conflating them is one of the most common failure modes in popular religious reasoning ("if Allah commanded X, X will happen") — we keep them separate at the gate level.

Alethic modal logic

Necessity () and possibility ().

Necessity · [Q 21:35]
كُلُّ نَفْسٍ ذَائِقَةُ الْمَوْتِ
∀x . □ TASTES_DEATH(x)
Possibility · [Q 5:52]
فَعَسَى اللَّهُ أَن يَأْتِيَ بِالْفَتْحِ
◇ BRINGS(Allah, victory)

Epistemic modal logic

Knowledge attributions. Frequent والله يعلم / والله بكل شيء عليم statements are epistemic, not deontic or alethic, and need their own operator K_Allah(p) to avoid being mistakenly chained into causal arguments — Allah's knowing P does not entail P being a gate-output of any human or natural process.

1.3The meta-condition: mashīʾat Allāh

[Q 18:23–24] explicitly forbids saying "I will do X tomorrow" without coupling it to إن شاء الله (if Allah wills). This functions as an overriding modal operator above all gates — but its placement is critical, and three cases must be distinguished. Carelessly attaching it to every gate flattens the distinction and produces incorrect formalisations.

Statement typeIs ⟨MA⟩ implicit?Why
About Allah's actionNoAllah's will is the will in question; conditioning on itself is incoherent.
About created outcomesYesOutcomes occur within the created order, which operates under Allah's will.
Legislative (O / F / P)No (rule) / Yes (compliance)Obligation is fixed; agent's capacity to fulfill is contingent — see [Q 2:286].

1.4Notation conventions

SymbolMeaning
∀x, ∃xuniversal / existential quantifier ("for every x" / "there exists an x")
∧, ∨, ¬and, or, not
→, ↔conditional (if-then), biconditional (if-and-only-if)
O(p), F(p), P(p)obligatory, forbidden, permitted
□, ◇necessary, possible
K_a(p)agent a knows that p
⟨MA⟩meta-condition: under mashīʾat Allāh (Allah's will)
PREDICATE(x)predicates in capitals, arguments lowercase
[Q s:a]Quranic citation: surah:ayah

1.5Calibrating warrant beyond text-counting

The warrant scale (A / M / W / R+ / R / S) calibrates by textual signal: explicit sunna-tagging, explicit promise marker, multi-locus structural consistency, single-locus presence. This is necessary but not sufficient. Two further methodological calibrations operate alongside.

i. School-divergence as transmission-weakness signal

When schools (across Sunnī, Shīʿī, Ibāḍī, Muʿtazilī, Ẓāhirī, etc.) persistently disagree on the application of a textual rule — not merely on derivative cases or contemporary novel applications, but on the rule's original application — this disagreement is itself evidence that the underlying transmission of the rule's application is structurally weaker than classical presentation suggests.

Why this works

If the prophetic transmission of an application were robust, schools would converge on it even where they differ on derivative analogies. Persistent cross-school divergence on the application itself signals one of: (a) the underlying transmission has hidden defects (chains, matn-issues); (b) the rule's textual scope is genuinely underdetermined and schools are doing distinct ijtihādic closures; (c) historical-contextual factors shifted application conditions across regions and the original was lost or never universal. In any of these cases, the appropriate response is to weaken the warrant for treating the contested application as established, not to harmonise around any single school's position.

When to apply

To contested applications of a textual rule — e.g., the universal-hawl-default for zakāh across asset types, specific timing of ṣalāh combination, witness-structure across non-debt contexts, exact scope of certain food prohibitions, the form of certain ritual elements. The calibration weakens warrant for the contested application without weakening warrant for the foundational rule.

When NOT to apply

Where school-divergence reflects different scope-judgments rather than different transmission of a single original fact. Some divergence is genuine ijtihādic difference about how a textually-clear principle applies to novel situations — that is healthy methodological diversity, not transmission weakness. The signal applies when divergence is on the original-rule application, not on its extension.

ii. Cross-traditional convergence as warrant-strengthener

Symmetrical counterpart of (i). Where Sunnī, Shīʿī, Ibāḍī, Muʿtazilī, and Ẓāhirī traditions converge on the application of a textual rule despite disagreeing on much else, the convergence strengthens warrant. Cross-traditional agreement filters out tradition-specific transmission contamination.

iii. Matn-criticism preserved as a separate move

The apparatus is Quran-primary by design. Where transmitted material is invoked at all, matn-level critique (universal quantifiers, absence of sabab al-wurūd, internal corpus tensions) operates independently of isnād-grading. Even chains assessed as clean at the isnād-level can fail at the matn-level. The apparatus does not adopt grading as authoritative without engaging the matn.

Honest scope of these calibrations

These calibrations are diagnostic tools, not closure mechanisms. They sharpen confidence levels; they do not produce final positions on contested applications. Where a contested application has weakened warrant after calibration, the appropriate stance is acknowledgment of underdetermination, not confident assertion of an alternative. The apparatus can show where transmission is structurally weaker than presentation suggests; it cannot adjudicate what the original application was.

Slices
Statement Types
The 7 kinds of Quranic statement and their inference behaviour. Each rule belongs to one or more types.
In plain terms

The Quran says different kinds of things, and each kind behaves differently when you reason about it. A command isn't a prediction. A description of how Allah is, isn't a rule for humans to follow. A historical narrative isn't automatically a universal pattern. Mixing these up is where most bad reasoning starts. Below: seven categories.

The same surface gate-shape (IF P THEN Q) means different things across categories — predictive in one, obligatory in another, guaranteed in a third. Conflating them produces bad inferences. Click a card to expand.

§Summary

#TypeOperator familyDefeasibility
iOntologicalAssertionNot defeasible within system (axiomatic)
iiSunan∀ + →Under ⟨MA⟩; explicit textual exceptions
iiiLegislativeO / F / PRule not defeasible; compliance per [Q 2:286]
ivEschatologicalOnly by explicit textual exception
vConditional promise→ with divine guarantee⟨MA⟩ on manner / timing only
viCounterfactual□→ counterfactualArgumentative; not predictive (3 subtypes — see Gate Forms)
viiNarrativeInstance dataGeneralises only via explicit sunna tie
Slices
Gate Forms
20 formal gate-shapes in 6 families. The structural patterns rules instantiate.
In plain terms

"If X then Y" comes in many shapes. Sometimes Y is the only thing that can happen given X (universal). Sometimes Y is one of several possibilities. Sometimes X is required for Y but doesn't guarantee it (necessary precondition). Sometimes X by itself is enough for Y (sufficient condition). Sometimes there are multiple things you have to satisfy together (conjunctive). The grammar of the if-then matters. Twenty distinct shapes are catalogued below in six families.

Twenty gate-forms organised in six families. Each rule in the corpus uses one or more of these. Where rules reference a gate-form by number — e.g. "Universal-conditional (1)" — this is the catalog entry.

Reference
Particles
20 Arabic logical particles with inference behaviour and worked examples.
In plain terms

Arabic uses small connecting words — إن, إذا, لو, إلا, etc. — that fix the logical force of a sentence. لو means "had it been" (counterfactual — contrary to fact). إن means "if" (open possibility). Reading لو as if it were إن turns an argument into a forecast. Below: twenty particles, each with inference behaviour and an example.

Each particle's surface form maps to a specific inference behaviour. Misreading a particle silently corrupts formalisations.

Category
20 particles

§Two flagged ambiguities

i. Strength of إذا vs. إن

Some classical scholars read إذا as conveying greater certainty about antecedent realisation than إن; others treat them as inferentially equivalent. We treat them as inferentially equivalent unless context supplies a reason to distinguish, flagging the assumption explicitly when it matters.

ii. The فـ particle

Sometimes introduces a consequent من يفعل ذلك فله كذا; sometimes purely sequential, equivalent to ثم. We disambiguate ayah-by-ayah; we do not adopt a blanket rule.

Reference
Glossary
54 terms used across the apparatus. Filter by category or jump by initial letter.
What this is

Every Arabic term and classical concept used in the apparatus, defined plainly. Search to jump to a term, or use the alphabet bar.

Category
Spine
Rules
54 formalised rules — the gold of the engine. Filter by type, warrant, or search.

Warrant scale: from strongest (top) to weakest (bottom). Higher warrant means greater confidence the rule operates as universal/invariant.

A Axiomatic — ontological self-disclosure about Allah or fundamental reality. Functions as system axiom, not a gate.

M Explicitly tagged sunnat Allāh — the strongest invariance warrant for gate-statements.

W Explicit waʿd Allāh / ḥaqq — divine-promise marker.

R+ Strong multi-locus pattern (4+ ayat, sometimes near sunna-density without explicit tag).

R Standard multi-locus (2–3 ayat, consistent structure).

S Single-locus statement — weakest warrant for invariance treatment.

Statement type
Warrant
54 rules
Spine
Verses
Every verse the engine cites — reverse index across rules, tensions, and particles. Click the Q-reference to open the Atlas; click any chip to jump to the source. Why only 184 verses? These are the ayāt the Logic Engine's 54 rules formally apply to. The full corpus of 6,236 ayāt lives in the Atlas ↗ — every verse here links there for the broader context.

The reverse direction of the citation bridge. Each verse card lists the rules / tensions / particles that cite it; the Q-ref opens the Atlas's full annotation stack for that ayah.

Cited by
Period
— verses
Slices
Tensions
9 worked cases of apparent contradiction in the corpus, each resolved by a mechanism.
In plain terms

People sometimes claim "the Quran contradicts itself here." Most of these apparent contradictions resolve through specific structural moves once you have the right vocabulary. Nine worked examples below — each demonstrates a distinct mechanism (A through F).

Nine representative tension-pairs showing how apparent contradictions resolve.

Slices
Mechanisms
6 resolution moves for apparent contradictions in the corpus. Each tension cites one.
In plain terms

When two ayat seem to contradict, there are six recognised resolution moves. These aren't ad-hoc — most map to long-standing principles in classical Quranic interpretation. Knowing the catalog lets you diagnose what's actually going on quickly.

Six mechanisms by which apparent textual tensions resolve. Most contradictions in popular polemic against the Quran reduce to one of these.

Slices
Pitfall Index
12 common errors when reading rules. Each pitfall lists the rules it applies to.
In plain terms

The same kind of reasoning mistake recurs across many different ayat. Catalogued here by pattern: reverse-inference (running a gate backward from observable to cause), conjunction-reduction (treating one of two required conditions as sufficient by itself), universalising restricted scope, etc. Studying the patterns helps you avoid them.

Reasoning errors organised by pattern type. Each pattern is illustrated with rules where it commonly occurs.

Slices
Graph
Typed edges between rules — presupposes / parallels / qualifies / applies-to / gate-distinct-from / conflicts-with. Auto-derived from tensions; hand-authored elsewhere with confidence ratings. Click any node to open its rule detail.
Show
— edges

Layout: concentric rings by warrant strength. Inner: A-axioms (5). Inner-mid: M-sunna (5). Outer-mid: W (5) + R+ (11). Outer: R (25) + S (3).

Edge confidence: solid = high (textually grounded), dashed = medium (interpretive). Hover any edge to see the relation type, mechanism (if any), and authorship note.

Reference
Composition
How multiple gates combine when simultaneously active for one agent.

Composition Sandbox

Pick up to 3 rules from the corpus and declare which of their antecedents hold for a specific agent. The engine shows which gates fire, which apparent contradictions become tractable, and any compositional notes from the relationship layer.

1Select rules
2Agent state

Select at least one rule above to declare an agent state.

3Output — what fires

Set the agent state above to see which gates fire.

Composition theory — §3.1–3.4 of the apparatus (click to expand)
In plain terms

Real moral life isn't one rule running at a time — it's many rules running at once. Someone might be on the gratitude-gate, the avoidance-of-major-sins gate, AND have an unrepented sin issue, all simultaneously. How do these compose? The Quranic answer, drawn together below, is that gates run in parallel, and the eschatological reckoning aggregates them.

3.1Gates run in parallel

Each gate-rule is independently active when its antecedent is satisfied. A person performing shukr while also persisting in a major sin is on both the gratitude gate (running toward ziyāda) and on the persistent-sin gate (running toward consequence). The two do not cancel — they aggregate.

Schema: gates compose additively

For agent x at time t: Active_Gates(x, t) = { all gates G_i where antecedent(G_i, x, t) holds } Each gate runs independently: G₁: SHUKR(x) → ⟨MA⟩ INCREASE(x, niʿma) G₂: PERSISTENCE_IN_SIN(x) → ⟨MA⟩ CONSEQUENCE(x) G₃: TAQWA(x) → ⟨MA⟩ MAKHRAJ(x) ∧ RIZQ_UNEXPECTED(x) ... Final eschatological state aggregates outputs: Mīzān(x) = ⊕ outputs of G_i [under ⟨MA⟩, with mercy / forgiveness ops]

3.2Worked composition example

Consider an agent who: (a) performs shukr, (b) avoids major sins, (c) commits a minor sin without repentance, (d) gives ṣadaqa in private, (e) supplicates often. Five gates are simultaneously active:

G₁: r-shukr [14:7] SHUKR(x) → ⟨MA⟩ INCREASE(niʿma) G₂: r-kabair [4:31] AVOIDS(kabā'ir) → ⟨MA⟩ EXPIATE(sayyiʾāt) G₃: r-dua [40:60] DU'Ā(x) → ⟨MA⟩ ISTIJĀBA G₄: r-atom-evil [99:8] DOES(atom_evil) → □ SEES(atom_evil) G₅: r-no-waste [11:115] AḤSANA('amal) → ⟨MA⟩ ¬WASTE(ajr) Net trajectory: G₁, G₂, G₃, G₅ all running positive. G₄ running consequential for the unrepented minor sin. G₂ may absorb G₄'s output (4:31 expiation). Final state: under ⟨MA⟩, mercy, and forgiveness operators.

3.3The observational-ambiguity meta-pattern

A structural feature of the gate system, not a one-off tension: multiple gates can produce the same observable. Surface prosperity can be the output of r-shukr, r-istidraj (warning stage), r-empowerment, or simple ⟨MA⟩-distribution. Surface hardship can be from testing per r-death, from internal-change failure per r-internal-change, from kufr-of-niʿma, or from r-empowerment not yet realised.

Implication

Forward-running of gates is reliable; backward inference from observable to which gate is active is not. From the outside, gate-diagnosis is structurally limited. This is not a defect — the Quran itself indicates inner states are opaque to outside observers, and that the eschatological reckoning is precisely what aggregates and discloses what observation cannot.

3.4Three principles of composition

Principle 1 — Parallel, not sequential

Gates are not processed one-by-one in temporal order; they all run on the same underlying state. An agent performing many actions simultaneously activates many gates simultaneously.

Principle 2 — Some gates absorb others

Certain gates explicitly absorb the output of others — e.g. r-kabair [Q 4:31] absorbs minor-sin consequences when major sins are avoided. r-tawba [Q 39:53] absorbs sin-output when repentance occurs pre-death. Composition is not just additive but has explicit absorption operators.

Principle 3 — The mīzān aggregates, ⟨MA⟩ governs

Final aggregation occurs at the eschatological reckoning [Q 99:7–8], [Q 21:47]. Throughout, ⟨MA⟩ — the meta-condition — governs: mercy, forgiveness, and divine response are not mechanical outputs but operate under Allah's will, with the gates as the system architecture, not as levers.

Reference
Practice
Reading a verse: the six-step workflow plus two worked examples — applying the apparatus to a fresh ayah.
What this is

A six-step workflow for analysing a Quranic verse with the apparatus. Use this when you encounter an ayah and want to think rigorously about what it does and doesn't claim. Two worked examples follow.

4.1The six-step workflow

Identify particles

Scan for the small connecting words that fix logical force: إن، إذا، لو، إلا، كل، من، ما، عسى، لعل، فـ, etc. The presence and exact form of these particles determines what kind of statement you're reading.

Why this comes first: misreading a particle silently corrupts everything that follows. A لو read as إن turns a counterfactual argument into a forecast.

→ Particle catalog

Identify gate-form

Match the verse to one of the 20 gate-forms. Universal-conditional? Counterfactual? Quantified-necessity? Permissive? The gate-form is the formal shape of the if-then (or non-if-then) structure.

Why this matters: the gate-form determines what kinds of inference the verse licenses. A blocking-precondition (gate 3) doesn't license forward prediction — it only blocks. A universal-conditional (gate 1) licenses forward inference but only under ⟨MA⟩.

→ Gate forms catalog

Classify statement type

Which of the seven statement-types is this? Ontological, sunan, legislative, eschatological, conditional-promise, counterfactual, or narrative? Different types follow different inference rules.

Common error: reading a legislative statement as predictive. F(zinā) does NOT entail ¬OCCURS(zinā). The forbidden may still occur; the statement is about moral status, not factual prediction.

→ Statement types

Assess warrant

How strongly does the text license treating this as universal? Is it explicitly tagged sunnat Allāh (M), divine promise (W), multi-locus pattern (R+ / R), or single-locus (S)? Weaker warrant means more caution about generalising beyond the text.

What this protects against: taking a single dramatic narrative ayah and treating it as a universal sunna without other ayat tying it that way. The classical apparatus has its own version of this guard (ʿibra being earned, not assumed).

Mark ⟨MA⟩ scope

Where does mashīʾat Allāh apply? On the gate-form itself? On the manner and timing of the consequent? On agent compliance? Recall the three cases: (a) statements about Allah's action — no ⟨MA⟩; (b) statements about created outcomes — ⟨MA⟩ on outcome; (c) legislative — no ⟨MA⟩ on rule, ⟨MA⟩ on compliance.

Check for tensions

Does this verse appear to conflict with another? If so, which of the six resolution mechanisms applies? Scope-restriction? Type-distinction? Gate-distinction? Chain-decomposition? Layer distinction? Composition?

→ Worked tensions · → Mechanisms

4.2Worked example A — gratitude gate

Q 14:7

وَإِذْ تَأَذَّنَ رَبُّكُمْ لَئِن شَكَرْتُمْ لَأَزِيدَنَّكُمْ ۖ وَلَئِن كَفَرْتُمْ إِنَّ عَذَابِي لَشَدِيدٌ

"And when your Lord proclaimed: 'If you are grateful, I will surely increase you; and if you deny, indeed My punishment is severe.'"

Step 1 · Particles لَئِن (la-in) appears twice — emphatic conditional, "if indeed." إن introduces standard real-conditional. ل in لأزيدنكم is lām al-tawkīd (emphatic), not lām al-taʿlīl (purposive).
Step 2 · Gate-form Universal-conditional (gate 1), paired. Two parallel one-direction conditionals: shukr → ziyāda, and kufr-niʿma → ʿadhāb.
Step 3 · Statement type Sunan + Conditional Promise. Two-typed because the gate is invariant in its structure (sunan) but is also a divine promise about consequence (conditional promise).
Step 4 · Warrant R — multi-locus consistent structure (cf. 31:12, 27:40, 39:7). Not explicitly sunna-tagged; classified R rather than M.
Step 5 · ⟨MA⟩ scope On manner and timing of ziyāda. The form (material / spiritual / dunyā / ākhira) is underspecified by the text.
Step 6 · Tensions Yes — Tension 3 (gate-distinction with r-istidrāj). Both gates can produce the same observable (visible increase). Not a contradiction; an observational-ambiguity feature.
Three pitfalls to avoid (1) Reading ziyāda as material-only. (2) Reading the gate as biconditional (lack of visible ziyāda doesn't entail kufr-of-niʿma). (3) Reverse-inference from observable hardship to ingratitude.

4.3Worked example B — counterfactual reasoning

Q 21:22

لَوْ كَانَ فِيهِمَا آلِهَةٌ إِلَّا اللَّهُ لَفَسَدَتَا

"Had there been within them gods other than Allah, both would have been corrupted."

Step 1 · Particles لَوْ (law) — counterfactual, contrary to fact. The antecedent is presumed false. إِلَّا — exception. ل in لفسدتا — emphatic on the consequent.
Step 2 · Gate-form Counterfactual (gate 9). Specifically, the reductio subtype — the form is a kalāmic argument, modus tollens applied counterfactually.
Step 3 · Statement type Counterfactual. The verse is NOT a forecast that the heavens and earth would be corrupted; it's an argument that they aren't, by showing that the assumption of plural gods would entail consequences contrary to observation.
Step 4 · Warrant R. The kalāmic line distinct from 17:42 (which makes a different argument). Repeated reasoning structure across the corpus.
Step 5 · ⟨MA⟩ scope Not applicable — counterfactual reasoning operates at argumentative layer.
Step 6 · Tensions None apparent. Distinct from Q 17:42 (different argument structure — hierarchical, not cosmological).
Inference structure PLURAL_GODS(heavens, earth) □→ CORRUPTED(heavens ∧ earth)
OBSERVED: ¬CORRUPTED(heavens ∧ earth)
∴ ¬PLURAL_GODS — by modus tollens.

4.4Practice prompts

To internalise the workflow, try applying it (without first reading the apparatus's existing rule) to:

  • [Q 13:11] — Try the workflow. Then check r-internal-change.
  • [Q 65:2–3] — Try the workflow. Then check r-taqwa.
  • [Q 30:30] — Try the workflow. Then check r-fitra.
Reference
Plain-English Tour
Newcomer-friendly walkthrough of the five key ideas. No classical or formal-logic background required.
For everyone

This tour assumes no background in classical Islamic studies or formal logic. It introduces the apparatus's main ideas in plain English, with technical terms gently introduced and glossed.

What is this tool?

This is a tool for thinking carefully about Quranic statements. The Quran says many different kinds of things: it makes claims about reality, gives commands, makes promises, reasons hypothetically, tells stories. Each kind of statement behaves differently when you reason about it. This tool is a vocabulary and method for telling them apart and engaging them rigorously.

Why does this matter? Because most arguments about the Quran — both arguments from it (people drawing conclusions from a verse) and arguments against it (people claiming it contradicts itself) — fail at the basic level: they miss what kind of statement they're dealing with. A command read as a forecast. A counterfactual argument read as a prediction. A historical narrative read as a universal rule. Once you have the vocabulary, much of the noise drops away.

Key idea 1 — Different kinds of statements

The apparatus identifies seven kinds of Quranic statement, each with different logical behaviour:

  • Ontological — describes how reality fundamentally is. "Allah is One" is ontological. These don't follow from anything; they're foundational claims.
  • Sunan (invariant patterns — "the way Allah does things") — repeated patterns the Quran says don't change. "Whoever is grateful, Allah increases them" is a sunan-style claim.
  • Legislative — commands and prohibitions. "Establish prayer" is legislative. Not a prediction — that someone is commanded to do X doesn't mean X will happen.
  • Eschatological — about death, judgment, the hereafter. "Every soul will taste death" is eschatological — a guaranteed future fact.
  • Conditional promise — "if you do X, Allah will do Y." Bind divine response to human action.
  • Counterfactual — "had X been the case, Y would have happened." These are arguments, not forecasts. The Quran uses them to refute false beliefs.
  • Narrative — stories of past peoples. These are case data. They become rules only when explicitly tied to a sunan elsewhere.

If you remember nothing else from this tour: different kinds of statements have different inference rules. Mixing them up is where most bad reasoning starts.

Key idea 2 — "If X then Y" comes in many shapes

"If X then Y" sounds like one structure. It isn't. It comes in at least eight conditional shapes plus several non-conditional shapes. A few examples:

  • Universal conditional: "everyone who does X gets Y" — applies to all agents.
  • Necessary precondition: "Y doesn't happen until X" — X is required, but doesn't guarantee Y. ("No town is destroyed until a warner is sent" — having a warner doesn't guarantee destruction.)
  • Conjunctive precondition: "if X and Z and W, then Y" — multiple things required together. Reducing to "if X then Y" loses the structure.
  • Counterfactual: "had X been the case, Y would have happened" — argues from impossibility, not predicting.
  • Permissive: "no blame if you do X" — removes restriction; doesn't require the action.

The full catalog is here.

Key idea 3 — Some patterns are explicitly invariant

The Quran does something striking: it explicitly tags certain patterns as invariant. The phrase is sunnat Allāh ("Allah's way" — the established pattern that doesn't change). When you find this phrase, you've found one of the corpus's strongest claims about how reality works. The text says directly: this isn't just how things happened in this case; this is how things always work.

Six ayat carry the explicit sunnat Allāh tag (Q 17:77, 33:38, 33:62, 35:43, 40:85, 48:23). The apparatus formalises each of these as a top-warrant rule.

This is also where the apparatus's warrant scale comes from. A claim that's explicitly tagged sunnat Allāh gets the strongest warrant for treating-as-invariant (M). A claim repeated four times across the corpus with consistent structure gets the next-strongest (R+). A claim that appears only once gets the weakest (S). The scale lets you calibrate confidence — claims aren't all equal even if all are textual.

Key idea 4 — Apparent contradictions usually have specific resolution moves

Sometimes two ayat seem to contradict. Most of the time, this resolves through one of six recognised structural moves:

  • A. Scope restriction — one ayah states a general rule; another carves out a specific exception. Both hold, in their respective scopes.
  • B. Type distinction — what looks like one predicate splits into two distinct predicates. The "burden" in one ayah is direct-personal-sin; the "burden" in another is misleading-others-burden. Both hold.
  • C. Gate distinction — same observable, different antecedents. Surface prosperity can come from gratitude (running positive) or from istidrāj (slow-burning warning) running negative. The gates don't contradict; backward-inference from observable to gate fails.
  • D. Chain decomposition — what looks immediate is actually a compressed chain.
  • E. Layer distinction — two ayat operate at different layers (e.g. ontological substrate vs. operational deontic).
  • F. Composition — what looks contradictory is sequential phases of one process.

Knowing the catalog lets you diagnose tensions quickly. Nine worked examples here.

Key idea 5 — Multiple gates run at once

Real moral life isn't one rule running at a time — it's many at once. A person might be grateful (running the gratitude gate), avoiding major sins (running the major-sin avoidance gate), supplicating (running the duʿāʾ gate), but also persisting in a minor failure (running its consequence gate). All these gates run in parallel. They aggregate at the eschatological reckoning.

This matters because it's how the apparatus avoids being mechanical. You don't run one gate and conclude. You map the active gates and acknowledge the parallel composition. More here.

What this tool isn't

Not a replacement for classical Islamic scholarship. The apparatus sits on top of tafsir (Quranic commentary), uṣūl al-fiqh (legal theory), classical Arabic, and the science of sabab al-nuzūl (occasion of revelation). It uses these; it doesn't replace them.

Not a fiqh-derivation tool. Mapping a verse to a gate-form does not yield a juristic ruling. Fiqh requires its own methodology beyond gate-classification.

Not metaphysics. The apparatus shows that texts about divine will and human agency are textually coherent. It does not solve the deeper philosophical question of how those things are compatible. That's a different project.

Not exhaustive. The 43 rules cover much of the corpus's gate-system but not all of it. The apparatus is a tool; the text is larger than any tool.

Where to go next

If this orientation makes sense, try the Reading a Verse workflow next — it's the practical application of everything above.

For deeper engagement: Statement types, Gate forms, Rules, Worked tensions.

Before treating any of this as authoritative, read the Limits section.

Reference
Limits
What the apparatus cannot do. The methodological guardrails that keep the tool from overreaching. Required reading before treating any output as authoritative.
In plain terms

Tools of this kind tempt the people who use them to overestimate what they prove. This section is a deliberate counterweight: spelling out where the apparatus's reach genuinely ends, and where treating its output as authoritative would be a mistake.

5.1Anti-ratiocentric guardrails

The apparatus exists to engage the text more rigorously, not to override it. Three guardrails apply absolutely:

i. Apparatus output never overrides plain reading

When apparatus-output conflicts with the plain reading of an ayah, the apparatus is wrong, not the ayah. The formalisation must be revised; the text stands.

ii. The Quran is not reduced to logic

The apparatus should never be used to systematise the Quran into something the text itself does not claim to be. The Quran uses logical structure for its purposes; it is not reducible to logical structure. Formalisation gives a skeleton; the body of the text exceeds it.

iii. No premature inconsistency claims

The apparatus should never be used to dismiss interpretations on grounds of "logical inconsistency" before cross-textual resolution work has been done. Most apparent inconsistencies dissolve under careful application of the resolution mechanisms.

5.2What the apparatus cannot do

Cannot replace classical sciences

Built on top of tafsir, uṣūl, and ḥadīth sciences — not in place of them. Sabab al-nuzūl, classical lexicon, qirāʾāt (authorised variant readings), and balāgha (rhetoric) remain prerequisites. The apparatus is a shortcut around nothing.

Cannot derive fiqh

Gate-classification does not yield jurisprudence. Even when [Q 4:11] inheritance shares are formalised, the formalism does not tell us what to do in cases the text does not directly address. Fiqh requires its own methodology — qiyās, istiṣḥāb, maṣlaḥa, the science of tarjīḥ — beyond gate-form classification.

Cannot eliminate ⟨MA⟩

Every gate involving created outcomes operates under divine will. The apparatus marks ⟨MA⟩ explicitly but cannot remove it. Treating any gate as mechanically deterministic is a category error. The gates are reliable in the structural sense; they are not levers.

Cannot resolve metaphysical questions

The apparatus is textual. It can show that the qadar / free-will texts are coherent at the textual layer (Tension 5) via layer-distinction. It cannot resolve the deeper metaphysical question of how comprehensive divine will is actually compatible with genuine human agency. That is a separate philosophical project.

Cannot diagnose individual gate-states from outside

When multiple gates can produce the same observable (the observational-ambiguity meta-pattern, Composition §3.3), outside observers cannot reliably diagnose which gate is operative for a given person. This is structural, not a defect — the Quran itself indicates that inner states are opaque to outside observers.

Cannot adjudicate genuinely ambiguous text

Some ayat have multiple sound qirāʾāt yielding different gate-forms ([Q 17:16] amarnā vs ammarnā). Mubhamāt (genuinely ambiguous expressions) resist single formalisation. Where the text is genuinely indeterminate, the apparatus marks the indeterminacy rather than imposing closure.

Cannot legislate or extend

Descriptive-analytical, not prescriptive. Surfaces what the text says; does not extend it. Apparent extensions ("if P→Q runs, then by analogy P'→Q' must follow") are interpretive moves requiring their own justification.

Cannot capture rhetorical and aesthetic dimensions

The Quran's rhetorical architecture (balāgha, iʿjāz (rhetorical inimitability), sound-meaning interplay, repetition-with-variation, emotional cadence) is real and theologically significant. Formalisation strips this. The skeleton is useful; the full text exceeds it.

5.3Categories where the apparatus is weakest

CategoryWhy weak
Muqaṭṭaʿāt (disjointed letters)Meaning mubham; no gate-structure
Eschatological imageryOften ontological-descriptive, not gate-form
Highly metaphorical ayatFormalisation flattens the metaphor
Disputed qirāʾātMultiple readings yield different formalisations
Narrative without sunna-taggingInstances rather than rules
Direct address with situational referentUniversal vs situational scope ambiguous

5.4Honest scope

This is one methodological lens among many. Most useful for: systematic mapping, consistency-checking, pitfall-diagnosis, reference tools, stress-testing claims that purport to derive from the Quran. Least useful for: aesthetic and rhetorical engagement with individual ayat, full-meaning tafsir, theological systematisation, direct fiqh derivation, apologetic argumentation against careful classical scholarship. The apparatus produces a skeleton. The text itself is the body.