Auto-sync Thu Aug 6 11:31:13 +08 2026

2026-08-06 11:31:13 +08:00
commit 2ac024163b
31 changed files with 3638 additions and 0 deletions
@@ -0,0 +1,39 @@
+## THE FATWA (HUKM)
+
+**HUKM:** We will only incur technical debt that is **Deliberate and Prudent** (as per the Debt Quadrant) and immediately recorded with a repayment plan. **Reckless and Inadvertent debt is Israf** (waste of Hifz al-Mal) and must be repaid within the same sprint. **Zero tolerance for security, compliance, or data integrity debt** – that is always haram.
+
+**DALEEL:** Discovery interviews revealed that 70% of our past “speed” decisions created untracked, compounding debt that later cost 3x the original effort to fix – a clear violation of Hifz al-Mal (waste of wealth) and Hifz al-Aql (mental overload). User evidence showed no feature value from the shortcuts, only bugs. The Debt Quadrant framework (Prudent/Reckless/Deliberate/Inadvertent) confirmed that our only valid quadrant is **Deliberate + Prudent** – where we consciously choose debt with a known payoff and a written exit plan.
+
+**MAQSAD:** Primary: **Hifz al-Mal** – preserving engineering budget and avoiding waste of developer time and future maintenance costs. Secondary: **Hifz al-Aql** – protecting the team’s cognitive load and decision-making ability from chaotic code. Also supports **Hifz al-Din** (trustworthiness in delivering reliable software) and **Hifz al-Nasl** (sustainable product for future users/teams).
+
+**SHURUT:**
+- Every technical debt decision must be logged in a **Debt Register** with: quadrant classification, estimated repayment cost, owner, and “repay by” date.
+- **Reckless** and **Inadvertent** debt that enters the codebase (e.g., from rushed hotfixes) must be repaid within **2 sprint cycles** or escalated to the Product Lead.
+- The team must allocate **at least 20% of each sprint** to debt reduction – this is a non-negotiable Shart (condition) for any new feature work.
+- **No debt** may be incurred on: authentication, payment, user data privacy, or any feature with legal/regulatory implications. Those are Qati (certain) obligations.
+
+**MUNKATHIRAT:**
+- If a debt item causes a **production incident** (P0 or P1), the entire sprint is paused to repay it immediately – that debt is now Israf.
+- If the **Debt Register grows** beyond 10 items or the total estimated repayment exceeds 2 sprint cycles, the fatwa is automatically suspended and a new Shura must be called to re-evaluate the entire backlog.
+- If the team reports **burnout or confusion** due to debt (measured in weekly health checks), the debt is nullified – Hifz al-Aql takes precedence over all other Maqasid.
+
+---
+
+## THE PROTOCOL (3 Steps — This Sprint)
+
+**STEP 1: Audit and Classify Your Current Debt**  
+This Monday, gather the entire engineering team for a **45-minute Debt Quadrant mapping session**. List every known shortcut, hack, or workaround. Place each item into one of the four quadrants (Prudent/Reckless/Deliberate/Inadvertent). Any item in Reckless or Inadvertent gets a red “Israf” label and a **2-sprint deadline** for repayment.
+
+**STEP 2: Create the Debt Register**  
+By Wednesday, set up a shared document or tool (e.g., a spreadsheet or a GitHub project board). For each item, record: quadrant, description, estimated cleanup effort (story points), owner, and “repay by” date. Add a column for the **Maqsad impact**: which of the five Maqasid (Din, Nafs, Aql, Mal, Nasl) is harmed if left unpaid? This makes the cost tangible.
+
+**STEP 3: Reserve 20% Capacity This Sprint**  
+In the current sprint planning, **slice off 20% of the team’s capacity** for debt repayment. Do not negotiate this. Use the register to pick the highest priority item (start with anything that threatens Hifz al-Aql or Hifz al-Mal). If you have no prior debt, use this capacity to build a **routing slip** for future debt decisions – a simple checklist: “Is this decision Deliberate? Is it Prudent? Have we logged it?”
+
+---
+
+## MUHASABA (RETROSPECTIVE)
+
+**Where are we tolerating Israf in the name of speed, and what is the true cost in terms of Hifz al-Mal and Hifz al-Aql?**
+
+Ask this question at your next retrospective. Sit in silence for 60 seconds before anyone speaks. Then force the team to assign a **dollar figure** to each piece of untracked debt – the cost of the bug it caused, the hours of confusion, the delayed feature. This isn’t guilt; it’s a calibration. If you cannot name the cost, you are still in Israf. The moment you name it, you are one step closer to Hifz al-Mal.