# Global Guidelines & Development Guardrails

**Last Updated:** 2026-04-04

This document houses the detailed global guidelines previously stored in `.cursor/rules/global.mdc`. It serves as the definitive reference for planning requirements, project-wide standard component usage, performance baselines, and development workflows.

## 1. Planning Requirements

Plans must be **correct and auditable**, not maximally verbose. **Right-size** depth to the task: use enough discovery to avoid wrong edits, then implement and validate. **Validation quality is non-negotiable** regardless of plan length.

### Plan structure (Cursor Plan Mode)

**Canonical phase checklist:** [cursor-playbook.md](cursor-playbook.md) § **Plan structure requirements** (Discovery → Implementation → Validation → Risks & Rollback → Handoff). Use that section for phase names and ordering; use the tier table below for how deep each phase goes.

### Task classification (tiered planning)

Use the **smallest** structure that still covers risk:

| Tier | Examples | Phases to emphasize |
|------|----------|---------------------|
| **Maintenance** | Typos, single-file bugfix, copy tweak, one known script | Implementation + Validation; Discovery only if unclear |
| **Implementation-heavy** | Well-specified multi-file change, new section on existing page | Discovery + Implementation + Validation + short Risks |
| **Research-heavy** | New feature, architecture change, new pipeline, base component change | Full discovery, explicit research, Validation across surfaces |

**Rule of thumb:** If the task is maintenance but touches `v2/base/` or shared schemas, **upgrade** at least one tier for Discovery and Validation.

## 2. Whole-Project Thinking
- **Comparison Pages**: Apply changes to all 67 pages if applicable (plan Multi-Edit).
- **Product Pages**: Apply changes to all 8 product pages.
- **Base Components (`v2/base/`)**: ⚠️ HIGH IMPACT. Test across 5+ page types (Product, Industry, Tools, Comparison, Homepage).
- **Schemas**: Verify all URLs are absolute, dates use current year, pricing is up-to-date.

## 3. Standard Component Usage (PHP)

Apply to ALL page types unless overridden:

```php
// Head Section
$aosScript = "true";  // or "false" if no animations
$swiperScript = "false";  // or "true" if carousel needed
include '../base/head.php';

// Header
$headerwidth = "w-full";  // or "max-w-7xl" for contained
include '../base/header.php';

// CTA Buttons
$ctaPositionLeft = 'true';  // or 'false' for right
$ctaButtonsAOS = 'false';  // animation
$ctaButtonsLight = 'yes';  // or 'no' for dark
$showCallbackButton = 'yes';  // or 'no' to hide callback
include '../base/include_ctabuttons.php';

// Footer
$color_fill = '#fff';
$color_background = '#fbfbfb';
$rotate = '0';
$margin_bottom = 'mb-24';
include '../base/footer.php';
```

## 4. Performance Baseline

- **Images**: Use WebP, include `srcset` and `sizes`, explicit `width`/`height`.
- **Preloading**: `fetchpriority="high"` for above-fold LCP images. `loading="lazy"` for below-fold.
- **CSS Loading**: `media="print"` trick for non-critical CSS. Cache busting via `filemtime()`.
- **JS Loading**: Defer non-critical scripts. NO `console.log()` in production (use `logger.js`).

## 5. Development Workflow & Best Practices

- **Local Development Server**: **CRITICAL** - Do not start `php -S localhost:8003`. The project uses Docker. Assume it's running.
- **Before Modifying Blog Content**: Use `update-post-content.php`. NEVER edit JSON files directly. Create a local snapshot backup before bulk changes.
- **Before Modifying URL Redirects**: Use QSA flag, R=301, and test thoroughly.
- **Before Pushing Rule Changes**: DO NOT run `make rules` or validation during editing. Update `METADATA_INDEX.json` via `make rules` when ready to commit.
- **Internal Links**: Always use canonical URLs (destination), not redirect sources. Do not link to `/kostenlos-testen`.
- **Date Management**: Run `date +%Y-%m-%d` or use file modification time `stat -f "%Sm" -t "%Y-%m-%d" filename`. Never use placeholder dates.
- **Documentation**: Avoid duplicates. Update existing status files instead of creating new ones.
- **CSS/JS Minification**: ALWAYS run `npm run minify` after editing CSS/JS files in `v2/css/` or `v2/js/`.

## 6. Error Handling & Security

- **Sanitization**: `htmlspecialchars(trim($input), ENT_QUOTES, 'UTF-8')`
- **Email Recipients**: **CRITICAL** - All error, debugging, testing, and system notification emails MUST be sent to `hady@ordio.com` (NOT david@ordio.com). Business functional emails can go to others.
- **Security**: Store API keys in config files, never in code. Rate limit endpoints.

## 7. PHP Extension Dependencies

**CRITICAL**: PHP extensions (mbstring, iconv, gd, curl, etc.) may be missing in production.
- **ALWAYS** check `function_exists()` or `extension_loaded()` before using an extension function.
- **Always provide a fallback** (e.g., `iconv` fallback for `mbstring`).
- See `.cursor/rules/php-extensions.mdc` for comprehensive patterns.