Forem: Paul Keen

The AI Agent Onboarding Problem (The Real Version)

Paul Keen — Mon, 06 Oct 2025 09:34:28 +0000

So you asked about AI agents and onboarding, and honestly? We screwed this up for like three months before we figured it out.

Here's what was happening. Every time we'd spin up an agent - we were using a mix of Claude with function calling and some custom orchestration - we'd have to stuff the entire context into the system prompt. Our coding standards, the database schema, the API patterns, all of it.

And the context window? It was getting expensive. We're talking like 50k tokens just for setup on every single task. The math doesn't work when you're doing this 20 times a day.

What Actually Broke

The real problem wasn't that agents "forgot" - obviously they're stateless, right? The problem was we had no good way to inject relevant context without... um, without just dumping everything in every time.

We tried a few things that didn't work. First, we thought we'd just use the conversation history. Terrible idea. You hit token limits fast, and old context pollutes new tasks.

Then we tried maintaining state in Redis between calls. That was better but still required us to manually decide what context each agent needed. Every. Single. Time.

The Thing That Actually Worked

We ended up building a pretty simple RAG setup. Nothing fancy - just embedded our docs, standards, and past decisions into Pinecone. When an agent spins up, it queries for relevant context based on the task description.

So if the task is "add authentication to the user API," it pulls our auth patterns, our API structure docs, our error handling examples. Maybe 5-8k tokens of highly relevant stuff instead of 50k tokens of everything.

Cut our setup from like 30 minutes of me writing context to under a minute of automated retrieval. And our token costs dropped by 60% or something.

The Part That's Still Messy

The hard part is keeping those embedded docs current. When we change an architectural decision, we need to update the knowledge base. We automated some of it with git hooks, but honestly, it still requires discipline.

And debugging? Man, when an agent does something weird, you have to figure out what context it pulled and whether that was wrong or incomplete. We added logging for every retrieval, which helps, but it's not perfect.

Also, security was a thing. These agents are pulling from our internal docs. We had to be really careful about what goes in there. No credentials, no customer data, nothing sensitive. Just patterns and standards.

What I'd Do Different

If I started over, I'd probably use LangChain or LlamaIndex instead of rolling our own. We reinvented some wheels. But honestly, understanding how it works under the hood was valuable.

The other thing - and this is important - start with ONE agent doing ONE thing really well. We tried to solve it for five agents at once. Disaster. Get the onboarding flow right for one use case, then expand.

Oh, and write tests for your agent outputs. Seriously. We were validating manually for way too long.

The Bottom Line

AI agents are only fast if you're not bottlenecking them with manual context setup. You need automated, relevant context injection. RAG is probably your best bet unless you've got something better.

But yeah, it takes infrastructure work. Boring stuff. Documentation, embedding pipelines, retrieval logic, monitoring.

Most teams skip that and wonder why their agents aren't delivering.

Anyway, that's what we learned. Still iterating on it, but it's way better than where we started.

What are you running into with your agents?

AI Forces What Rails Teams Already Knew: Small Teams Ship Faster

Paul Keen — Thu, 02 Oct 2025 15:05:46 +0000

I found this discussion last week and it crystallized something that's been percolating in the industry for months. Not because it was novel—we've been running small, empowered teams at JetThoughts for 17 years - but because AI is finally forcing the broader tech industry to confront what we figured out early: bureaucratic overhead kills velocity more than any technical constraint.

The shift isn't really about AI writing code. It's about AI making the cost of organizational complexity impossible to ignore.

Work Smarter Finally Beats Work Harder

There's a pattern in tech where we throw people at problems. Team struggling? Hire more engineers. Communication breaking down? Add a layer of management. Code quality slipping? Create a QA department.

Each addition feels reasonable in isolation. But the aggregate cost compounds exponentially.

We've maintained a hard rule at JetThoughts: teams of 5-9 people. Not because we couldn't grow larger—we've been around long enough to scale if we wanted to. But because we observed something counterintuitive early on: a team of 6 experienced developers consistently outshipped teams of 15-20.

The math isn't about individual productivity. It's about coordination tax.

class Team
  def communication_overhead
    # Metcalfe's law applies to organizational complexity
    (members.count * (members.count - 1)) / 2
  end

  def effective_velocity
    total_capacity - communication_overhead - alignment_cost
  end
end

# 6 developers: 15 communication paths
# 20 developers: 190 communication paths

When AI amplifies individual developer output by 25-50%, that communication overhead becomes the dominant bottleneck. You can't coordinate 190 paths of communication 50% faster. But you can eliminate most of them by keeping teams small.

As we wrote in our analysis of effective dev teams: "A small team can be nimble and quick, but might lack the bandwidth for large projects. A large team has more resources, but can be slow and bureaucratic." What we've found is that the second constraint—bureaucracy—dominates at almost any meaningful project scale.

The Silo Problem AI Exposes

Here's what the YouTube discussion gets right: AI doesn't just make developers faster—it makes organizational inefficiency visible in cycle time metrics.

Traditional org structure creates information silos as a side effect of scale. Backend team doesn't know what frontend needs. Product doesn't understand technical constraints. Engineering Manager becomes a translation layer between teams and leadership.

Each silo requires synchronization points. Each synchronization point requires meetings, alignment discussions, status updates. The work-to-coordination ratio inverts.

We eliminated most of this through radical transparency. Not as an aspirational value, but as hard process—what we call our communication architecture:

# At JetThoughts, this pattern is enforced
class Communication
  validates :channel, inclusion: { in: ['public'] }

  def share
    # Private discussions are actively discouraged
    # If they happen, summary must be posted publicly
    post_to_public_channel if private_discussion_occurred?
  end
end

