With a Twist

An agent chat turned into a skill, and then it QA'd itself

2026-03-19T00:00:00+00:00

I had a simple index.html page, a marketing site for a client in Spanish. They asked an English version too, so I opened the chat to Claude’s Opus 4.5 model and asked it to create a near-identical en/index.html with content translated. Easy peasy.

I opened both files side by side and skimmed, they looked the same with lines in different languages. But I’m used to testing changes, and agents find things to fix before I start more careful checking. While I had this thought, the client recalled they’d need a version in Portuguese as well. “Sure”.

Now, would they synchronize updates in Spanish to the other two languages? Content and design will surely drift.

The solution

I used Claude’s /skill-creator to build reusable instructions to check parity across all languages. My simple prompt:

Create a skill to check that the index files read well in all languages (Spanish and English, Portuguese upcoming). Check translations match, no page has content that the other does not, and that markup and UI looks and behaves the same.

The agent started writing a Python script to check:

DOM structure is identical after normalizing expected differences (like the language switcher)
Texts that should be translated aren’t identical across files
Same images, same order
Same stylesheets
Internal consistency (nav anchors to section IDs, <html lang> attribute)

I expected hand-wavy, maybe helpful browser-based checks. It wrote a deterministic Python script.

A noisy first run

I observed its thought process; it started flagging dozens of mismatches. Most of them cascaded from a single root cause: an extra closing </div> in the English file threw off every structural comparison after it. The output was technically correct, but not helpful as a checklist.

It iterated: it identified the root divergence pattern, filtered expected differences (the language switcher, text that’s legitimately identical across languages like proper nouns or acronyms), and re-ran until the output was clean. It also flagged actual issues it had found while building its skill:

The false positives disappeared. Now only the 2 real problems remain.

Two real bugs I’d missed

The extra </div> was a copy-paste error (that didn’t break the UI and I hadn’t noticed). And an image at the footer had an old path I hadn’t finished migrating. The skill caught them while testing itself.

Let’s add Portuguese now

When I added pt/index.html, the parity script immediately had a new problem: Spanish and Portuguese share too much vocabulary. “Engenharia” and “Ingeniería” are different enough, but dozens of short terms like proper nouns or abbreviations are identical. The script was flagging legitimate cognates as missing translations.

Opus taught the script about language proximity: it introduced a CLOSE_LANG_PAIRS to relate Spanish and Portuguese, identical text under 30 characters is assumed to be a legitimate cognate and skipped. For distant pairs (like Spanish and English), any identical text is still suspicious.

That was creative. A human may get there after a while. The agent got there in a chat that turned into an effective, reusable skill.

Closing thoughts

Internationalizing projects used to be complicated. I asked for English and then Portuguese versions, and I got a system where adding a new language is a tool call and a proof read away. A system specific to this one project, with its single index.html copied over in language subdirectories, because it’s simple, and with LLMs it’s now easy to maintain.

Testing the skill on real files caught bugs in the HTML. Adding a third language taught the skill to handle distant and proximate languages. Each step improved either the thing being checked or the thing doing the checking.

Claude, tell me what needs my attention today

2025-12-23T00:00:00+00:00

Each morning I open four tabs: Calendar, Gmail, Jira, and Obsidian. I read all, discard low priority emails or calendar events, and start building a mental picture of what I’ll do that day, and when exactly. For each piece of data I decide whether it’s time sensitive or not, whether I need to prepare beforehand, and whether I should tackle it later (or never). After warming up my brain, I kick off the actual work.

I decided an LLM should do that pre-work instead of my well-rested brain. To build such automation I’d practice Claude Code subagents and local MCP servers setup, a good exercise for my new startup, RailsPilot.ai. So I started creating my /today Claude Code command.

/today fetches information scattered accross mails, calendar, task manager, and notes, and compiles them into a prioritized task list for the day. It saves the output to a plain text file like daily_notes/2025-12-23.txt).

It’s funny to see Claude properly weighing what’s worthy of my attention from disparate sources according to natural language explanations, while it juggles different commands to decide what day is today. Discovering what’s cheap vs challening with LLMs is what I seek, and is also funny to me. December 22nd, 2025 is NOT Sunday, Claude, it’s Monday. Wise up!

It first works to define what day is today, then launches three parallel subagents, each responsible for fetching, processing and normalizing data from one source:

The Jira subagent fetches assigned issues and checks for QA comments that need my attention: my highest priority these end-of-year days.
The Calendar subagent retrieves today’s events and applies priority logic (marks certain family events as low priority reminders, whereas time-sensitive meetings are marked as high priority and with an action item to prepare 15 minutes beforehand).
The Gmail subagent reads my inbox, detects newsletters to deprioritize and defines suggested action items for the rest.

