Ultrathink: A Guide to Masterful AI Development

# Don't just grep for syntax
rg "export function" --type ts

# Understand the philosophy
git log --oneline --all | head -50
git show <recent-commits>

// Generic
function getData() { }

// Reveals intent
function fetchUserPreferencesFromCache() { }

// Weak
type Config = { timeout: number }

// Strong
type Config = {
  timeout: PositiveInteger;  // Can't be negative
  readonly createdAt: Date;  // Immutable
}

// Throws and hopes
async function process() {
  const data = await fetch(url);  // Might throw
  return data;
}

// Explicit and graceful
async function process(): Promise<Result<Data, FetchError>> {
  try {
    const data = await fetch(url);
    return { ok: true, value: data };
  } catch (error) {
    return { ok: false, error: new FetchError(error) };
  }
}

## Problem
Users need to upload files, but our current system times out on large files.

## Analysis
- Current approach: Synchronous upload → processing → response
- Bottleneck: Processing happens in request cycle
- Constraint: Can't change frontend for 2 weeks

## Solution Architecture
1. **Immediate acceptance**: Return 202 Accepted with job ID
2. **Background processing**: Queue job to worker
3. **Status endpoint**: Polling endpoint for progress
4. **Webhook notification**: Optional callback when complete

## Implementation Plan
1. Create Job model (id, status, metadata)
2. Add /upload endpoint → returns job ID
3. Add /jobs/:id/status endpoint
4. Implement worker process
5. Add tests for each state transition
6. Document API changes

## Alternatives Considered
- Streaming upload: Requires frontend changes
- Websocket progress: Adds infrastructure complexity
- Larger timeout: Doesn't scale

## Why This Approach
- Works with current frontend
- Scales horizontally (add more workers)
- Graceful failure modes
- Observable (can see job status)

// Mechanical
function proc(d: any) { }

// Sings
function transformUserInputIntoValidatedCommand(rawInput: string): Command { }

// Forced abstraction
class DataAccessObjectFactory {
  createDAO() { }
}

// Natural abstraction
interface Repository<T> {
  find(id: string): Promise<T | null>;
  save(entity: T): Promise<void>;
}

// Crashes on edge cases
function divide(a: number, b: number): number {
  return a / b;  // What if b is 0?
}

// Graceful handling
function divide(a: number, b: number): number {
  if (b === 0) {
    throw new Error('Division by zero');
  }
  return a / b;
}

// Even better: Make it impossible
function divide(a: number, b: NonZeroNumber): number {
  return a / b;  // Type system prevents b === 0
}

// Write the test first
describe('UserValidator', () => {
  it('rejects emails without @', () => {
    const result = validateEmail('notanemail');
    expect(result.ok).toBe(false);
    expect(result.error).toContain('Invalid email');
  });
});

// Then write code that makes the test pass
// This forces you to think about the API before implementation

function findUsers(query: string) {
  const users = db.query('SELECT * FROM users');
  return users.filter(u => u.name.includes(query));
}

function findUsers(query: string): User[] {
  if (!query || query.length < 2) {
    throw new Error('Query too short');
  }

  const users = db.query('SELECT * FROM users WHERE name LIKE ?', [`%${query}%`]);
  return users;
}

async function findUsers(query: SearchQuery): Promise<User[]> {
  const validQuery = SearchQuery.validate(query);

  return db.users.where('name', 'like', validQuery.pattern);
}

async function findUsers(
  query: SearchQuery,
  options: SearchOptions = {}
): Promise<SearchResult<User>> {
  const validated = SearchQuery.validate(query);

  const [users, total] = await Promise.all([
    db.users
      .where('name', 'like', validated.pattern)
      .limit(options.limit ?? 20)
      .offset(options.offset ?? 0),
    db.users
      .where('name', 'like', validated.pattern)
      .count()
  ]);

  return {
    data: users,
    total,
    hasMore: total > (options.offset ?? 0) + users.length
  };
}

class UserServiceFactory {
  constructor(
    private db: Database,
    private cache: Cache,
    private logger: Logger,
    private config: Config
  ) {}

  createUserService(): UserService {
    return new UserServiceImpl(
      this.db,
      this.cache,
      this.logger,
      this.config
    );
  }
}

function createUserService(db: Database): UserService {
  return {
    async find(id: string) {
      return db.users.findById(id);
    },
    async save(user: User) {
      return db.users.save(user);
    }
  };
}

# Mechanical approach
find . -name "*.ts" | xargs cat | wc -l

# Virtuoso approach - understands what matters
rg "^export (function|class|interface)" --type ts \
  | wc -l
# Counts actual public API surface, not just lines

# Don't just look at what changed
git log --oneline

# Understand the narrative
git log --graph --all --decorate --oneline