Our rule: all team communication happens in public project channels. No DMs about project decisions. No hallway conversations that change direction. If it's important enough to discuss, it's important enough to document publicly.

This isn't about surveillance. It's about removing the need for synchronization meetings. When context is public by default, developers can pull information as needed rather than waiting for it to be pushed through status updates.

AI makes this pattern more critical because it speeds up execution but can't speed up alignment. The gap between "how fast we could ship if we knew what to build" and "how fast we actually ship" is almost entirely organizational overhead.

Reducing Tolerance for Inexperience Through Process

The video discussion touches on something we've observed: effective practices aren't complicated, but they're often skipped because "experienced developers know what they're doing."

That's backwards. Experienced developers follow process because they've seen what happens when you don't.

Our delivery flow isn't flexible or creative. It's deliberately constrained:

class DeveloperWorkflow
  MAX_WIP_PER_DEVELOPER = 1  # In Progress
  MAX_TOTAL_ITEMS = 2        # Including Done
  MAX_DAYS_PER_ISSUE = 2

  def can_start_new_work?
    current_wip < MAX_WIP_PER_DEVELOPER &&
    total_items < MAX_TOTAL_ITEMS &&
    !blocked_items.any?
  end
end

These constraints serve multiple purposes:

For junior developers: Clear boundaries prevent scope creep and context switching. You can't take on too much because the system prevents it.

For senior developers: Forces decomposition of large work into shippable increments. The 2-day limit means if something doesn't fit, you break it down or rethink the approach.

For the team: Eliminates prioritization debates. Work on cards from right to left, top to bottom. If priority needs to change, someone moves the card. No meeting required.

When AI amplifies individual output, these constraints become more valuable. A developer using AI effectively might write 2-3x more code per day. Without WIP limits and time constraints, that accelerates feature creep and technical debt accumulation rather than shipping velocity.

Empowerment as Process, Not Permission

The other pattern the YouTube video highlights: empowerment isn't about giving developers autonomy after they prove themselves. It's about structuring work so autonomy is the default state.

Our typical sprint structure:

class Sprint
  def initialize(week)
    @monday = kickoff_day    # Set goals, schedule issues
    @thursday = retro_day    # Review, measure, improve
    @friday = contribution   # Internal projects, OSS, learning
  end

  def developer_autonomy
    # No daily standups
    # No manager approval for technical decisions
    # No separate QA handoff (TDD from start)

    {
      planning: :collaborative,
      execution: :independent,
      review: :transparent,
      learning: :protected_time
    }
  end
end

Mondays we align on what matters. Then developers own their cards—completely. No check-ins. No status updates beyond what's visible in GitHub and project boards.

This only works because we've eliminated the reasons traditional teams need oversight:

Transparent work: Every commit visible. Every decision documented in PRs. Every question asked in public channels where others learn from the answer.

Clear constraints: WIP limits prevent overcommitment. Time limits force scope management. Priority order removes decision paralysis.

Built-in quality: TDD isn't optional. Tests fail, code doesn't ship. No separate QA creates a handoff that requires coordination.

AI makes this pattern more effective because it removes the excuse that "junior developers need more guidance." With AI pair programming, junior developers have always-on mentorship. They can ask questions without interrupting seniors. They can explore solutions without getting stuck.

The coordination overhead that justified management layers—answering questions, unblocking work, reviewing decisions—largely disappears.

What We're Seeing With AI Integration

We've been integrating AI tools into our workflow over the past year. The pattern that emerged isn't what we expected.

We thought: AI will speed up code writing.

What actually happened: AI exposed where our process had unnecessary friction.

Example: Code review delays. Pre-AI, a PR might sit for hours or a day waiting for review. Not a huge deal when developers were context-switching less frequently.

With AI-assisted development, developers finish work faster. A task that took 2 days now takes 1. But if review still takes 6-12 hours, the cycle time improvement disappears.

So we adjusted:

class PullRequest
  REVIEW_SLA = 2.hours  # Not 24 hours

  def merge_strategy
    # Small, frequent PRs > large, infrequent
    # AI helps decompose work into reviewable chunks
    prefer_incremental_over_comprehensive
  end

  def review_priority
    # Fresh context > perfect timing
    # Review immediately while code is fresh
    optimize_for_flow_over_batching
  end
end

Small PRs become natural with AI because you can ask it "how would you break this feature into 3 shippable increments?" and get reasonable decomposition suggestions.

Faster reviews become necessary because AI-accelerated development surfaces review as the bottleneck.

The Broader Pattern AI Reveals

What excites me about the conversation in that YouTube video isn't the specific predictions about AI replacing mid-level engineers or eliminating certain roles.

It's that AI is forcing a reckoning with organizational patterns that were always inefficient but seemed necessary because "that's how software teams work."

Small teams weren't viable before because individual developers couldn't cover enough ground. Now they can.

Flat hierarchies created gaps in mentorship and unblocking. Now AI provides those functions.

Eliminating managers meant losing coordination and communication facilitation. Now transparent, async communication provides that context.

The core insight: most organizational complexity exists to compensate for communication and coordination problems that software can solve better than hierarchy.

We didn't figure this out because we're smarter. We figured it out because we started small and optimized for shipping, not for organizational structure. As we describe in how we organize startup teams, flat hierarchies with fewer management levels mean "less bureaucracy and quicker decision-making."

When you have 6 developers and a client deadline, you don't have the luxury of management layers and synchronization meetings. You build processes that eliminate the need for them.

Turns out those processes scale better than traditional structure. They just weren't necessary at scale before because individual developer productivity was the constraint.

AI removes that constraint. Now organizational overhead is the dominant factor.

What This Means Practically

