Skip to content

ZAD_MANDATE.md

Latest commit

 

History

History
127 lines (90 loc) · 6.49 KB

ZAD_MANDATE.md

File metadata and controls

127 lines (90 loc) · 6.49 KB

The ZAD Development Mandate: A Framework for Building Software That Fucking Works

🚨 CRITICAL METHODOLOGY REQUIREMENT 🚨

⚠️ MANDATORY: ALL DEVELOPMENT AND DOCUMENTATION MUST FOLLOW THIS FRAMEWORK ⚠️

This document supersedes all previous PRDs and documentation style guides. It establishes a unified methodology for both project execution and reporting. Its purpose is to eliminate the primary cause of project failure: building complex, feature-rich applications around a broken or unproven core.

This framework has two parts:

  1. The Core-First Mandate (The Blueprint): A strict, sequential process for building software. It forces the validation of the most critical, high-risk component first.
  2. The ZAD Reporting Framework (The Inspection Report): A documentation style for proving that each step of the Mandate was completed correctly, leaving zero assumptions.

Methodology Compliance:

  • All project plans MUST be derived from the Core-First Mandate using TaskMaster.
  • All reports on completed work MUST use the ZAD Reporting Framework.
  • NO EXCEPTIONS.

🔥 THE CORE PROBLEM THIS SOLVES

You've felt this pain: you spend days or weeks developing a massive project. The test suite is green, the features are built, the UI looks great. But when you run it for the first time in a real-world scenario, it fucking breaks. The core function, the entire reason the app exists, was never actually tested.

This happens because development often focuses on what's easy to test (UI components, utility functions, security rules) while avoiding the most complex and uncertain part (the core business logic). You end up with a beautiful, secure fortress built around an empty throne.

The ZAD Development Mandate fixes this by forcing a simple, brutal rule: Prove the engine works before you build the car.

PART 1: THE CORE-FIRST MANDATE (THE BLUEPRINT)

This is the strategic plan that must be followed for all new projects.

Step 1: Isolate and Prove the Core Function

Before writing any web server code, user interface, or comprehensive tests, your first and only task is to write a simple, self-contained script named core_test.py.

  • Requirement: This script must execute the single most critical function of the application using hardcoded data. It must prove the highest-risk part of the system can work.
  • No Dependencies: Do not use Flask, file parsers, or anything beyond the essential libraries needed for the core function (e.g., the openai library).
  • Clear Output: The script must print its result directly to the terminal.

DO NOT PROCEED TO STEP 2 UNTIL THIS SCRIPT RUNS SUCCESSFULLY AND IS MANUALLY VERIFIED.

Step 2: Build a Minimal API Wrapper

Once the core_test.py is working, wrap that proven function in a simple API endpoint.

  • Requirement: The endpoint should accept a JSON object with the same structure as the hardcoded data from Step 1 and return the result.
  • Focus: This step is only about exposing the proven core logic to the network. Keep it minimal.

Step 3: Implement a True End-to-End Browser Test

Before building any complex UI, write a single, automated E2E browser test using a tool like Selenium.

  • Requirement: This test must automate a real browser to hit the API endpoint from Step 2 with valid data and verify that the correct result is returned.
  • Purpose: This test becomes the ultimate gatekeeper. If it passes, the entire critical path of the application is confirmed to be working.

DO NOT PROCEED TO STEP 4 UNTIL THIS E2E TEST PASSES RELIABLY.

Step 4: Build Supporting Features and the Full UI

Only after the core function is proven and validated by a real E2E test can you begin work on the rest of the application.

  • Examples:
    • Building the full user interface.
    • Implementing advanced file parsing and column mapping.
    • Adding security hardening, performance optimizations, and comprehensive error handling.
    • Writing additional unit and integration tests for these secondary components.

PART 2: THE ZAD REPORTING FRAMEWORK (THE INSPECTION REPORT)

This is how you document the work done at each step of the Mandate. It assumes the reader knows nothing and builds their understanding from the ground up.

Core Philosophy: "Crystal Clear Big Picture + Deep Technical Detail"

  • Simple = Easy to understand, no confusing jargon.
  • Detailed = Comprehensive, leaves no questions unanswered.
  • Technical = Real implementation details, actual code, specific commands.
  • Big Picture = Real-world analogies that make the technical parts make sense.

The ZAD Balance: Analogies + Technical Implementation

DON'T: Write purely allegorical explanations. DO: Use analogies to build understanding, then dive deep into the actual technical implementation.

Example of Balance:

## 🏠 **ANALOGY**: The Core Logic is the Engine Block
The `core_test.py` script is like building and testing a car engine on a stand. We're making sure the pistons fire and the crankshaft turns before we even think about putting it in a car frame.

## 🔧 **TECHNICAL IMPLEMENTATION**:
Here's the exact code for the `core_test.py` script that proves our email generation engine works.

### Core Generation Script (`core_test.py`):
```python
# This script has ZERO dependencies on Flask or any web components.
# It only tests the direct interaction with the OpenAI API.
import os
from openai import OpenAI

# 1. Hardcoded Data (The Fuel and Spark)
test_lead = {
    'first_name': 'John',
    'company_name': 'Acme Corp',
    'job_title': 'Lead Developer',
    'industry': 'Software'
}

# 2. The Core Logic (The Engine)
def generate_email_for_lead(lead_data):
    client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
    prompt = f"Write a cold email to {lead_data['first_name']} at {lead_data['company_name']} who is a {lead_data['job_title']} in the {lead_data['industry']} industry."
    
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# 3. The Test Run (Turning the Key)
try:
    print("--- Attempting to start the engine... ---")
    generated_email = generate_email_for_lead(test_lead)
    print("\n✅ SUCCESS! ENGINE IS WORKING.")
    print("--- Generated Email Output: ---")
    print(generated_email)
except Exception as e:
    print(f"\n❌ FAILED! ENGINE SEIZED. ERROR: {e}")