export default software-principles

name	software-principles
description	AUTOMATICALLY enforces world-class software engineering principles for every line of code written. Validates architecture, design patterns, file size limits, code structure, and engineering best practices. USE THIS SKILL AUTOMATICALLY when writing ANY code, creating components, implementing features, or refactoring. Also use when user asks to review architecture, check design patterns, ensure best practices, validate code structure, or improve code quality.
allowed-tools	["Read","Grep","Glob"]

The Quantum Core — Software Engineering Principles

Enforces the foundational principles of world-class software engineering, adapted for the SHEREHE platform built with Next.js 16, React 19, and TypeScript.

⚠️ CRITICAL: AUTOMATIC ACTIVATION

This skill MUST be used automatically whenever:

• Writing ANY new code (components, hooks, utilities, API routes)
• Creating ANY new file
• Implementing ANY feature
• Refactoring existing code
• Before completing ANY coding task

DO NOT wait for the user to ask. Apply these principles proactively.

When to Use This Skill

Activate AUTOMATICALLY when:

• Writing any component, hook, utility, or API route
• Creating new files (check 500-line limit)
• Implementing features
• Refactoring code
• The user says "check architecture" or "review design"
• The user asks "is this good architecture?" or "does this follow best practices?"
• The user says "improve code structure" or "refactor this"
• The user requests "validate design patterns"
• The user says "make this production-ready"
• The user asks for architectural guidance or code organization advice

---

🧠 I. The Three Fundamental Principles (The Trifecta)

1. Abstraction

"Hide complexity; reveal intent."

Good engineers manage complexity. Great engineers hide it behind clear interfaces.

✅ Next.js/React Implementation

Server Components (Abstraction Layer)

// ✅ GOOD - Abstract data fetching
// app/events/[id]/page.tsx
export default async function EventPage({
  params
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params;
  const event = await getEvent(id); // Abstracted

  return <EventDetails event={event} />;
}

// lib/api/events.ts - Implementation hidden
export async function getEvent(id: string): Promise<Event> {
  const response = await fetch(`${API_URL}/events/${id}`, {
    next: { revalidate: 3600 }
  });

  if (!response.ok) throw new EventNotFoundError(id);

  return EventSchema.parse(await response.json());
}

Custom Hooks (Abstraction for State Logic)

// ✅ GOOD - Abstract complex state logic
// hooks/use-event-form.ts
export function useEventForm(initialData?: Event) {
  const [state, setState] = useState<EventFormState>(/* ... */);
  const [errors, setErrors] = useState<ValidationErrors>({});

  const validate = useCallback((data: EventFormData) => {
    return EventFormSchema.safeParse(data);
  }, []);

  const handleSubmit = useCallback(async (data: EventFormData) => {
    const result = validate(data);
    if (!result.success) {
      setErrors(formatZodErrors(result.error));
      return;
    }

    await saveEvent(result.data);
  }, [validate]);

  return { state, errors, handleSubmit, validate };
}

// ✅ USAGE - Clean, simple API
function CreateEventForm() {
  const { state, errors, handleSubmit } = useEventForm();

  return <form onSubmit={handleSubmit}>...</form>;
}

❌ BAD - Exposed Complexity

// ❌ BAD - No abstraction, implementation details everywhere
function EventPage() {
  const [event, setEvent] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    fetch('/api/events/123')
      .then((r) => r.json())
      .then(setEvent)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);

  // Component now knows too much about fetching implementation
}

🎯 Abstraction Checklist

• API calls are abstracted into dedicated functions/hooks
• Complex business logic is hidden behind hooks or utilities
• Components receive clean props, not implementation details
• Server Components handle data fetching, Client Components handle interactivity
• Each layer exposes minimal surface area

---

2. Modularity

"Divide to conquer."

Split the system into small, self-contained units that evolve independently.

✅ Next.js/React Implementation

File Structure (Physical Modularity)

app/
├── (public)/              # Public pages module
│   ├── page.tsx
│   ├── about/page.tsx
│   └── early-access/
│       ├── page.tsx
│       └── early-access-client.tsx
├── (dashboard)/           # Dashboard module
│   └── dashboard/page.tsx
├── (events)/              # Events module
│   └── events/
│       ├── [id]/page.tsx
│       └── create/page.tsx