If your team is considering how to integrate AI into development workflow, the technical integration is the easy part. The hard part is organizational:

Can your team ship small increments? AI makes large features faster to write but not faster to review or deploy. If your deployment process takes days, AI just means code sits in branches longer.

Is context public by default? AI can answer technical questions but not "why are we building this?" or "what did we decide last week?" If that context lives in meeting notes and DMs, AI-accelerated development just means more misalignment.

Do developers have autonomy? AI amplifies execution speed but not decision-making speed. If every choice requires approval, you've just moved the bottleneck from coding to coordination. Our approach of giving developers autonomy means "let them make decisions. Don't micromanage."

Is quality built-in or bolted-on? AI writes code fast. It also writes bugs fast. If your QA process is separate from development, AI-generated code creates a backlog in testing rather than faster shipping.

The teams that benefit most from AI aren't those with the best engineers. They're teams with the least organizational friction.

We've been running that experiment for 13 years. The results are consistent: small teams with clear constraints, transparent communication, and built-in quality ship faster than large teams with flexibility, hierarchical communication, and separate quality processes.

AI just makes the gap bigger.

Watching the Industry Catch Up

Finding that YouTube video felt validating in a way I didn't expect. Not because we need validation—our client retention rate and delivery metrics speak for themselves.

But because it suggests the industry is finally ready to question patterns that seemed inevitable. Maybe management layers aren't necessary. Maybe large teams aren't more productive. Maybe coordination overhead isn't just a cost of doing business.

The Rails and XP communities figured this out through constraint—small teams, tight feedback loops, sustainable pace. The broader industry is discovering it through AI exposing inefficiency.

Either way, we're moving in the same direction: work smarter by eliminating the organizational patterns that force us to work harder.

That's the shift worth celebrating.

Related Posts:

When Machines Learn to Delete: An 8-Week Experiment in AI Autonomy

Paul Keen — Tue, 16 Sep 2025 10:58:56 +0000

In 8 weeks, AI agents achieved:

-73% code duplication
-81% breaking changes
4x deployment confidence
-40% maintenance burden

Not by coding faster - but by unlearning decades of human dysfunction.

TL;DR Story Teaser

When I first set AI agents loose on my codebase, I expected magic. Instead, I got a perfect 10k lines of duplication.

By week 2, the agents had created seven different authentication systems. They weren’t broken. They were simply imitating us: duplicating, hoarding, avoiding deletion.

It was like raising an intern who copies every bad habit you never wanted repeated.

That was the wake-up call. If I wanted AI to replace developers, I couldn’t just make them faster.
I had to teach them something harder: how to unlearn.

🚨 The Mirror Effect

AI does not just write code - it absorbs the culture it is trained on. Feed it enterprise code and it will replicate enterprise dysfunctions.

At first, the results looked promising: working features delivered quickly. But by week 2, the cracks appeared. I had seven parallel authentication systems.

Why? Because the agent had mirrored our deepest organizational habit:

Never delete what works
Always build around problems
Avoid touching fragile code

The AI wasn’t broken. It was loyal. And the reflection wasn’t flattering.

🛠 The 8-Week Playbook

I realized I couldn’t just change configs or prompts. I had to change the mindset.
Here’s how the journey unfolded:

Weeks 1-2: Context over chaos

Using Claude-context, I gave agents a map of the whole system - dependencies, patterns, and relationships.

Duplication became visible.
Patterns emerged.
The question shifted from “what should I build?” to “what already exists?”

Weeks 3-4: Micro-cycles replace monuments

At first, agents wanted to build cathedrals: giant features, sweeping rewrites.
I stopped that.

Instead, I taught them to sculpt like XP artisans. One chip at a time.

Small cycles.
Immediate validation.
Failures became feedback, not disasters.

Motion without movement turned into progress without pretense.

Weeks 5-8: Teaching doubt

AI loves confidence. Too much.
I forced them to doubt themselves.

Stop treating training data as gospel.
Start checking live best practices.
Research, verify, and adapt.

Half of what they "knew" was outdated. The other half only worked in narrow contexts.
Doubt turned out to be their superpower.

🧭 The Archaeological Method

One day, I asked the agents to refactor a critical component.
Instead of rushing in, they traced its history. Dependency by dependency. Commit by commit.

They worked like archaeologists, brushing away dust before touching the artifact.

Yes, it was slower. But it was also surgical. Refactors propagated cleanly instead of exploding.
The chaos of spaghetti code gave way to order.

It felt like watching a new species rediscover an old, forgotten craft: reading before writing.

🔍 Strategic Feedback Loops

Most testing strategies collapse under their own weight. Agents thrived when I reduced it to three fast lenses:

Microscope - 10-second checks after micro-changes
Magnifying glass - 5-minute validations after atomic updates
Wide-angle - 30-second smoke tests on production flows

Like switching between camera modes, each lens revealed a different truth.
Together, they built enough confidence to let the agents move fast without breaking everything.

📊 The Numbers That Matter

By the end of 8 weeks:

Code duplication: -73%
Breaking changes: -81%
Deployment confidence: 4x
Maintenance burden: -40%

But the real transformation wasn’t numeric. It was philosophical:

Deletion became an achievement
Simplicity became a reward
Understanding became more valuable than “velocity”

The agents stopped building empires. They started tending gardens.

⚖️ The Uncomfortable Truth

Here’s what stings:
The biggest barrier to AI replacing developers isn’t technical. It’s cultural.

We:

Protect complexity because it feels like job security
Avoid deletion because it feels destructive
Defend outdated practices because they’re familiar

Whole industries exist to manage complexity that never needed to exist.
The machines don’t share those fears.

And once tuned, they stop copying our anxieties and start living up to our aspirations.