The architecture is designed for efficiency: raw API responses are contained within each subagent’s context window and discarded after processing, so only compact JSON summaries flow back to the main agent. This keeps the context clean and allows each source to fail independently without breaking the entire command. It will also let me enable only relevant MCPs per subagent, another context window optimization I didn’t yet need.

Each subagent normalizes its data into a common task schema with fields like title, source, priority, due date, URL, and action item. Low-priority items include a reason why. This normalization allows disparate data pieces to be compared and sorted. When all subagents return their results to the orchestrator agent, it merges everything into a single list sorted by priority and time.

The final output is plain text designed for quick scanning top to bottom, with key details, URL and action item after each title.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Daily Tasks - December 23, 2025
==============================

• [DEV-450] Enable PWA On Select Pages
  - Status: IN QA
  - Action: Respond to QA comments from David regarding errors on refresh
  - URL: https://client.atlassian.net/browse/DEV-450

• Your Documents are now ready for Reservation ID: 123456
  - From: Provider <^DONOTREPLY@provider.com>
  - Action: download and print documents, complete forms
  - URL: https://mail.google.com/mail/u/0/#inbox/123456789

• [DEV-430] Landing Page N+1s
  - Status: IN QA
  - Action: No QA feedback yet
  - URL: https://client.atlassian.net/browse/DEV-430

• Kids visit Granny - 3:00 PM to 7:00 PM
  - Note: Family reminder
  - URL: https://www.google.com/calendar/event?eid=eideideideideideideid

---
Generated at 2025-12-23 09:30:00

And, instead of sifting through tabs, I can go from cup of coffee straight to my top priority for the day.

How I use AI agents to code new features

2025-02-20T00:00:00+00:00

I wrote about how Cursor’s AI agent helped me build a high quality new feature in Rails, without much “prompt engineering” getting in the way.

You can find it in my employer’s blog: “How I use AI agents to code new features”.

Writing Architecture Documents (for developers)

2022-03-31T00:00:00+00:00

Our colleague Martin was about to start working on a small-scale feature, an addition to a module that wasn’t open for extension and couldn’t easily support it.

He could shoehorn his use case on top of existing architecture without affecting others much or lay a more robust foundation over which he’d implement his use case. This could also help fix long-standing bugs and enable the implementation of new features that we foresee in our next two years (but would be hard to add now). In other words, “make the change easy, then make the easy change”.

We are a 20-people team organized into three pods (each with a Product Manager, a QA tester, and about three developers), designers, and leadership roles. The three pod structure helped us work without needing to have the context of the whole application in mind but made us need to sync up whenever a decision would affect others.

Martin postponed his solution in favor of determining a better architecture. He needed to write up a document to share ideas with everyone, ensuring we covered every pod’s needs and addressed the comparatively minor feature that led to these conversations.

Martin wanted the document to:

be succinct, so everybody reads it, can share feedback, and signs off on –while also adding much detail to ensure no scenario (current or future) is left unattended
use general language so his Product Manager can follow it while also using technical jargon, so his CTO will know precisely where we are heading
be quick, so he can get going with his solution while also letting the document sit for days so people in different time zones share their feedback

How could he write the document with such competing goals? Martin and I paired on it many times, took notes, shared with the team, and wrote what worked well for us.

Definitions

First, Martin defined an objective, an audience, and a desirable trait for the document:

Objective: Efficiently communicate the problems and goals for the audience to discuss and support our decision, ideally without the need for meetings. Many people will read it many times, so we’ll take the time to make it clear and succinct.

Audience: For this case, our Director of Engineering. A single person, which in turn helps define the level of detail, tone, and deadline for the document. Interested developers and technically inclined Product Managers should be able to follow along a document intended for our Director (or know whom to ask for clarifications).
Even if more people are deciders for the solution, it will help the writer to have a single person in mind to whom he’s writing.

Desirable: Discuss at least two alternative solutions for the problem, outlining their pros and cons. What would the solution look like if we had all the time in the world? Or double our team size? Or only half of our team size? What if we needed to get something out in two weeks?

The document’s structure

Most developers at Epion have much less experience writing documents than writing code. Martin got a case of blank page block. How could he put in a couple of sheets of paper everything we discussed over lunch and on several calls, looking both at the short and long term? There were still open questions and even unknown unknowns!