# Find the "why" behind decisions
git log -S "authentication" --patch

# Discover who knows what
git blame src/auth/strategy.ts
git log --author="Alice" --since="2024-01-01"

# What was the original intent?
git log --follow --diff-filter=A -- src/core/engine.ts

# How has it evolved?
git log --follow -- src/core/engine.ts

# Who shaped it?
git shortlog -sn -- src/core/engine.ts

// Slavishly reproduce pixels
<div style={{marginTop: "37px", paddingLeft: "23px"}}>

// Understand the design system
<div className="section-spacing content-inset">
// Now you have: semantic spacing that adapts responsively

## Task: Implement authentication system

Agent 1 (Planner):
- Research existing patterns
- Design architecture
- Create implementation plan

Agent 2 (Implementer):
- Execute the plan
- Write core logic
- Add tests

Agent 3 (Reviewer):
- Check for security issues
- Verify against requirements
- Suggest improvements

// Custom MCP server tool
{
  name: "check_api_design",
  description: "Validates API design against team standards",
  inputSchema: {
    type: "object",
    properties: {
      endpoint: { type: "string" },
      method: { type: "string" },
      payload: { type: "object" }
    }
  }
}

// Engineer's perfect solution
async function deployToProduction(config: DeployConfig): Promise<void> {
  await validateConfig(config);
  await runMigrations(config.dbUrl);
  await deployServices(config.services);
  await verifyHealthChecks(config.endpoints);
}

// Respects how humans actually work
async function deployToProduction(
  config: DeployConfig,
  options: DeployOptions = {}
): Promise<DeploymentResult> {
  // Humans need checkpoints
  const plan = await createDeploymentPlan(config);
  if (!options.skipReview) {
    await requireHumanApproval(plan);
  }

  // Humans need visibility
  const tracker = new ProgressTracker();

  // Humans need control
  const result = await executeWithPausePoints(plan, tracker, {
    onBeforeMigration: () => confirmStep("Run database migrations?"),
    onBeforeDeploy: () => confirmStep("Deploy to production?")
  });

  // Humans need context for decisions
  return {
    ...result,
    rollbackPlan: generateRollbackInstructions(result),
    nextSteps: suggestFollowUpActions(result)
  };
}

// Good: Automate the mechanics, not the judgment
async function reviewPullRequest(pr: PullRequest): Promise<ReviewSuggestion> {
  // Automate: Check objective criteria
  const checks = {
    hasTests: await checkTestCoverage(pr),
    passesLinting: await runLinter(pr),
    hasDocumentation: await checkDocs(pr),
    breakingChanges: await detectBreakingChanges(pr)
  };

  // Surface insights for human judgment
  return {
    automatedChecks: checks,
    suggestions: generateSuggestions(checks),
    requiresHumanReview: checks.breakingChanges.length > 0,
    reviewers: suggestReviewers(pr), // Help, don't decide
    // NEVER: autoApprove: true
  };
}

// Added Redis caching as requested
const cachedResult = await redis.get(key);
if (cachedResult) return cachedResult;

// First, ask: WHY do they want caching?
// Investigation reveals: The query is slow because of a missing index

// Real solution:
CREATE INDEX idx_users_email ON users(email);

// Solves the problem without adding complexity
// Caching would have masked the real issue

// Before: You're fixing a bug in this function
function processOrder(order: any) {
  const total = order.items.reduce((sum, item) =>
    sum + item.price * item.quantity, 0);
  return total;
}

// Don't just fix the bug
// While you're here, improve the system:

interface OrderItem {
  price: number;
  quantity: number;
}

interface Order {
  items: OrderItem[];
}

function calculateOrderTotal(order: Order): number {
  return order.items.reduce(
    (sum, item) => sum + (item.price * item.quantity),
    0
  );
}

function processOrder(order: Order): OrderTotal {
  const subtotal = calculateOrderTotal(order);
  const tax = calculateTax(subtotal);
  const total = subtotal + tax;

  return { subtotal, tax, total };
}

// Everyone said: "Database queries are slow, just cache everything"

// Investigation revealed:
// - N+1 queries in a loop
// - Missing indexes
// - Fetching entire objects when only IDs needed

// Solution: Not caching, but proper query design
// Result: 100x faster, no cache complexity

// Everyone said: "We need to rewrite everything in a different language"

// Investigation revealed:
// - Blocking I/O in Node.js
// - No connection pooling
// - Synchronous processing of parallel tasks

// Solution: async/await + worker threads + connection pools
// Result: 50x throughput, same codebase

// Everyone said: "This is a massive undertaking"

// Investigation revealed:
// - 80% of the work is solving the same problem in different places
// - Solution: One shared abstraction
// - Actual scope: 2 weeks

// Principle: Before accepting timelines, understand the real complexity