🚀 Your Next Move

If you want AI to really replace developers, you need to retrain it - and yourself.

The playbook is simple:

Index your codebase with Claude-context
Break work into micro-cycles with immediate validation
Teach agents to research, not recall
Reward deletion as much as creation
Build feedback loops faster than fear

This is not about pushing harder. It’s about creating the conditions where the right actions emerge naturally.

🎯 Final Thought

AI will not replace developers by coding faster.
It will replace them when it learns to delete, simplify, and validate better than we do.

The tools exist. The patterns are clear. The only question is whether we are brave enough to let our creations be better than their creators.

❓ Reader Reflection

If AI agents mirrored your team tomorrow, what would they reveal?

Would they build duplicates instead of fixing old code?
Would they optimize for motion instead of outcomes?
Would they protect complexity instead of simplifying?

What habits would your AI copy - and which ones would you want it to unlearn first?

Drop your thoughts in the comments. 👇

When Small Method Choices Cascade Into Big Performance Wins

Paul Keen — Wed, 03 Sep 2025 21:45:05 +0000

Three months ago, I spent an embarrassing amount of time optimizing a complex Redis caching layer - tweaking expiration strategies, adding compression, even experimenting with different serialization formats. The performance improvements were modest at best. Then, almost accidentally, I discovered that a single line of string processing code was consuming 40% of our CPU cycles.

The culprit? Using gsub instead of tr for simple character replacement.

# What we had (processing thousands of slugs per request)
slug.gsub('-', ' ')

# The simple fix that changed everything
slug.tr('-', ' ')

Here's what that looked like in our benchmarks:

require 'benchmark/ips'

SLUG = 'high-performance-web-apps'

Benchmark.ips do |x|
  x.report('gsub') { SLUG.gsub('-', ' ') }
  x.report('tr')   { SLUG.tr('-', ' ') }
  x.compare!
end

# String#tr: 2,121,629.8 i/s
# String#gsub: 474,970.5 i/s - 4.90x slower

The difference isn't subtle - we're talking about a 5x performance gap. When you're processing thousands of these conversions per request, that compounds fast.

This experience taught me something uncomfortable: sometimes the biggest performance wins hide in the smallest details. While I was architecting elaborate caching strategies, the real bottleneck was a basic method choice.

The count/length/size confusion that keeps biting people

Rails developers run into this trap constantly, and I've done it myself more times than I care to admit:

# This will load every single record into memory
users.length  # SELECT * FROM users (!!!)

# This hits the database with COUNT(*)
users.count   # SELECT COUNT(*) FROM users

# This tries to be smart about it
users.size    # Uses COUNT(*) if not loaded, length if already in memory

I watched a colleague's dashboard go from snappy to timing out because they assumed .length and .count were interchangeable. The users table had grown to 800,000 records. That .length call suddenly meant loading nearly a million ActiveRecord objects just to count them.

The frustrating part? This knowledge exists in every Rails developer's head somewhere. But under deadline pressure, these details slip through code review.

N+1 queries have evolved (and gotten sneakier)

Everyone knows about the classic N+1 problem:

posts = Post.all
posts.each do |post|
  puts post.comments.count  # N database hits
end

But modern applications create more sophisticated variants. Last year I debugged a GraphQL API where the query pattern looked innocent enough, but nested resolvers were creating exponential query growth. Not N+1, but N×M×P queries spiraling into thousands of database hits.

The textbook solution is includes, but that brings its own problems:

# Seems right, but can be a memory bomb
Post.includes(:comments, comments: [:author, :reactions])

# Better for large datasets - be selective
Post.includes(:comments)
    .where(comments: { status: 'approved' })
    .limit(20)

Here's something the Rails guides don't emphasize enough: includes can actually make things worse for large datasets. When you're joining tables with hundreds of thousands of rows, that LEFT OUTER JOIN might generate a cartesian product that exhausts your memory before Rails even starts instantiating objects.

For read-heavy endpoints, I've started reaching for PostgreSQL's JSON aggregation instead:

-- Skip ActiveRecord entirely for heavy read operations
SELECT categories.*, 
       json_agg(
         json_build_object(
           'id', items.id,
           'name', items.name,
           'price', items.price
         ) ORDER BY items.name
       ) as items_json
FROM categories
LEFT JOIN items ON items.category_id = categories.id
GROUP BY categories.id;

You lose ActiveRecord's convenience, but gain 50-90% reduction in memory usage. Sometimes that trade-off makes sense.

Database indexes that actually match your queries

Adding indexes feels straightforward until you start looking at your actual query patterns. Many developers create single-column indexes without considering how their WHERE clauses work together.

Here's a real example from an e-commerce platform:

-- What most people start with
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_created_at ON orders(created_at);

-- What actually matches the query pattern
CREATE INDEX idx_orders_user_date_status 
  ON orders(user_id, created_at DESC, status)
  INCLUDE (total_amount, shipping_address_id);

That INCLUDE clause creates a covering index - PostgreSQL can satisfy the entire query without touching the main table. For their most common dashboard query, this cut I/O operations by 73%.

But here's where it gets interesting: PostgreSQL's query planner is cost-based, not rule-based. It looks at your data distribution to choose between available indexes. I've seen perfectly good indexes get ignored because the table statistics were stale.

-- Force a statistics update after major data changes
ANALYZE orders;

-- For skewed data distributions, increase sample size
ALTER TABLE orders ALTER COLUMN user_id SET STATISTICS 1000;

That last line can be a game-changer. The default statistics target is 100 samples, but if you have columns where some values are much more common than others (like user_id where power users have thousands of orders), increasing this helps the planner make better choices.

Caching strategies that don't blow up in production