I suggested starting from a template defining a structure. How should an Architecture Document look when skimming from afar? We wrote that down with some generic content that we’d iterate on for the feature and project at hand.

The blueprint with dummy content looked like this:

Bariloche (a short “catchy” name)

High-level overview

What we want (in order of priority):

A great cost/benefit ratio (weigh up requirements and available resources)

Seize a good risk/value ratio (some risk is acceptable for great value; what’s our aim and tolerance?)

Make our teams happier (what specific teams, and what can we improve for them?)

Not a fourth! That’s enough; we shall define the top ones only. Also ok: “we don’t want to"s: we don’t want to continue seeing a current architecture problem.

Who will participate in this decision, who will approve it, and who are responsible for executing it.

When: a timeline and the "why” behind each deadline.

Top-down overview. We’ll achieve this by doing first some work that makes our pods and their stakeholders happy (the feature at the start of this story). We’ll also lay down foundations for our new architecture, enabling the fixes for long-standing bugs and paving the road for features on our horizon.

Alternative A

Description

Detailed description, supported with:

ERD/class diagrams

Database migrations (maybe a link, but nice to see them verbatim here to see not only entities but also their attributes and types)

Implementation notes

Use cases and sample data (could be a link to a GitHub spike PR, a linked document, or a block of code within).

It’s not a solution to apply as-is, but detailed enough that developers can “run it” in their minds and provide more specific feedback, saving time in future code reviews.

List of features enabled by the design and problems prevented by it.

Alternative B

Description

…

Comparison

Pros and Cons of considered alternatives.

Timeline

First Quarter: We’ll do the work that triggered this conversation. Pod and PM will be happy and timely get what they want.

Second Quarter: Developers will have a better architecture to more easily implement future work in our pipeline, such as A, B, and C.

Third Quarter: We’ll delete legacy implementations and run 100% on the design we want.

Conclusion

Described objectives will be met (expand this). We can’t identify additional risks (consider running “pre-mortems” to find more). We’ll be in a better place to implement future work without neglecting our short-term commitments.

Final thoughts

One goal is to avoid discussions until we have a mature draft with concrete alternatives. Discussions expand the space of possibilities (“design by committee”), while writing reduces it to its most essential components. Consensus means no ownership. But we do want to hear everyone’s feedback before making the decision.

In an Architecture Document we should use a tone different from what we are used to during code reviews: in code review we tend to ask rather than prescribe, use open-ended questions, and ask for early feedback. We’ll first avoid such early discussion, only describing a path forward. Discussions will come later.

With Architecture Documents we can implement our near-term work while aligning ourselves with the long-term vision for Epion Products.

I took some ideas in this article from:

Square’s system to make decisions
I first read about “Pre-Mortems” in “Thinking Fast and Slow” by Daniel-Kahneman (on our Epion Book Club)
Julia Evans’ zine on writing for a single person

Mystery Guest Development Edition

2021-05-10T00:00:00+00:00

Mystery Guest is the name of an anti-pattern that often appear in tests. In short, it is caused by non explicitly declaring or naming a value, which is tested over that faulty declaration. The issue is not apparent at first, as the test is created at the same time as the fixture or factory that supports it. Eventually, when a change is needed in that support object to test something else, the change unintentionally breaks the first test.

For a test which verifies that the full_name of a user is the combination of first_name and last_name, those two properties need to appear explicitly on the test setup. Even if you have user factory, you are not testing the factory, but your own user with first_name and last_name. If the users in your application also need, say, an address not being tested in this example, the factory can provide that.

So the question arises: are tests the only ones affected by this anti-pattern?

Let’s see an example.

In our application, we had a CheckIn model and a associated Progress to record when the each step of a check-in has been completed. We want to calculate, among other things, the duration of each check-in for reporting purposes. We had something like this:

1
2
3
4
5
6
7
8
# models/check_in.rb
class CheckIn < ApplicationRecord
  has_one :progress, dependent: :destroy

  before_create -> { self.progress ||= Progress.new }

  ...
end

1
2
3
4
5
6
7
8
9
10
11
12
# models/progress.rb
Class Progress < ApplicationRecord
  belongs_to :check_in

  def duration
    if check_in_completed_at.present?
      created_at - check_in_completed_at
    end
  end

  ...
end

The duration method in Progress is the interesting one. We didn’t need to use the CheckIn created_at field because a Progress was created at the same time. So, to simplify and optimize, we used the Progress created_at method instead. There is no issue whatsoever with this approach. Or is there?

After some time, we decided to include events happening before the patient arrives to the practice, which is before the check-in.

