flowchart TB
    subgraph code ["docs/rules/code/"]
        G["general/"]
        TS["typescript/"]
        N["naming/"]
        E["errors/"]
        A["async/"]

        subgraph front ["front/"]
            FC["components/"]
            FS["state/"]
            FST["styling/"]
        end

        subgraph back ["back/"]
            BA["api/"]
            BD["database/"]
            BS["services/"]
        end
    end

    G --> TS
    G --> N
    G --> E
    G --> A

docs/rules/code/
├── general/                        # Cross-cutting rules
│   ├── rule.md
│   ├── examples.md
│   ├── .version
│   └── .enforced_by
│
├── typescript/                     # TypeScript-specific
│   ├── strict_mode/
│   ├── type_assertions/
│   ├── generics/
│   └── unions/
│
├── naming/                         # Naming conventions
│   ├── files/
│   ├── variables/
│   ├── functions/
│   ├── types/
│   └── constants/
│
├── errors/                         # Error handling
│   ├── catching/
│   ├── throwing/
│   └── logging/
│
├── async/                          # Async patterns
│   ├── promises/
│   └── error_handling/
│
├── imports/                        # Import organization
│   ├── ordering/
│   └── barrel_files/
│
├── front/                          # Frontend-specific
│   ├── components/
│   ├── state/
│   ├── hooks/
│   └── styling/
│
└── back/                           # Backend-specific
    ├── api/
    ├── database/
    └── services/

docs/rules/code/general/
├── rule.md
├── examples.md
├── .version
└── .enforced_by

# Rule: General Coding Standards

## Summary

All code MUST follow these fundamental standards for consistency and maintainability.

## Rationale

Consistent code is easier to read, review, maintain, and debug.

## The Rules

### 1. Single Responsibility

Each function, class, or module MUST have one clear purpose.

- Functions SHOULD be under 30 lines
- Files SHOULD be under 300 lines

### 2. Explicit Over Implicit

- **MUST NOT** rely on implicit type coercion
- **MUST** use explicit return statements
- **MUST** use explicit comparisons (`===` not `==`)

### 3. Fail Fast

- **MUST** validate function parameters at entry
- **MUST** throw on invalid input (not return null)

### 4. No Magic Values

- **MUST** extract magic numbers to named constants
- **MUST** extract magic strings to constants or enums

### 5. Immutability Preference

- **SHOULD** use `const` over `let`
- **MUST NOT** use `var`
- **SHOULD** prefer spread over mutation

## Examples

### Correct

```typescript
// Named constants
const MAX_RETRY_ATTEMPTS = 3;
const CACHE_TTL_MS = 60 * 1000;

// Explicit comparisons
if (user.role === 'admin') { ... }

// Immutable update
const updatedUser = { ...user, lastLogin: new Date() };
```

// Magic values
setTimeout(callback, 86400000);  // What is this?

// Implicit coercion
if (user.role == 'admin') { ... }  // Use ===

// Mutation
user.lastLogin = new Date();  // Mutates original

### .enforced_by

---

## Example: docs/rules/code/naming/files/

File naming conventions.

### rule.md

```markdown
# Rule: File Naming Conventions

## Summary

All source files MUST follow consistent naming patterns based on content type.

## The Rules

| Type | Pattern | Example |
|------|---------|---------|
| React Component | `PascalCase.tsx` | `CreatureCard.tsx` |
| React Hook | `use-{name}.ts` | `use-creature-data.ts` |
| Service | `{name}-service.ts` | `auth-service.ts` |
| Utility | `{name}.ts` | `string-utils.ts` |
| Types | `{name}.types.ts` | `creature.types.ts` |
| Test | `{name}.test.ts` | `auth-service.test.ts` |
| Index/Barrel | `index.ts` | `index.ts` |

### Directory Names

- **MUST** use kebab-case for directories
- **SHOULD** match domain concept (plural for collections)

## Examples

### Correct

### Incorrect

## Enforcement

- ESLint file naming plugin
- Pre-commit hook

# Rule: Error Catching

## Summary

All caught errors MUST be properly typed, logged, and handled - never silently swallowed.

## The Rules

### 1. Never Catch and Ignore

**MUST NOT** have empty catch blocks.

### 2. Type Caught Errors

**MUST** type errors as `unknown` and narrow appropriately.

```typescript
try {
  await fetchData();
} catch (error: unknown) {
  if (error instanceof NetworkError) {
    handleNetworkError(error);
  } else if (error instanceof Error) {
    handleGenericError(error);
  }
}
```

async function fetchUser(id: string): Promise<User> {
  try {
    return await api.get(`/users/${id}`);
  } catch (error: unknown) {
    if (isNotFoundError(error)) {
      throw new UserNotFoundError(id);
    }
    logger.error("Unexpected error", { id, error });
    throw error;
  }
}

// Silent swallow - FORBIDDEN
try {
  await saveAnalytics(event);
} catch (e) {}

// Untyped error access
try {
  await fetchData();
} catch (e) {
  console.log(e.message); // e is unknown!
}

---

## Example: docs/rules/code/async/promises/

Async/await patterns.

### rule.md

```markdown
# Rule: Promise Handling

## Summary

All Promises MUST be properly awaited or have rejections handled.

## The Rules

### 1. Always Await or Handle

```typescript
// CORRECT - awaited
const data = await fetchData();

// CORRECT - fire-and-forget with handler
sendAnalytics(event).catch(logError);

// FORBIDDEN - floating promise
fetchData();  // No await, no handler

// CORRECT - parallel
const [users, posts] = await Promise.all([fetchUsers(), fetchPosts()]);

// INEFFICIENT - sequential
const users = await fetchUsers();
const posts = await fetchPosts();

// CORRECT - factory function
class Service {
  private constructor(private data: Data) {}

  static async create(): Promise<Service> {
    const data = await loadData();
    return new Service(data);
  }
}

---

## Creating New Code Rules

```mermaid
flowchart TD
    A[Identify Pattern] --> B{Category}
    B -->|Types| C[typescript/]
    B -->|Names| D[naming/]
    B -->|Errors| E[errors/]
    B -->|Async| F[async/]
    B -->|General| G[general/]
    B -->|Frontend| H[front/]
    B -->|Backend| I[back/]

    C --> J[Create Rule Folder]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J

    J --> K[Write rule.md]
    K --> L[Add examples.md]
    L --> M[Configure Enforcement]
    M --> N{Automated?}

    N -->|ESLint| O[Add ESLint Rule]
    N -->|TypeScript| P[Add tsconfig Option]
    N -->|Manual| Q[Add to Review Checklist]

    O --> R[Update CI]
    P --> R
    Q --> S[Announce]
    R --> S