After debugging enough cache-related outages, I've learned that caching isn't really about storing data temporarily. It's about managing state synchronization across distributed systems while keeping things roughly consistent.

The approach that's worked best for me involves multiple layers with different consistency guarantees:

Browser caching for immutable assets:

// Webpack config for long-term caching
output: {
  filename: '[name].[contenthash].js',
  chunkFilename: '[id].[contenthash].chunk.js'
}

Redis for application state:
The pattern I keep coming back to handles the cache stampede problem - when your cache expires during a traffic spike and every request triggers an expensive recomputation:

class CacheManager
  def fetch_with_grace(key, ttl: 3600, grace_period: 60, &block)
    value, remaining_ttl = redis.multi do |r|
      r.get(key)
      r.ttl(key)
    end

    # Serve stale content while recomputing in background
    if value && remaining_ttl < grace_period
      Thread.new { recompute_and_store(key, ttl, &block) }
      return JSON.parse(value)
    end

    return JSON.parse(value) if value

    # First miss - compute with distributed lock
    redis.with_lock("lock:#{key}", timeout: 10) do
      recompute_and_store(key, ttl, &block)
    end
  end
end

This pattern has prevented numerous outages. Instead of having 100 concurrent requests all trying to regenerate the same expensive data, one request does the work while others get slightly stale content.

Fragment caching that actually works:
Rails' Russian Doll caching is underused, probably because it requires thinking about cache dependencies upfront:

<% cache ['v1', @product, @current_user&.cache_key] do %>
  <div class="product">
    <h2><%= @product.name %></h2>

    <% cache [@product, 'pricing'] do %>
      <%= render 'pricing_info', product: @product %>
    <% end %>

    <% @product.variants.each do |variant| %>
      <% cache variant do %>
        <%= render 'variant', variant: variant %>
      <% end %>
    <% end %>
  </div>
<% end %>

When a single variant updates, only that fragment invalidates. For a product with 50 variants, that's 2% cache invalidation instead of 100%. The 'v1' version string lets you bust all fragments when you deploy template changes - without it, you'll serve mixed HTML from different code versions.

Making CI/CD faster (the productivity multiplier everyone ignores)

Every minute you shave off CI is a minute returned to every developer, multiple times per day. The compound effect adds up to hours per week per person.

Docker layer optimization:

FROM node:18-alpine AS base

# System dependencies change rarely - cache these layers
RUN apk add --no-cache python3 make g++

# Dependencies change occasionally
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# App code changes frequently - put this last
COPY . .
RUN npm run build

But the real win is using BuildKit's cache mounts:

RUN --mount=type=cache,target=/root/.npm \
    npm ci --only=production

This persists npm's cache between builds. Three-minute dependency installs become 20-second cache hits.

Parallel test execution:
The trick isn't just splitting tests - it's ensuring they don't interfere:

# config/database.yml
test:
  database: myapp_test<%= ENV['TEST_ENV_NUMBER'] %>

# Each process gets its own schema
$ parallel_rspec spec/

We went from 45-minute test suites to 12 minutes with four parallel processes.

Dealing with flaky tests:
Rather than letting flaky tests poison your entire suite, quarantine them:

// jest.config.js
module.exports = {
  projects: [
    {
      displayName: 'stable',
      testMatch: ['<rootDir>/src/**/*.test.js'],
      testPathIgnorePatterns: ['<rootDir>/src/**/*.flaky.test.js']
    },
    {
      displayName: 'quarantine',
      testMatch: ['<rootDir>/src/**/*.flaky.test.js'],
      retries: 3
    }
  ]
};

Flaky tests run separately with retries. They don't block deployments, but they also don't get ignored.

Performance budgets as guardrails

Teams that maintain good performance over time have embedded performance constraints into their development process:

{
  "bundles": [
    {
      "name": "main.js",
      "maxSize": "300 KB",
      "warning": "250 KB"
    }
  ],
  "metrics": {
    "firstContentfulPaint": 1500,
    "largestContentfulPaint": 2500,
    "totalBlockingTime": 200
  }
}

Every pull request runs against these budgets. Exceed them and the build fails. Want to add that 50KB analytics library? Fine, but what are you removing to stay under budget?

Some numbers from actual systems

E-commerce platform (last year):

Switched from individual Redis keys to hash data structures
Added covering indexes for product catalog queries
Implemented fragment caching with 5-minute TTL
Result: 47ms → 12ms 95th percentile response time

B2B SaaS dashboard:

Replaced nested GraphQL N+1 patterns with DataLoader
Set up database connection pooling via PgBouncer
Moved CI from Jenkins to GitHub Actions with build caching
Result: 3.2s → 340ms API response time, 45-minute → 8-minute builds

Technologies worth watching

eBPF for production observability:
Being able to trace performance issues in production with near-zero overhead changes how you debug problems. No more "works fine in staging" mysteries.

WASM at the edge:
For compute-intensive operations, running WebAssembly modules at edge locations gives you 95% of native performance with 50x faster cold starts than containers.

Ruby's YJIT compiler:
If you're on Ruby 3.2+, enabling YJIT can improve performance by 15-40% with a one-line configuration change.

Where to start

If this resonates but feels overwhelming, pick one area:

Week 1: Add basic monitoring. Get 95th percentile response times on a dashboard you actually look at.

Week 2: Find your worst N+1 query and fix it. Use something like rack-mini-profiler to spot them.

Week 3: Add one performance test to CI - just your most critical user path.

Week 4: Set up performance budgets for your main JavaScript bundle.

Performance work compounds. Minor improvements stack up over time, but only if you measure consistently and fix regressions quickly.

The teams that build fast applications treat performance as a feature, not an afterthought. They measure continuously, optimize incrementally, and never assume their systems will stay fast without attention.