We created a new model called Engagement. As we still wanted to keep track of steps completed before and during the check-in, we associated our Progress to the Engagement which we moved up from the CheckIn.

1
2
3
4
5
6
7
8
9
# models/engagement.rb
class Engagement < ApplicationRecord
  has_one :check_in, dependent: :destroy
  has_one :progress, dependent: :destroy

  before_create -> { self.progress ||= Progress.new }

  ...
end

1
2
3
4
5
6
# models/check_in.rb
class CheckIn < ApplicationRecord
  belongs_to :engagement

  ...
end

1
2
3
4
5
6
7
8
9
10
11
12
# models/progress.rb
class Progress < ApplicationRecord
  belongs_to :engagement

  def duration
    if check_in_completed_at.present?
      check_in_completed_at - created_at
    end
  end

  ...
end

You have probably already seen the problem. Progresses are now sometimes created long before the check-in starts. In some cases, days before. And since then, our calculations of check-in duration started failing. And that is not the biggest problem. The main issue is how hard this is to detect. Tests are green, and there’s no clear indication that the calculations are wrong until you see the actual numbers.

We thought we knew all our dependencies, but a mysterious guest appeared! We assumed that progresses would always be check_in progresses, but that’s not true anymore. Old check_in progresses are now engagement ones. Once again, we trusted the underlying object supporting our assumptions, but it changed on us.

The fix is arguably even more interesting than the bug. As a first step, we specify that we want check_in.created_at timestamp and not the progress one. Also, as a progress now is associated with an Engagement, we can change the name of the method to specify what we are talking about.

1
2
3
4
5
6
7
8
9
10
11
12
# models/progress.rb
class Progress < ApplicationRecord
  belongs_to :engagement

  def check_in_duration
    if check_in_completed_at.present?
      check_in_completed_at - check_in.created_at
    end
  end

  ...
end

Now, method name and implementation are telling us something else. All the references to check_in indicate this method probably suffers from “feature envy”, and should be in the CheckIn object instead of here. In our way of fixing an issue we found a better design for our code as well!

This is the final version:

1
2
3
4
5
6
7
8
9
# models/engagement.rb
class Engagement < ApplicationRecord
  has_one :check_in, dependent: :destroy
  has_one :progress, dependent: :destroy

  before_create -> { self.progress ||= Progress.new }

  ...
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# models/check_in.rb
CheckIn < ApplicationRecord
  belongs_to :engagement

  delegate :completed_timestamp, to: :progress, prefix: true

  def duration
    if completed_timestamp.present?
      progress_completed_timestamp - created_at
    end
  end

  ...
end

1
2
3
4
5
6
7
8
9
10
# models/progress.rb
Class Progress < ApplicationRecord
  belongs_to :engagement

  def check_in_completed_timestamp
    check_in_completed_at
  end

  ...
end

In summary, there were two main reasons for a development mystery guest here:

We trusted that objects supporting our code assumptions wouldn’t change on us. And because of that, we didn’t specify the information needed from them. (The same happens during testing when we trust fixtures or factories to have the data for us to pass the test, instead of declaring it during setup).
We optimized too early. It is simpler to call a method in the current object than to ask for the information to some other one. But even if simpler, it may not be correct with future changes in the code.

Avoid assuming that the information depending on other objects will always be as correct as it is today.

Always specify what you need. And forget about early “optimizations”. Do them when they make sense and are needed. That’s how you make sure you prevent mystery guests.

A git branching model for 15 people sharing a single testing environment

2021-04-29T00:00:00+00:00

My development team collaborates every day with a QA team to ship timely well-tested work. We work on a feature and put it up for testing; if QA passes it, we prepare it for production. Every week, after QAs perform full regression testing, we deploy to production (occasionally, they spot tricky bugs or regressions that we fix or revert).

A typical workflow, but with a caveat: we share a single testing environment (and thus git branch), which complicates preparing releases: either the shared branch contains untested code, or developers wait on QA and on each other to merge after acceptance. We tried for long to solve this from scratch by provisioning more testing environments, so that developers and QA work in parallel while the shared branch only contains tested work, but in vain: we depend on a third party that so far can’t provision extra testing environments (an Electronic Health Record –EHR– company).

How does this team of 12 developers and 3 QAs get their work tested on the one shared environment, deploy only acceptance-tested work weekly, without code freezes?

Solution zero: GitHub flow with two Epion testing environments

To ensure we’d test everything before deployments, we had two Epion testing environments (connected to our single EHR account) where we’d test branches before merge. Merging after tests guaranteed the shared branch only contained accepted work and was always deployable (the simple GitHub flow).