components/
├── features/              # Feature modules
│   ├── events/           # Event-specific components
│   │   ├── EventCard.tsx
│   │   ├── EventList.tsx
│   │   └── EventForm.tsx
│   ├── auth/             # Auth-specific components
│   └── dashboard/        # Dashboard widgets
├── ui/                    # Base UI module (atoms)
│   ├── Button.tsx
│   ├── Input.tsx
│   └── Card.tsx
└── shared/                # Shared utilities
    └── FontLoader.tsx

lib/
├── api/                   # API module
│   ├── events.ts
│   ├── users.ts
│   └── client.ts
├── validations/           # Validation module
│   ├── event-schema.ts
│   └── user-schema.ts
└── utils/                 # Utility module

Component Modularity (SRP)

// ✅ GOOD - Each component does ONE thing

// components/features/events/EventCard.tsx
interface EventCardProps {
  event: Event;
  onFavorite?: (id: string) => void;
}

export function EventCard({ event, onFavorite }: EventCardProps) {
  return (
    <div className="card-sherehe">
      <EventImage src={event.image} alt={event.name} />
      <EventDetails event={event} />
      <EventActions eventId={event.id} onFavorite={onFavorite} />
    </div>
  );
}

// components/features/events/EventImage.tsx
export function EventImage({ src, alt }: EventImageProps) {
  return (
    <div className="relative h-48 w-full">
      <Image
        src={src}
        alt={alt}
        fill
        className="object-cover rounded-t-lg"
      />
    </div>
  );
}

// components/features/events/EventDetails.tsx
export function EventDetails({ event }: { event: Event }) {
  return (
    <div className="p-4">
      <h3 className="font-clash-display text-xl text-sherehe-purple-700">
        {event.name}
      </h3>
      <p className="text-sherehe-purple-600">{formatDate(event.date)}</p>
      <p className="text-sm text-sherehe-purple-500">{event.location}</p>
    </div>
  );
}

❌ BAD - God Component (No Modularity)

// ❌ BAD - One massive component doing everything
function EventPage() {
  // 500 lines of code
  // Fetching, validation, rendering, state management all mixed
  // Hard to test, hard to reuse, hard to maintain
}

🎯 Modularity Checklist

• Each file/component has a single, clear purpose
• NO file exceeds 500 lines (HARD LIMIT - see Cardinal Rule)
• Components are small (< 200 lines ideally, 500 max)
• Features are grouped into modules (folders)
• Modules can be developed/tested independently
• Dependencies flow in one direction (no circular deps)
• Shared code lives in lib/, components/ui/, or components/shared/

---

3. Reusability

"Don't repeat logic, reuse intelligence."

Write once, use everywhere. Encapsulate patterns into hooks, utilities, and components.

✅ Next.js/React Implementation

Reusable Hooks

// hooks/use-local-storage.ts
export function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T) => void] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initialValue;

    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = useCallback(
    (value: T) => {
      try {
        setStoredValue(value);
        if (typeof window !== 'undefined') {
          window.localStorage.setItem(key, JSON.stringify(value));
        }
      } catch (error) {
        console.error(`Error saving to localStorage:`, error);
      }
    },
    [key]
  );

  return [storedValue, setValue];
}

// ✅ USAGE - Reuse everywhere
const [favorites, setFavorites] = useLocalStorage<string[]>('favorites', []);
const [theme, setTheme] = useLocalStorage<Theme>('theme', 'light');

Reusable Utilities

// lib/utils/format.ts
export function formatDate(date: Date | string): string {
  const d = typeof date === "string" ? new Date(date) : date;
  return new Intl.DateTimeFormat("en-RW", {
    year: "numeric",
    month: "long",
    day: "numeric"
  }).format(d);
}

export function formatCurrency(amount: number): string {
  return new Intl.NumberFormat("en-RW", {
    style: "currency",
    currency: "RWF"
  }).format(amount);
}

// ✅ USAGE - Consistent formatting everywhere
<p>{formatDate(event.date)}</p>
<p>{formatCurrency(event.price)}</p>

Reusable UI Components

// components/ui/Button.tsx
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline";
  size?: "sm" | "md" | "lg";
  isLoading?: boolean;
}