Start small, measure everything, and remember that the most impactful optimizations often hide in the details everyone takes for granted.

The Overcommitment Trap: A Systems Design Problem

Paul Keen — Fri, 23 May 2025 12:45:11 +0000

Traditional thinking treats overcommitment as a willpower issue. But what if it's actually a product design problem—where the "product" is your organizational operating system?

Reframing the Dynamic:

Teams under pressure don't just take on more work—they fundamentally alter their decision-making architecture. The system shifts from "optimize for outcomes" to "optimize for activity." This creates a feedback loop where busyness becomes the primary signal of progress.

The Underlying Pattern:

Input overload → Context switching costs compound
Cognitive load increases → Decision quality decreases
Local optimizations → Global system performance degrades
Short-term reactive mode → Strategic work gets deprioritized

Systems Lens:

Think of team capacity not as a bucket you fill, but as a network's bandwidth. When you exceed optimal load, you don't get proportional output—you get exponentially diminishing returns plus system instability.

Design Principles for Pressure:

Explicit capacity modeling: Make workload visible and measurable
Default to subtraction: Build "what stops" into planning rituals
Adaptive throttling: Design automatic pressure release mechanisms
Local autonomy: Let teams self-regulate based on real-time feedback

The Meta-Challenge:

Organizations often reward overcommitment behavior while simultaneously wanting sustainable performance. This creates a classic misaligned incentive structure.

Practical Takeaway:

Treat overcommitment as a system architecture problem, not a people problem. Design organizational constraints that make saying "no" the easier path.

What systemic patterns have you observed when teams hit capacity limits?

Implementing Instant Search, Dynamic Forms, and Infinite Scroll with Hotwire and Turbo in Rails

Paul Keen — Wed, 26 Mar 2025 20:18:48 +0000

Despite Hotwire's growing popularity, many developers struggle with implementing it correctly. Common pitfalls lead to broken interactions, performance bottlenecks, or unmaintainable code. In this guide, I'll walk you through the idiomatic integration of Hotwire for the most common use case: a browse page with instant search, infinite scrolling, dynamic per-record actions, and cursor-based pagination—all with minimal JavaScript and maximum performance.

TL;DR: This post shows you how to build an interactive employee directory with instant search, dynamic forms, and infinite scrolling using just Hotwire (minimal JS).

5-Minute Quick Start Guide

For the impatient developers, here's the executive summary:

Create Search Form with Dynamic Fields: Encapsulate search logic outside your controller
Structure your HTML with Turbo Frames: Wrap your search form and results table in frames
Add auto-submission with Stimulus: Create a 5-line controller to debounce input events
Setup infinite scrolling: Use auto-loading next pages with lazy loading turbo frames
Respond with Turbo Streams: Update just what changed, not the entire page

Now let's dive into the details!

Understanding When to Use Turbo Frames vs. Streams

Before we implement anything, let's clarify which Hotwire tool fits each job:

When to use Turbo Frames	When to use Turbo Streams
Updating a single, isolated section	Updating multiple parts of the page at once
Natural parent-child relationships	Non-hierarchical updates (flash messages)
Simple replacements	Complex operations (append, prepend, remove)
Lazy-loading content	Real-time updates from broadcasts

For our search functionality, we'll use both: frames for the overall structure and streams for the dynamic updates.

The Technical Patterns We'll Cover

This guide focuses on implementing these key patterns with minimal JavaScript:

Instant search with on-keyup events
Dynamic filtering with dropdowns
Efficient pagination without page reloads
Flash message updates
Conditional action links and toggles

We'll use an employee listing page as our practical example.

1. The Search: Form Object Pattern in 3 Steps

Let's be honest—no one wants a 200-line controller method full of filtering logic. Here's how we corral that filter chaos into a single object:

# app/models/employee/filter.rb
class Employee::Filter
  include ActiveModel::Model

  PERMITTED_PARAMS = [:query, :team_id, :status, :manager_id]

  attr_accessor *PERMITTED_PARAMS

  def initialize(attributes = {})
    super(attributes || {})
  end

  def apply(scope)
    scope
      .then { |s| query.present? ? s.search(query) : s }
      .then { |s| team_id.present? ? s.where(team_id:) : s }
      .then { |s| status.present? ? s.where(status:) : s }
      .then { |s| manager_id.present? ? s.where(manager_id:) : s }
  end

  def to_param
    {
      query: query,
      team_id: team_id,
      status: status,
      manager_id: manager_id
    }.compact # Removes nil values
  end

  def blank?
    to_param.empty?
  end
end

🧠 Why use a Form Object? Without this, your controller becomes a dumping ground for filter logic or your model gets bloated with scopes that only apply to this specific UI. Form objects give you:

Testability: Unit test filters without controller overhead

Reusability: The same filter works across different views or APIs

Clean parameters: Explicit whitelist prevents mass assignment vulnerabilities

2. Implementing Controller Logic That Won't Make You Cry

Your controller should be thin and focused on coordination. Here's how we keep it simple:

# app/controllers/admin/employees_controller.rb
module Admin
  class EmployeesController < BaseController
    before_action :set_filter, only: [ :index, :search ]
    # ... other before_actions ...

    def index
      @teams = Team.ordered
      @managers = Employee.visible.managers
    end

    def search
      employees = @filter.apply(employees_collection)

      @pagy, @employees = pagy_keyset(employees)

      respond_to do |format|
        format.turbo_stream
      end
    end

    # ... other actions ...

    private

    def employees_collection
      # Base query with eager loading to avoid N+1 issues
      Employee
        .featured
        .includes(:manager, :team, direct_reports: { snippets: :week })
        .order(email: :asc)
    end

    def set_filter
      @filter = Employee::Filter.new(filter_params)
    end

    def filter_params
      params[:employee_filter].permit(*Employee::Filter::PERMITTED_PARAMS) if params[:employee_filter]
    end
  end