Commits for features 4 and 5 are on both testing environments; feature 6 awaits its turn for testing.

Two environments didn’t suffice, and we went up to four, but having them all connected to the same EHR account meant changes from one could affect others, and we started seeing more unexpected errors due to the invisible shared context. Also, we grew past four parallel lines of work.

We needed to go back to a single testing environment but still guarantee we wouldn’t block each other, and we’d release only tested work.

First solution: Parallel branches

We devised a cherry-pick based git workflow with two parallel branches:

develop contains all commits ready for testing. Developers merge into this branch as soon as code review passes; QA tests them in our single testing environment.
main contains all QA-accepted commits. Developers cherry-pick when their work is accepted, except on regression days when main gets frozen, and they need to wait.

In theory, develop was a superset of main that contained all work ready for deployment plus some untested work. When we had a handful of cards in development that we could easily track in our minds, that was true, but that didn’t hold once the team grew.

For a card requiring follow-up commits, the developer may forget to cherry-pick all of them once accepted. Or a dev-only kind of task (sometimes dependency upgrades) would be invisible to QA. We’d apply it to develop and forget to port it over to main, erroneously believing that the production version of our code had the commit. As branches diverged for long, it got harder to spot such differences.

Features 4, 1, and 2 were accepted and cherry-picked (copied) into main.

Other issues with this workflow:

Deploying any work to production involved committing twice
The team needed reminders to move accepted cards over to main
Occasionally we’d wait for a commit that needed to go out that week, delaying regression testing and resulting in long workdays for QA
Irrelevant merge conflicts arose due to different commits order on each branch
The process’ complexity prompted more questions, like:
- Do we squash fixups in main, so it ends up being a single, revertable commit?
- How do I know when main is frozen, or can I commit now?
- Do we cherry-pick from the feature branch we worked on or from develop?

As we started developing more projects in parallel, we needed to decouple deployments from testing. Our work is accepted straight out of the bat two-thirds of the time. Developers should forget their work as soon as they merge, two-thirds of the times.

The new proposal: Weekly release cuts

We “cut a release” every Tuesday at midday, no questions asked (even with not-yet-accepted commits). That day QA focuses on the untested cards that made it into the cut, so on regression and deploy day, all cards are Accepted (or reverted) as was guaranteed by our previous workflow. We run deployments the following day.

If a developer merges work after midday, it will miss the week’s “deploy train” and appear on the following week’s release (features 4 and 5 in the diagram).

Release cut on feature3 by moving main onto it; develop continued moving forward. QA tests feature1 and 3 first.

Advantages over the first solution:

The happy path is “don’t make me think” simple. If a card gets accepted, it will reach production in less than a week
Developers don’t need to interact with main (unless preparing a deployment or they need to revert)
QA can start regression testing a day before, decreasing the chance of rushed deploy days
No code freezes; developers can always merge their work

Given we cut the release a day (instead of hours) before regression testing starts, develop usually contains Accepted commits during deploy day that won’t go out to production until the following week. The clear deadline has forced developers to try getting their priority work earlier in the sprint to maximize the chance to see production on time, alleviating the QA team’s work. But we rarely have such urgent tasks. This process helped us see that a commit can go out next week even when ready today, which is not a problem for our teams or clients as we used to feel.

When we need a task out the door after the release cut time, we perform a smaller deployment the next day with that commit (with scoped down, faster regression testing) or postpone regression testing and deployment one day.

As a disadvantage, if QA rejects a card that made it into the release, the developer must revert the commit from main or prepare a (risky?) fixup. Our first solution specified reverts too, but we usually added fixup commits instead, given parallel develop wasn’t under pressure. We began using more feature flags to turn off features dynamically, mitigating the need for git revert. A good practice for sure, but our team didn’t feel the need for them before and gladly incorporated them.

This solution is closer to git-flow but:

Without release branches. We maintain a single version: the one that currently runs in production, so “release” and “main” mean the same thing for us (we don’t need to backport bugfixes)
Adding our definition of when develop “reaches a stable point and is ready to be released”. The first solution was “never”, and now it’s when we merge to main and ask QA to prioritize untested cards in it.

We’ve been running on this new workflow for a couple of months now. QA regression testing isn’t as rushed as before; we know all commits we intend for production are there; developers don’t need to wait to merge, or double-commit all their work.

If you find yourself in the unlucky position of needing to share fewer testing environments than lines of work, give this git workflow a try, it may help your team too.