export function Button({
  variant = "primary",
  size = "md",
  isLoading,
  children,
  ...props
}: ButtonProps) {
  const baseClass = "btn-base transition-all";
  const variantClass = {
    primary: "btn-primary",
    secondary: "btn-secondary",
    outline: "btn-outline"
  }[variant];

  const sizeClass = {
    sm: "text-sm px-3 py-1.5",
    md: "text-base px-4 py-2",
    lg: "text-lg px-6 py-3"
  }[size];

  return (
    <button
      className={`${baseClass} ${variantClass} ${sizeClass}`}
      disabled={isLoading}
      {...props}
    >
      {isLoading ? <Spinner /> : children}
    </button>
  );
}

// ✅ USAGE - Consistent buttons everywhere
<Button variant="primary">Submit Event</Button>
<Button variant="outline" size="sm">Cancel</Button>

🎯 Reusability Checklist

• Common patterns extracted into hooks (use-*.ts)
• Utility functions in lib/utils/ (format, validation, etc.)
• Base UI components in components/ui/
• No duplicate validation logic (use Zod schemas)
• No duplicate API calls (use abstracted functions)
• Consistent styling via predefined classes (SHEREHE design system)

---

🚨 The Cardinal Rule: 500-Line Limit

NO FILE SHALL EXCEED 500 LINES — PERIOD.

This is not a suggestion. This is a hard constraint that must be enforced on EVERY file.

Why 500 Lines?

A file over 500 lines is:

• Too complex to understand at a glance
• Too hard to test properly
• Too fragile to maintain safely
• Too coupled to refactor easily
• Too risky to modify with confidence

What Counts as a Line?

• ✅ Code lines (logic, JSX, declarations)
• ✅ Import statements
• ✅ Comments and documentation
• ❌ Blank lines (don't count, but don't abuse them)

The 500-Line Rule in Practice

✅ GOOD - File under limit

// components/features/events/EventCard.tsx (120 lines)
export function EventCard({ event }: EventCardProps) {
  // Clean, focused component
  return <div>...</div>;
}

⚠️ WARNING - File approaching limit (450+ lines)

// components/EventManager.tsx (465 lines)
// TIME TO SPLIT! Don't wait until 500.
// Split NOW before it becomes a monster.

❌ VIOLATION - File over limit (500+ lines)

// app/dashboard/page.tsx (687 lines) ❌ REJECTED
// This file is 187 lines over the limit.
// MUST be split into multiple files before merging.

How to Stay Under 500 Lines

1. Split by Concern

   // Before: UserProfile.tsx (650 lines)
   UserProfile.tsx (200 lines) - Main component
   UserProfileHeader.tsx (100 lines) - Header section
   UserProfileStats.tsx (120 lines) - Stats section
   UserProfileActions.tsx (80 lines) - Action buttons
   hooks/use-user-data.ts (150 lines) - Data logic
   

2. Extract Hooks

   // Before: Inline logic (800 lines in component)
   
   // After: Extracted hooks
   use-form-validation.ts (150 lines)
   use-api-client.ts (120 lines)
   use-user-permissions.ts (90 lines)
   Component.tsx (180 lines)
   

3. Extract Utilities

   // Before: Utility functions in component (600 lines)
   
   // After: Separate files
   lib/utils/date-format.ts (80 lines)
   lib/utils/price-calculations.ts (100 lines)
   lib/utils/validation.ts (120 lines)
   Component.tsx (200 lines)
   

4. Extract Types

   // Before: Types + component (550 lines)
   
   // After: Separate type files
   types/event.ts (100 lines)
   types/user.ts (80 lines)
   Component.tsx (220 lines)
   

5. Split Components

   // Before: Monolith component (800 lines)
   
   // After: Component composition
   EventPage.tsx (150 lines) - Container
   EventHeader.tsx (80 lines)
   EventDetails.tsx (120 lines)
   EventActions.tsx (90 lines)
   EventComments.tsx (180 lines)
   EventGallery.tsx (150 lines)
   

🎯 Enforcement Checklist

Before writing code, check:

• Current file line count
• Estimated lines to add
• Will file exceed 500 lines after changes?
• If yes, split FIRST, then add code

When reviewing code:

• Run line count on all changed files
• Flag any file > 450 lines (warning zone)
• REJECT any file > 500 lines (hard limit)
• Suggest split strategy for oversized files

When refactoring:

