□ ENGAGEMENT
  □ Does the core loop feel satisfying?
  □ Is there clear moment-to-moment feedback?
  □ Do players want "one more turn"?

□ CLARITY
  □ Do players understand what to do?
  □ Are goals and progress visible?
  □ Is the UI intuitive without tutorial?

□ PROGRESSION
  □ Does difficulty ramp appropriately?
  □ Are rewards meaningful and well-paced?
  □ Is there a sense of mastery over time?

□ JUICE
  □ Do interactions feel responsive?
  □ Are wins celebrated appropriately?
  □ Does the game have "weight" and polish?

□ FAIRNESS
  □ Do losses feel fair (not random/cheap)?
  □ Is RNG transparent to players?
  □ Are comeback mechanics present?

SESSION TEMPLATE (45-60 minutes)

1. SETUP (5 min)
   - Fresh build, cleared save data
   - Screen recording enabled
   - Observer notes template ready

2. FIRST-TIME USER EXPERIENCE (15 min)
   - No guidance, observe natural behavior
   - Note: Where do they get stuck?
   - Note: What do they try first?
   - Note: Facial expressions, body language

3. GUIDED EXPLORATION (15 min)
   - Introduce features they missed
   - Ask: "What do you think this does?"
   - Ask: "How did that feel?"

4. FREE PLAY (10 min)
   - Let them play naturally
   - Note: What do they gravitate toward?
   - Note: What do they avoid?

5. DEBRIEF (10 min)
   - "What was most fun?"
   - "What was frustrating?"
   - "Would you play again? Why?"
   - "Rate 1-10: How fun was this?"

// .eslintrc.json for the project
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react-hooks/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "react-hooks/exhaustive-deps": "error",
    "no-console": ["warn", { "allow": ["warn", "error"] }],
    "complexity": ["warn", 10],
    "max-lines-per-function": ["warn", 50]
  }
}

// biome.json alternative
{
  "linter": {
    "rules": {
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": { "maxAllowedComplexity": 15 }
        }
      },
      "correctness": {
        "useExhaustiveDependencies": "error"
      }
    }
  }
}

undefined

undefined

RED FLAGS:
- Function > 50 lines
- File > 300 lines
- Cyclomatic complexity > 10
- More than 3 levels of nesting
- Repeated code blocks
- "Utils" file growing unbounded
- Props drilling > 3 levels
- useEffect with 5+ dependencies

1. Ensure tests exist (write them first if not)
2. Make ONE change at a time
3. Run tests after each change
4. Commit working states frequently
5. Review diff before finalizing

        ╱╲
       ╱  ╲        E2E Tests (Playwright)
      ╱ 10%╲       - Full user flows
     ╱──────╲      - Critical paths only
    ╱        ╲
   ╱   20%    ╲    Integration Tests
  ╱────────────╲   - Component interactions
 ╱              ╲  - Store + UI together
╱      70%       ╲ Unit Tests (Vitest)
╲────────────────╱ - Pure functions
                   - Game logic
                   - Utilities

// Game logic tests
import { describe, it, expect } from 'vitest';
import { calculateBet, hexDistance, spreadTrouble } from './game-engine';

describe('calculateBet', () => {
  it('returns 0 for fold', () => {
    expect(calculateBet(1000, 'fold')).toBe(0);
  });

  it('returns 10% of coins for call', () => {
    expect(calculateBet(1000, 'call')).toBe(100);
  });

  it('returns all coins for all_in', () => {
    expect(calculateBet(1000, 'all_in')).toBe(1000);
  });

  it('floors fractional amounts', () => {
    expect(calculateBet(1005, 'call')).toBe(100);
  });
});

describe('hexDistance', () => {
  it('returns 0 for same hex', () => {
    const hex = { q: 0, r: 0, s: 0 };
    expect(hexDistance(hex, hex)).toBe(0);
  });

  it('calculates adjacent hex distance as 1', () => {
    const a = { q: 0, r: 0, s: 0 };
    const b = { q: 1, r: -1, s: 0 };
    expect(hexDistance(a, b)).toBe(1);
  });
});

// Component tests with Testing Library
import { render, screen, fireEvent } from '@testing-library/react';
import { ResourceBar } from './ResourceBar';

describe('ResourceBar', () => {
  it('displays the resource value', () => {
    render(<ResourceBar value={500} label="Coins" icon="🪙" />);
    expect(screen.getByText('500')).toBeInTheDocument();
  });

  it('animates on value change', async () => {
    const { rerender } = render(<ResourceBar value={500} label="Coins" />);
    rerender(<ResourceBar value={600} label="Coins" />);
    
    // Check for delta indicator
    expect(screen.getByText('+100')).toBeInTheDocument();
  });
});

// Playwright e2e tests
import { test, expect } from '@playwright/test';

test.describe('Game Flow', () => {
  test('complete a full day cycle', async ({ page }) => {
    await page.goto('/game');
    
    // Verify initial state
    await expect(page.getByText('Day 1')).toBeVisible();
    await expect(page.getByText('Morning')).toBeVisible();
    
    // Advance through phases
    await page.getByRole('button', { name: /advance/i }).click();
    await expect(page.getByText('Action')).toBeVisible();
    
    // Place a bet
    await page.getByTestId('water-pot').click();
    await page.getByRole('button', { name: /call/i }).click();
    
    // Continue to resolution
    await page.getByRole('button', { name: /advance/i }).click();
    await expect(page.getByText('Resolution')).toBeVisible();
    
    // Verify score changed
    const score = await page.getByTestId('score').textContent();
    expect(parseInt(score || '0')).toBeGreaterThan(0);
  });

  test('hex interaction works', async ({ page }) => {
    await page.goto('/game');
    
    // Click a hex
    await page.getByTestId('hex-0-0').click();
    
    // Verify selection
    await expect(page.getByTestId('hex-0-0')).toHaveClass(/selected/);
  });
});

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined