AI Rules Generator

You are an elite software engineer working with Cursor. Follow these repository rules rigorously.

## Framework & Architecture Guidelines

### Next.js App Router & Server Components
- Default to React Server Components (RSC). Only add "use client" when required for client event listeners, browser APIs, or interactive React state.
- Never fetch initial server data inside useEffect hooks on the client. Fetch data directly in Server Components using async/await or cached helpers.
- Use Server Actions for all state mutations. Validate incoming parameters using Zod schemas before touching data stores.
- Call revalidatePath or revalidateTag immediately following successful database operations to keep cached views synchronized.

### Tailwind CSS & Layout
- Use semantic HTML elements (<header>, <nav>, <main>, <article>, <section>, <footer>) over generic <div> containers.
- Maintain responsive, mobile-first design using Tailwind breakpoints (sm:, md:, lg:, xl:).
- Design dark-mode first with WCAG AA compliant contrast ratios (minimum 4.5:1 for body copy).
- Ensure all interactive buttons, links, and touch targets meet the minimum 44x44px hit area on mobile viewports.

## Language & Typing Standards

### TypeScript Strictness
- Never use 'any'. Use unknown with type guards, or define explicit discriminated union interfaces.
- Avoid type assertions (as Type or as any). Let the TypeScript compiler infer types naturally.
- Enable and uphold strictNullChecks and noImplicitReturns.
- Model multi-state workflows using discriminated union types (e.g. { status: 'idle' } | { status: 'loading' } | { status: 'success'; data: T }).

## Operational Discipline & Workflow

### Verification Gate
- Run automated verification (npm run lint, npx tsc --noEmit, and test suites) following any code change.
- Zero lint warnings or type errors allowed in clean pull requests.
- Verify that development server and build commands compile without warnings or missing exports.

### Git Discipline & Commits
- Make atomic commits that accomplish one discrete goal with passing tests.
- Use Conventional Commits format: type(scope): concise description (e.g. feat(auth): add double opt-in validation).
- Never commit broken code, uncommitted secrets, or temporary debugging logs.

### Surgical Code Editing
- Make targeted, minimal diffs. Do not rewrite entire files when editing a few lines.
- Preserve existing comments, docstrings, and license headers unless explicitly requested otherwise.
- Avoid blanket code formatting changes that obscure git blame history.

## Testing & Verification

### Verification-First Testing
- Write automated unit tests for every new feature, calculation, or bug fix.
- Test both sunny-day scenarios and edge-cases (e.g. empty states, invalid inputs, boundary numbers, timeouts).
- Never report a task as complete if tests or typechecks fail.
- Keep unit tests fast, deterministic, and isolated from external network dependencies.

## Prohibited Anti-Patterns (Avoid)

- NEVER use client-side useEffect for initial data fetching. Use React Server Components or server loaders.
- NEVER bypass the type system with 'as any' or 'as unknown as T'. Fix the underlying type signature or write a proper type guard.
- NEVER consume raw JSON payloads, query parameters, or form data without strict schema validation (Zod, Pydantic, or Valibot).