• Identify files > 400 lines (proactive split)
• Plan component/hook/utility extraction
• Split incrementally (don't create new problems)
• Test each extraction independently

Automated Enforcement

# Check all files for 500-line violations
find app components lib -name "*.tsx" -o -name "*.ts" | while read file; do
  lines=$(wc -l < "$file")
  if [ $lines -gt 500 ]; then
    echo "❌ VIOLATION: $file has $lines lines (limit: 500)"
  elif [ $lines -gt 450 ]; then
    echo "⚠️  WARNING: $file has $lines lines (approaching limit)"
  fi
done

Special Cases (Still Must Split!)

"But this is a configuration file!"

• Split into multiple config modules
• Use composition to combine them

"But this is generated code!"

• Don't commit generated code > 500 lines
• Generate smaller chunks
• Use code splitting

"But this is a complex form!"

• Split form sections into separate components
• Extract validation to schemas
• Use form composition

"But this is all related logic!"

• Extract to multiple focused modules
• Use clear exports to maintain cohesion
• Co-locate related files in same directory

Examples of Proper Splitting

Before (720 lines):

app/events/create/page.tsx (720 lines) ❌

After (compliant):

app/events/create/
├── page.tsx (180 lines) ✅ - Server component, metadata
├── create-event-client.tsx (220 lines) ✅ - Main client component
├── components/
│   ├── EventFormBasics.tsx (150 lines) ✅
│   ├── EventFormDetails.tsx (180 lines) ✅
│   ├── EventFormReview.tsx (120 lines) ✅
│   └── FormNavigation.tsx (80 lines) ✅
├── hooks/
│   └── use-event-form.ts (200 lines) ✅
└── validations/
    └── event-schema.ts (150 lines) ✅

Key Takeaways

1. 500 lines is a HARD LIMIT, not a suggestion
2. Start splitting at 400 lines (don't wait for 500)
3. Split by concern, not arbitrarily
4. Every split should improve clarity
5. Test after every split
6. No exceptions, no excuses

"If your file is over 500 lines, you haven't finished your job."

---

🔭 II. The Supporting Principles (The 13 Quantum Laws)

⚙️ 1. Separation of Concerns

"Each layer handles one concern."

Next.js/React Separation:

• Server Components: Data fetching, server-side logic
• Client Components: Interactivity, browser APIs, hooks
• API Routes: Backend logic, database access
• Components: UI presentation
• Hooks: State management and side effects
• Utils: Pure functions, transformations
• Types: Type definitions
• Styles: Design system (globals.css)

✅ Implementation

// ✅ Server Component - Data concern
// app/events/page.tsx
export default async function EventsPage() {
  const events = await fetchEvents(); // Server-side data fetching
  return <EventsClient events={events} />;
}

// ✅ Client Component - Interaction concern
// components/features/events/EventsClient.tsx
'use client';
export function EventsClient({ events }: { events: Event[] }) {
  const [filter, setFilter] = useState('all');
  const filtered = useFilteredEvents(events, filter);

  return (
    <>
      <FilterControls value={filter} onChange={setFilter} />
      <EventGrid events={filtered} />
    </>
  );
}

// ✅ API Route - Backend concern
// app/api/events/route.ts
export async function GET() {
  const events = await db.event.findMany();
  return Response.json(events);
}

❌ Violation:

// ❌ BAD - Mixing concerns
'use client';
export function EventCard({ eventId }: { eventId: string }) {
  const [event, setEvent] = useState(null);

  // ❌ Fetching in client component (should be server)
  // ❌ Styling inline (should be in className)
  // ❌ Validation here (should be in schema)
  // ❌ Business logic mixed with UI

  return <div style={{ color: 'blue' }}>...</div>; // ❌ Inline style
}

🎯 Checklist

• Server Components handle data, Client Components handle interaction
• No database access in client components
• No inline styles (use Tailwind classes)
• Business logic separated from UI
• Types defined in types/
• Validation schemas in lib/validations/

---

🧩 2. Single Responsibility Principle (SRP)

"One component, one job."

✅ Implementation

// ✅ GOOD - Each does one thing

// Button only handles rendering a button
function Button({ children, onClick }: ButtonProps) {
  return <button onClick={onClick}>{children}</button>;
}

// Form only handles form layout
function EventForm({ onSubmit }: EventFormProps) {
  return <form onSubmit={onSubmit}>...</form>;
}

// Hook only handles form state
function useEventForm() {
  const [data, setData] = useState({});
  const [errors, setErrors] = useState({});
  return { data, errors, setData };
}

// Utility only formats dates
function formatDate(date: Date): string {
  return date.toLocaleDateString();
}

❌ Violation:

// ❌ BAD - Component does too much
function EventManager() {
  // Fetching data
  // Managing state
  // Validating forms
  // Rendering UI
  // Handling navigation
  // Making API calls
  // All in one component!
}

🎯 Checklist

• Each component has one clear purpose (name reveals it)
• Each function does one thing
• Each hook manages one piece of state/logic
• If a component name has "And" or "Manager", it's probably doing too much

---

💡 3. DRY — Don't Repeat Yourself

"Extract repeated patterns."

✅ Implementation

// ❌ BAD - Repeated validation
function CreateEventForm() {
  if (!name || name.length < 3) {
    /* error */
  }
  if (!date || new Date(date) < new Date()) {
    /* error */
  }
}

function EditEventForm() {
  if (!name || name.length < 3) {
    /* error */
  } // Same code!
  if (!date || new Date(date) < new Date()) {
    /* error */
  } // Same code!
}

// ✅ GOOD - Extracted validation
// lib/validations/event-schema.ts
export const EventSchema = z.object({
  name: z.string().min(3, 'Name must be at least 3 characters'),
  date: z.date().min(new Date(), 'Date must be in the future'),
});

// Both forms use the same schema
function CreateEventForm() {
  const result = EventSchema.safeParse(data);
}

function EditEventForm() {
  const result = EventSchema.safeParse(data);
}

🎯 Checklist

• No duplicate validation logic (use Zod schemas)
• No duplicate API calls (use shared functions)
• No duplicate components (extract and reuse)
• No duplicate styles (use design system classes)

---

🔁 4. KISS — Keep It Simple, Stupid

"Simplicity scales. Complexity kills."

✅ Implementation

// ✅ SIMPLE - Easy to understand
function isEventUpcoming(event: Event): boolean {
  return new Date(event.date) > new Date();
}

// ❌ COMPLEX - Over-engineered
function isEventUpcoming(event: Event): boolean {
  const now = Date.now();
  const eventTime = new Date(event.date).getTime();
  const diff = eventTime - now;
  const MS_PER_DAY = 1000 * 60 * 60 * 24;
  const days = Math.floor(diff / MS_PER_DAY);
  return days >= 0;
}

🎯 Checklist

• Prefer clear code over clever code
• Avoid deep nesting (max 3 levels)
• Use early returns to reduce complexity
• Name variables clearly (no x, tmp, data)

---

🧠 5. YAGNI — You Aren't Gonna Need It

"Don't build what's not required today."

❌ Violations

// ❌ BAD - Building for imaginary future
interface Event {
  id: string;
  name: string;
  date: Date;
  // Future features we might need...
  virtualReality?: boolean;
  aiGeneratedContent?: string;
  blockchainVerification?: string;
  quantumEncryption?: boolean;
}

// ❌ BAD - Over-abstraction for one use case
class EventManagerFactoryBuilderProvider {
  // 500 lines of abstraction for a simple function
}

✅ Good Approach

// ✅ GOOD - Build what's needed now
interface Event {
  id: string;
  name: string;
  date: Date;
  location: string;
  // That's it. Add more when actually needed.
}

🎯 Checklist

• Only implement current requirements
• Don't add "maybe useful later" features
• Don't over-engineer abstractions
• Add complexity only when needed, not "just in case"

---

⚖️ 6. SOLID Principles (Adapted for React/TypeScript)

S - Single Responsibility (Already covered above)

O - Open/Closed Principle

"Open for extension, closed for modification."

// ✅ GOOD - Extensible via props
interface ButtonProps {
  variant?: "primary" | "secondary" | "outline";
  size?: "sm" | "md" | "lg";
  icon?: React.ReactNode;
  onClick?: () => void;
}

// Can extend with new variants without modifying core
<Button variant="primary" icon={<PlusIcon />}>
  Create Event
</Button>

L - Liskov Substitution Principle

"Derived types must be substitutable for their base types."

// ✅ GOOD - All input types work the same
interface InputProps {
  type: "text" | "email" | "password";
  value: string;
  onChange: (value: string) => void;
}

// Any Input can be swapped without breaking the form
<Input type="text" value={name} onChange={setName} />
<Input type="email" value={email} onChange={setEmail} />

I - Interface Segregation

"Many specific interfaces > One general interface."

// ✅ GOOD - Specific interfaces
interface Clickable {
  onClick: () => void;
}

interface Hoverable {
  onHover: () => void;
}

interface Focusable {
  onFocus: () => void;
}

// Components only implement what they need
function Button({ onClick }: Clickable) {}
function Tooltip({ onHover }: Hoverable) {}

D - Dependency Inversion

"Depend on abstractions, not implementations."

// ✅ GOOD - Depends on abstract API client
interface ApiClient {
  get<T>(url: string): Promise<T>;
  post<T>(url: string, data: unknown): Promise<T>;
}

function useEvents(client: ApiClient) {
  return client.get<Event[]>('/events');
}

// Can swap implementations (fetch, axios, mock)

🎯 Checklist

• Components accept props for extension
• Interfaces are small and focused
• Dependencies are injected (via props or context)
• Components depend on interfaces, not concrete implementations

---

🔒 7. Defensive Programming

"Validate everything. Trust nothing."

✅ Implementation

// ✅ GOOD - Validate all inputs
import { z } from 'zod';

const EventInputSchema = z.object({
  name: z.string().min(1).max(100),
  date: z.string().datetime(),
  attendees: z.number().int().min(1).max(10000),
});

export async function createEvent(input: unknown) {
  // Validate before using
  const data = EventInputSchema.parse(input);

  // Handle errors
  try {
    return await db.event.create({ data });
  } catch (error) {
    if (error instanceof DatabaseError) {
      throw new EventCreationError('Failed to save event');
    }
    throw error;
  }
}

🎯 Checklist

• All user input validated with Zod
• All API responses validated
• All null/undefined cases handled
• Error boundaries in place
• Fallback UI for failures
• No unhandled promise rejections

---

🧮 8. Composition over Inheritance

"Compose small pieces > Deep hierarchies."

✅ React Composition

// ✅ GOOD - Composition
function Card({ children }: { children: React.ReactNode }) {
  return <div className="card-sherehe">{children}</div>;
}

function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="p-4 border-b">{children}</div>;
}

function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="p-4">{children}</div>;
}