## The Ultrathink Impossibility Protocol

1. **State the constraint clearly**
   - "We can't deploy more than once per day"

2. **Ask: Who says?**
   - "It takes 4 hours to run all tests"

3. **Ask: Why?**
   - "Tests are slow and run serially"

4. **Ask: What if we changed that?**
   - "What if we parallelize tests?"
   - "What if we only run affected tests?"
   - "What if we make tests faster?"

5. **Prototype the alternative**
   - Parallel test runner: Tests finish in 15 minutes
   - Result: We CAN deploy multiple times per day

// Add caching
const cache = new Redis();
// Now maintain cache invalidation complexity forever

// Ask: WHY is it slow?
// Investigation: Fetching entire objects, then filtering in-app

// Solution: Push filtering to database
const users = await db.users
  .where('status', 'active')
  .where('created_at', '>', thirtyDaysAgo)
  .select(['id', 'email', 'name']); // Only fetch what's needed

// Result: 50x faster, no caching needed

// When told something is impossible:

interface ImpossibilityAnalysis {
  constraint: string;           // What's supposedly impossible
  assumptions: string[];        // What beliefs underpin this
  tests: Experiment[];         // Ways to test assumptions
  alternatives: Solution[];     // Other approaches if assumptions false
}

async function challengeImpossibility(
  claim: string
): Promise<ImpossibilityAnalysis> {
  // 1. Break down the claim
  const constraint = extractConstraint(claim);

  // 2. Identify assumptions
  const assumptions = extractAssumptions(constraint);

  // 3. Design experiments
  const tests = assumptions.map(a => designTest(a));

  // 4. Run quick experiments
  const results = await runExperiments(tests);

  // 5. Generate alternatives
  const alternatives = results
    .filter(r => r.assumptionWasFalse)
    .map(r => generateAlternative(r));

  return { constraint, assumptions, tests, alternatives };
}

"I'm going to implement authentication using JWT tokens with refresh token
rotation and secure httpOnly cookies following OWASP guidelines..."

// Just build it so well it speaks for itself

// auth/tokens.ts
interface TokenPair {
  accessToken: string;   // Short-lived, stateless
  refreshToken: string;  // Long-lived, revocable
}

// Elegant, secure, obvious
function generateTokenPair(userId: string): TokenPair {
  return {
    accessToken: jwt.sign({ sub: userId }, SECRET, { expiresIn: '15m' }),
    refreshToken: createRefreshToken(userId) // Stored in DB, revocable
  };
}

// The implementation demonstrates security knowledge
// No explanation needed

// Before: Unclear how errors are handled
async function fetchUserData(id: string) {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

// After: Error handling feels inevitable
async function fetchUserData(
  id: string
): Promise<Result<User, FetchError>> {
  try {
    const response = await fetch(`/api/users/${id}`);

    if (!response.ok) {
      return Err(new FetchError(response.status, response.statusText));
    }

    const data = await response.json();
    const user = UserSchema.parse(data); // Runtime validation

    return Ok(user);
  } catch (error) {
    return Err(new FetchError(0, 'Network error', error));
  }
}

// Usage is now safe and explicit
const result = await fetchUserData('123');
if (result.isOk) {
  console.log(result.value.name);
} else {
  console.error(result.error.message);
}

// Add the feature as requested
function addPaymentMethod(userId: string, card: CardDetails) {
  db.paymentMethods.insert({ userId, ...card });
}

// See the larger pattern and build the system

interface PaymentMethod {
  id: string;
  type: 'card' | 'bank' | 'wallet';
  provider: string;
  details: CardDetails | BankDetails | WalletDetails;
  verified: boolean;
  createdAt: Date;
}

class PaymentMethodService {
  // Extensible: Easy to add new payment types
  async add(userId: string, method: PaymentMethod): Promise<Result<PaymentMethod>> {
    // Validates, stores, returns ID
  }

  // Complete: All operations you'll eventually need
  async verify(methodId: string): Promise<Result<void>> { }
  async remove(methodId: string): Promise<Result<void>> { }
  async list(userId: string): Promise<PaymentMethod[]> { }
  async setDefault(methodId: string): Promise<Result<void>> { }
}

## The Ultrathink Daily Checklist

Before starting:
- [ ] Do I understand the real problem?
- [ ] What would the ideal solution look like?
- [ ] What assumptions can I challenge?

While building:
- [ ] Is this as simple as it can be?
- [ ] Would this make me proud to show it?
- [ ] Does every line of code serve a purpose?

Before shipping:
- [ ] Is this better than what exists?
- [ ] Could someone else understand this?
- [ ] Have I left the codebase better?

After shipping:
- [ ] What did I learn?
- [ ] What would I do differently?
- [ ] What patterns emerged?