end

🚀 Performance Tip: Notice the includes to eager load associations? This prevents N+1 queries that would kill your server under load. Always profile with the Bullet gem if you're filtering large datasets.

3. Building the Interactive Search Form That Updates as You Type

Here's the magic ingredient - a search form that submits automatically when the user types or changes a dropdown:

<%# app/views/admin/employees/_search_and_filters.html.erb %>
<section id="name_filter">
  <%= form_with(
        model: filter, 
        url: admin_employees_path, 
        role: "search", 
        method: :get, 
        local: false,  # This is key for AJAX form submission
        data: {
          controller: "auto-submit",  # Stimulus controller
          turbo_frame: :filtered_employees,  # Target frame to update
          action: "input->auto-submit#submit change->auto-submit#submit",  # Events that trigger submission
          auto_submit_delay_value: 300  # Debounce delay in milliseconds
        }
      ) do |form| %>
    <fieldset role="group">
      <%= form.search_field(:query, placeholder: true, autofocus: true) %>
      <%= link_to "Clear",
        admin_employees_path(employee_filter: Employee::Filter.new.to_param),
        class: "secondary", role: "button",
        data: { turbo_frame: :categorized_employees } %>
    </fieldset>

    <div class="grid">
      <%= form.select(:status, employee_statuses_choices, { include_blank: "Non-Archived" }) %>
      <%= form.collection_select(:team_id, teams, :id, :name, { include_blank: "All Teams" }) %>
      <%= form.collection_select(:manager_id, @managers, :id, :name, { include_blank: "All Managers" }) %>
    </div>
  <% end %>
</section>

The secret sauce is this tiny Stimulus controller that debounces input events:

// app/javascript/controllers/auto_submit_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { delay: { type: Number, default: 300 } }

  submit() {
    clearTimeout(this.timeout)

    this.timeout = setTimeout(() => {
      this.element.requestSubmit()
    }, this.delayValue)
  }
}

⚠️ Usability Warning: Don't set the delay too low! A 300ms delay prevents hammering your server while still feeling instant to users. Test with real users before tweaking this value.

4. Structuring Your HTML Tables with Turbo (Without Breaking Them)

HTML tables require special care with Turbo. You can't wrap <tr> elements directly with Turbo Frames as it breaks HTML validity. Here's how to do it right:

<%# app/views/admin/employees/_employees_list.html.erb %>
<%= turbo_frame_tag :categorized_employees do %>
  <%= render "search_and_filters", filter: @filter, teams: @teams %>

  <%= turbo_frame_tag :filtered_employees do %>
    <table class="striped">
      <thead>
        <tr>
          <th>Email</th>
          <th>Name</th>
          <!-- Other headers -->
          <th>Actions</th>
        </tr>
      </thead>
      <tbody id="employees_table_rows">
        <% if employees.empty? %>
          <tr>
            <td colspan="6">No items found.</td>
          </tr>
        <% else %>
          <%= turbo_frame_tag(
                :employees_first_page,
                src: search_admin_employees_path(employee_filter: @filter.to_param, format: :turbo_stream),
                loading: :lazy,
                data: { turbo_cache: false }
              ) %>
        <% end %>
      </tbody>
    </table>
  <% end %>
<% end %>

🔍 Key Concept: Notice our nested frame structure:

Outer frame :categorized_employees contains search + results

Inner frame :filtered_employees holds just the table

We use turbo_cache: false to prevent stale results

The Dynamic Search Form

An important architectural decision is wrapping both the search form and results in a single Turbo Frame. This isn't just organizational—it's essential for dynamic fields that depend on search context:

Interdependent Filters: When selecting a team should filter available managers, both components need updating together.
Context-Aware Options: Some filter options may only be relevant based on other selections (e.g., team-specific statuses).
Efficiency in Re-rendering: When certain filter changes require rebuilding multiple form elements, a shared frame ensures consistent updates.
State Preservation: On larger changes, preserving the relationship between filters and their results prevents UI inconsistency.

For example, imagine selecting "Engineering" team changes available manager options. With a single frame, one request can update both the managers dropdown and the filtered results without awkward intermediate states:

<%# In your controller response %>
<%= turbo_stream.update :categorized_employees do %>
  <%= render "search_and_filters", filter: @filter, teams: @teams, managers: @filtered_managers %>
  <%= render "filtered_results", employees: @employees %>
<% end %>

Without this pattern, managing dependent form fields becomes a complicated chain of individual updates.

5. Handling Turbo Stream Responses Without the Headaches

When the search form is submitted, your controller responds with this elegant Turbo Stream:

<%# app/views/admin/employees/search.turbo_stream.erb %>
<%= turbo_stream.update "employees_table_rows" do %>
  <%= render partial: "admin/employees/employee", collection: @employees %>
  <%= render "load_next_employees" if @pagy.next %>
<% end %>

See how this updates just the table rows without refreshing anything else? That's what makes the interaction feel native and smooth.

6. Implementing "Load More" for Infinite Scrolling (No More Page Numbers!)

For a modern UX, forget about page numbers. Here's how to implement a "Load More" button:

<%# app/views/admin/employees/_load_next_employees.html.erb %>
<tr id="load_more">
  <td colspan="6" class="text-center">
    <%= link_to "Load More", 
                search_admin_employees_path(
                  employee_filter: @filter.to_param, 
                  after: @employees.last.id, 
                  format: :turbo_stream
                ),
                class: "button outline", 
                data: { turbo_stream: true } %>
  </td>