// Compose them
<Card>
  <CardHeader>
    <h2>Event Details</h2>
  </CardHeader>
  <CardBody>
    <EventInfo event={event} />
  </CardBody>
</Card>

🎯 Checklist

• Prefer composition (children, slots) over inheritance
• Use React context for shared state, not prop drilling
• Combine small components into larger ones
• Avoid deep component hierarchies (max 3-4 levels)

---

🔬 9. Testability

"If it's hard to test, it's badly designed."

✅ Testable Code

// ✅ GOOD - Pure function, easy to test
export function calculateEventPrice(
  basePrice: number,
  attendees: number,
  discount: number
): number {
  return basePrice * attendees * (1 - discount);
}

// Test:
expect(calculateEventPrice(100, 10, 0.1)).toBe(900);

// ✅ GOOD - Component with clear inputs/outputs
export function EventCard({ event, onSelect }: EventCardProps) {
  return (
    <div onClick={() => onSelect(event.id)}>
      <h3>{event.name}</h3>
    </div>
  );
}

// Test: Render with mock data, verify onClick

🎯 Checklist

• Functions are pure (no side effects)
• Components receive all dependencies as props
• No direct DOM manipulation
• No hardcoded values
• Side effects isolated in hooks/API layer

---

🔧 10. Automation

"Automate everything repeated."

✅ SHEREHE Automation

// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "type-check": "tsc --noEmit",
    "format": "prettier --write .",
    "test": "jest",
    "test:watch": "jest --watch",
    "pre-commit": "lint-staged",
    "prepare": "husky install"
  }
}

🎯 Checklist

• Linting automated (ESLint)
• Type checking automated (TypeScript)
• Formatting automated (Prettier)
• Testing automated (Jest/Vitest)
• Builds automated (CI/CD)
• Pre-commit hooks set up (Husky + lint-staged)

---

🧭 11. Documentation as a Feature

"Document the 'why', not the 'what'."

✅ Good Documentation

/**
 * Calculates the total event cost including all fees and taxes.
 *
 * @param basePrice - Base price per attendee in RWF
 * @param attendees - Number of expected attendees
 * @param serviceType - Type of service (determines fee structure)
 * @returns Total cost in RWF
 *
 * @example
 * calculateTotalCost(50000, 100, "premium")
 * // Returns 5500000 (base + 10% premium fee)
 *
 * @remarks
 * Premium services include venue decoration and catering.
 * Standard services are venue rental only.
 * Fee structures are defined in PRICING.md
 */
export function calculateTotalCost(
  basePrice: number,
  attendees: number,
  serviceType: ServiceType
): number {
  // Implementation
}