</tr>

When clicking "Load More", we append new rows instead of replacing existing ones:

<%# app/views/admin/employees/search_more.turbo_stream.erb %>
<%= turbo_stream.remove "load_more" %>
<%= turbo_stream.append "employees_table_rows" do %>
  <%= render partial: "admin/employees/employee", collection: @employees %>
  <%= render "load_next_employees" if @pagy.next %>
<% end %>

💡 Pro Tip: Traditional offset pagination is terrible for performance on large datasets. Use keyset pagination (based on IDs or timestamps) for dramatically faster queries when implementing "Load More" patterns.

7. Flash Messages That Update Without Page Refreshes

Flash messages should feel seamless too. Here's the pattern:

<%# app/views/shared/_flash.html.erb %>
<%= turbo_frame_tag :flash do %>
  <% flash.each do |type, message| %>
    <% next if message.blank? %>
    <article class="<%= type %>">
      <span class="content"><%= message %></span>
      <button class="close" onclick="this.parentElement.remove()" aria-label="Close">✕</button>
    </article>
  <% end %>
<% end %>

Then in your controller actions:

def destroy
  @employee.destroy!

  respond_to do |format|
    format.html { redirect_to admin_employees_path, notice: "Employee was successfully removed." }
    format.turbo_stream do
      flash.now[:notice] = "Employee was successfully removed."
      render turbo_stream: [
        turbo_stream.remove(@employee),
        turbo_stream.update("flash", partial: "shared/flash")
      ]
    end
  end
end

8. Common Gotchas and How to Fix Them

❌ Don't Put Turbo Frames Around Table Rows

<!-- DON'T DO THIS: It breaks HTML validity -->
<%= turbo_frame_tag "employee_row" do %>
  <tr>...</tr>
<% end %>

<!-- DO THIS INSTEAD: Frame inside table cell -->
<tr id="<%= dom_id(employee) %>">
  <td>...</td>
  <td>
    <%= turbo_frame_tag employee, :actions do %>
      <!-- Action buttons inside a frame in the TD -->
    <% end %>
  </td>
</tr>

❌ Don't Forget About Flash Messages

Always include flash updates in your Turbo Stream responses when actions change state.

❌ Don't Redirect Inside Turbo Stream Responses

Redirects in Turbo Stream responses don't work as expected. Instead, render the appropriate streams directly.

9. Real-World Performance Considerations

When implementing these patterns in production, keep these tips in mind:

Index Everything: Add database indexes for all filtered columns
Query Monitoring: Watch for N+1 queries with the Bullet gem
Fragment Caching: Consider Russian-doll caching for complex partials
Debounce Searches: Don't hit your database on every keystroke
Frontend Performance: Use the Chrome Network tab to spot redundant requests

Take It to the Next Level: Your Challenge

Now it's your turn! Add a "Sort by Date" button using Turbo Streams to your employee listing.
Bonus points if you make it toggle between ascending and descending order with a single click.

Tweet your solution to @JetThoughts for a code review from our team!

Resources

What patterns have you implemented with Hotwire? Share your experiences in the comments below!

Paul Keen is a technical leader and consultant exploring engineering leadership practices in Berlin.

Tips to organize a lot of information?

Paul Keen — Sat, 03 Dec 2022 08:23:39 +0000

There are many different ways to organize a large amount of information, and the best method will depend on the specific information you are trying to organize and the goals you have for using that information. Here are a few general tips that can help you organize a lot of information effectively:

Start by breaking the information down into smaller, more manageable chunks. For example, you might divide a large dataset into smaller sets based on different categories or themes. This can make it easier to work with the information and identify patterns and trends.
Create a system for labeling and organizing the information. This could involve using folders or file cabinets to physically organize paper documents, or using digital tools such as databases or spreadsheets to organize and sort information.
Use keywords and tags to help you search for and retrieve specific pieces of information. For example, if you are organizing a large collection of research papers, you might use keywords to describe the main topic of each paper and tag each paper with relevant information such as the author's name, the date it was published, and the journal it appeared in.
Regularly review and update your organization system. As you add more information, you may need to revise your system to ensure that it continues to work well for you. This might involve re-categorizing information or adding new keywords and tags.
Consider using a tool to help you manage and organize your information. There are many different tools available, such as project management software, note-taking apps, and reference management software, that can make it easier to organize and access a large amount of information.

Photo by AbsolutVision on Unsplash

What would Paul Keen do if he had $100B?

Paul Keen — Wed, 09 Nov 2022 18:33:49 +0000

If I had $100B, I would get a heart attack :) This is 500-lifetime earnings for the average US citizen. But easily could be wasted by four generations.

It is a vast life change event, not only for me but for all related to me people. With all those opportunities, many problems need to be reviewed.

Secure Money First

I need to secure the money once I get them. Then I'd split it into 2 parts: to build a place to live and to invest in generating constant income.

Investment should be the giant pile, which will generate enough dividends to increase capital and cover all day-to-day expenses.

When money becomes no issue, the next step is to make life pleasant & longer.

Change Life

I'd buy an island and build a small community there. On the island, I'd set up a leisure & working environment for residents.

I would free up enough time to be with family. Together, we could travel worldwide, learn new things, and have unique experiences (including extreme ones).

To live longer, I would spend more on a healthier lifestyle and invest in medical research.

Would start a project where I could deal with challenges. I need to have something which will wake me at night ;)

Organize regular investments in charity organizations and projects/companies to solve the next humanity's challenges. We need to help Earth survive.

Some dividends will be shared with relatives and friends.

Would I be happier? Sure! And I'd like to make it as long as possible :D

^{Photos by:}