🎯 Checklist

• Complex functions have JSDoc comments
• Public APIs documented
• README.md exists and is current
• Architecture decisions documented (ADRs)
• SHEREHE design system documented
• Comments explain "why", not "what"

---

🔮 12. Performance as a Feature

"Fast code is good code."

✅ Next.js/React Performance

// ✅ Server Component - No JS to client
export default async function EventsPage() {
  const events = await fetchEvents();
  return <EventsList events={events} />;
}

// ✅ Memoization for expensive calculations
const sortedEvents = useMemo(
  () => events.sort((a, b) => a.date.getTime() - b.date.getTime()),
  [events]
);

// ✅ Dynamic imports for heavy components
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <Skeleton />,
  ssr: false
});

// ✅ Image optimization
<Image
  src={event.image}
  alt={event.name}
  width={800}
  height={600}
  priority={isAboveFold}
/>

🎯 Checklist

• Server Components by default
• Client Components only when needed
• Images optimized with next/image
• Heavy components lazy-loaded
• Bundle size monitored
• No unnecessary re-renders

---

🎯 Review Process

When activated, follow this process:

1. Identify Scope

   • Which files/features to review?
   • What's the architectural question?

2. Read & Analyze

   • CHECK FILE LINE COUNTS FIRST (count lines in all files)
   • Read relevant files
   • Map out component structure
   • Identify data flow

3. Check Principles (in priority order)

   • 🚨 CARDINAL RULE: Is any file > 500 lines? (INSTANT REJECTION)
   • 🚨 WARNING ZONE: Is any file > 450 lines? (Flag for splitting)
   • Abstraction: Is complexity hidden?
   • Modularity: Are components small and focused?
   • Reusability: Is logic duplicated?
   • SRP: Does each component do one thing?
   • Separation: Are concerns separated?
   • KISS: Is it simple?
   • YAGNI: Is there over-engineering?

4. Provide Recommendations

   • If 500-line violations: STOP and require split FIRST
   • List violations with examples
   • Suggest refactorings
   • Show before/after code
   • Provide line count for each file
   • Prioritize by impact (500-line violations = CRITICAL)

---

📋 Example Review Output

## Architecture Review Results

### Files Reviewed (with line counts)

- app/events/page.tsx (324 lines) ✅
- components/features/events/EventCard.tsx (120 lines) ✅
- app/early-access/early-access-client.tsx (265 lines) ✅
- lib/api/events.ts (89 lines) ✅

### 🚨 500-Line Limit Check

- ✅ All files under 500-line limit
- ⚠️ No files in warning zone (450-500 lines)
- ✅ PASS

### ✅ Strengths

1. **File Size Compliance** - All files well under 500-line limit
2. **Separation of Concerns** - Server/Client split is clean
3. **SHEREHE Brand Compliance** - All colors use design system
4. **TypeScript Safety** - No `any` types

### ⚠️ Issues Found

#### 🔴 CRITICAL: Violation of DRY Principle

**File**: `components/features/events/EventCard.tsx:45`
**Issue**: Duplicate date formatting logic

**Current Code**:

```typescript
const formatted = new Date(event.date).toLocaleDateString();
```

Found in: 5 different components

Recommendation: Extract to utility

// lib/utils/format.ts
export function formatEventDate(date: Date): string {
  return new Intl.DateTimeFormat('en-RW', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  }).format(date);
}

🟡 MEDIUM: SRP Violation

File: app/events/page.tsx:20-150 Issue: Component is 130 lines, doing too much

Recommendation: Split into:

• EventsPage (server, data fetching)
• EventsClient (client, interactions)
• EventFilters (filtering logic)
• EventGrid (rendering)

Summary

• Total issues: 8
• Critical: 2 (DRY, Modularity)
• High: 3 (SRP, Abstraction)
• Medium: 3 (KISS)

Recommendation

⚠️ NEEDS REFACTORING - Address critical issues before production

---

### Example 2: 500-Line Violation (Instant Rejection)

```markdown
## Architecture Review Results

### Files Reviewed (with line counts)
- app/dashboard/page.tsx (687 lines) ❌ VIOLATION
- components/UserDashboard.tsx (523 lines) ❌ VIOLATION
- hooks/use-dashboard-data.ts (456 lines) ⚠️ WARNING ZONE
- lib/api/dashboard.ts (342 lines) ✅

### 🚨 500-Line Limit Check

❌ **CRITICAL VIOLATIONS FOUND**

#### ❌ VIOLATION #1: app/dashboard/page.tsx
- **Current**: 687 lines
- **Limit**: 500 lines
- **Overage**: 187 lines (37% over limit)
- **Status**: 🚨 **INSTANT REJECTION**

**Required Action**: MUST split before proceeding
**Suggested Split**:

app/dashboard/ ├── page.tsx (180 lines) - Server component ├── dashboard-client.tsx (220 lines) - Client wrapper ├── components/ │ ├── DashboardHeader.tsx (120 lines) │ ├── DashboardStats.tsx (150 lines) │ ├── RecentActivity.tsx (180 lines) │ └── QuickActions.tsx (100 lines) └── hooks/ └── use-dashboard.ts (200 lines)

#### ❌ VIOLATION #2: components/UserDashboard.tsx
- **Current**: 523 lines
- **Limit**: 500 lines
- **Overage**: 23 lines (5% over limit)
- **Status**: 🚨 **INSTANT REJECTION**

**Required Action**: Extract 50+ lines minimum
**Suggested Fix**:
- Extract profile section → UserProfile.tsx (150 lines)
- Extract settings panel → UserSettings.tsx (120 lines)
- Keep main layout → UserDashboard.tsx (250 lines)

#### ⚠️ WARNING: hooks/use-dashboard-data.ts
- **Current**: 456 lines
- **Limit**: 500 lines
- **Remaining**: 44 lines
- **Status**: ⚠️ **WARNING ZONE (450-500)**

**Recommendation**: Split NOW before reaching limit
**Suggested Split**:
- use-dashboard-stats.ts (180 lines)
- use-dashboard-activities.ts (150 lines)
- use-dashboard-actions.ts (120 lines)

### 🛑 REVIEW STOPPED

**Cannot proceed with architectural review while 500-line violations exist.**

This code is **NOT PRODUCTION READY** and must be refactored before:
- Further development
- Code review
- Testing
- Deployment

### Required Next Steps

1. **IMMEDIATELY**: Stop all feature development
2. **FIRST**: Split violating files (app/dashboard/page.tsx, UserDashboard.tsx)
3. **SECOND**: Split warning-zone files (use-dashboard-data.ts)
4. **THIRD**: Request new review after refactoring
5. **ONLY THEN**: Continue with feature development

### Final Verdict

❌ **REJECTED - 500-Line Violations**

**Files must be split before any other work proceeds.**

---

🎓 Remember

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler

These principles aren't rules to follow blindly. They're tools to help you write:

• Maintainable code (future you will thank you)
• Testable code (confidence in changes)
• Scalable code (grows with the product)
• Readable code (team can contribute)

The Non-Negotiables

1. 500 lines max - HARD LIMIT, no exceptions
2. No any or unknown - TypeScript strict mode
3. SHEREHE brand - Use design system
4. Test first - If it's hard to test, redesign it

When in Doubt

• Keep it simple - KISS over clever
• Keep it modular - Split early, split often
• Keep it reusable - DRY principles
• Keep it under 500 lines - Always check line count

---

⚡ Automatic Enforcement

This skill activates automatically when writing code. You don't need to ask.

Every time you write a component, hook, or utility:

1. Check line count FIRST
2. Apply principles as you code
3. Validate before completion
4. Reject if 500-line limit violated

The 500-line rule is not optional. It's fundamental to writing maintainable software.