With a Twist

One Telegram contact to rule my team of AI agents

2026-06-04T00:00:00+00:00

Siri doesn’t understand Argentinian Spanish. I have to pronounce some words in a neutral accent, which sounds weird here, and my toddlers learn it as local, or write them out, navigating the awkward iOS cursor, or tap each letter and then correct typos. I use calendar, timers, notes, and reminders as anyone else, and I’ve been a “tech person” since my early years.

So I was surprised by my own surprise when Fede, my brother-in-law, repeated my ask to his Telegram agent: “remind me to pick up the kids at 11:30”. Well that was simple, and it wouldn’t rely on our memory. He didn’t write or pronounce how Siri expects, he just said my words to his phone. I’ve long wanted to schedule calendar events via voice while on the go. Siri promised this for long too, but it never quite delivered.

Three weeks later I had five specialized AI agents running on my iMac under an orchestrator.

Need zero, pick an agent architecture

I’ve been meaning to implement agents but struggled to pick a solution.

RubyLLM looked too low-level (last month): I was looking for a simple system but with predefined structure. It’s quickly evolving though
OpenClaw is powerful but ginormous, a big bundle of prompts, and I would never fully control the details of its functioning
NanoClaw seemed closer to what I’d like, but if it’s so simple, why not roll my own from scratch?
My own from scratch: where do I even start?
Mastra, a TypeScript framework for building AI agents, initially felt like much more than I needed. I eagerly watched Damian Galarza’s videos, but I couldn’t predict what exactly each dashboard item does

My ex coworker Anthony Costanzo provided an onramp I needed: he built his Batcomputer from the ground up, and shared his notes. He used familiar tools for programmers: a long-running Claude Code session within tmux, reachable via Telegram with Tailscale, launching on boot using macOS’s LaunchAgents, and a directory of markdown files for memory with auto-commit. This was right up my alley, it would help me delineate what “my own agent” even means.

I added voice note transcription via OpenAI’s whisper, registered a Google account for my agent (Dino) with API access, and a new macOS non-admin user on my iMac for isolation.

Dino also sends me a daily morning brief with my schedule and unread emails. It can also send emails, but with this implementation I worried it may spam people even though its prompt said “don’t without my consent”. A prompt does not suffice to guarantee such rules.

I gave him readonly access to my email and calendar: I don’t want an agent to impersonate me, nor do I want it to exfiltrate or commit mistakes with my data.

It worked, but showed rough edges:

Screen-scraping tmux couldn’t distinguish a tool working from a finished response
Adding a second agent meant a second tmux session, a second polling loop, and hand-rolled connections between them
Multi-turn context lived only in the pane’s scrollback buffer
Memory wasn’t efficient
Iterating on prompts and testing them with real usage felt like when I updated PHP websites before learning about automated tests

It proved the concept: a personal agent I can configure with precision, reachable from my phone, understanding both my English and Argentinian Spanish. But I wouldn’t grow it on that early foundation.

I took another look at the implementation options. I rewatched Damian’s videos on Mastra and now it clicked. “Framework” means decisions taken for me, in this case proposing a sensible structure. Mastra has a declarative API that makes for readable code. I rewrote Dino in Mastra. And now I could understand its features.

Like, add a “Human In The Loop” approval requirement before sending emails. Now I can comfortably ask Dino to try sending an email, inspect what it plans to do, and only then approve the operation or request changes.

First need: Maybe a second agent

As Dino proved its worth, I started asking more of it. It started remembering how I use calendar, email, Telegram, plus the communication styles I prefer. And it began mixing preferences up.

Another problem: every request was handled by the smart (and expensive) LLM model, but some simpler operations can be done by cheaper models, in turn faster.

On May 10th I split an orchestrator and a worker. Manuel became the smart orchestrator handling Telegram conversations, memories, and deciding delegations. Dino kept its calendar and email fu, becoming a simpler, more focused utility agent who knew one thing well. Dino doesn’t have much of a personality or agency, but boy does it fill event details and invitees from my natural language instructions properly. No forms, double verification of whether I’m picking the right week, or timezone musings needed anymore.

This pattern unlocked everything that follows.

You may think: how do you keep track of names that don’t even have faces? I don’t. I have a single Telegram contact to access everything: Manuel. I say what I need in either language I’m using, and Manuel routes it. I couldn’t build a simpler UX for this functionality, and that’s why it sticks unlike other “intelligences” and apps I’ve tried before.

Second need: self-improving agents

Sometimes I’d ask Manuel to make changes to the project itself:

“Fix all-day events time boundaries.”
“Add support for recurring events”

Manuel would counter he has no tools to write code. I’d sit on my computer, copy the failed request into Cursor, and redeploy.

On May 14th I added Topo, a sub-agent with Mastra’s Workspace API, allowing access to the project’s directory and to relevant shell commands.

I can now tell Manuel to add a capability to an agent, and it’ll delegate to Topo. The sub-agent implements it, and reports back the generated commit SHA as verifiable evidence of work (without it, LLMs can and will report back enthusiastic success with no changes done).

The friction between “I want this feature” and “the feature exists” dropped to near zero. And in my agents team I optimistically let it deploy its changes: most often it works, and when not it’s easy for me to roll back or fix. I still review all commits to tweak anything needed and to learn, but not before letting it update itself.

Third need: invoicing for my company with Tito agent

For my company each month-end I have to:

Review each client’s GitHub repos and task managers to gather links to work done
Write a monthly report summarizing all
Generate and email an invoice
Commit compiled notes to my railspilot-documents repository

It’s not a terribly laborious or time-consuming task, but it did distract me the last days of each month with something that didn’t seem to deserve my time. That feeling again, this mustn’t be hard to automate well.

On May 29th, via Telegram request to Manuel, I created Tito, a RailsPilot bookkeeper agent with a RailsPilot-documents workspace. Tito reads clients.yml to list clients and their relevant URLs, fetches merged PRs via git log and GitHub CLI, tasks to my name from their boards, writes the report, generates the invoice, and pushes its changes. I say “May reports” and it does the work, I review the diff, apply small adjustments, and send.

Each client also has a status file that both Tito and I keep up to date, so it can tell me what’s next for each client, and any deadline to keep top of mind.

I speak with clients and interpret their needs, which I try to fulfill as well as I can. I love that work. Tedious tasks that are easy to delegate shouldn’t eat into it.

Fourth need: lights on when I pull into the driveway

The underlying need was implementing yet another agent. Now I got greedy. Lower value than the previous one, yet still satisfying.

I have SmartLife (Tuya) smart switches for some lights. Some evenings I arrive home and enter through the back door, and it’s too dark to find the right key. I would pull my phone’s SmartLife app, tap the very small button next to “Kitchen Lights”, and enter.

On June 3rd I added Jaime, an agent who talks to the Tuya Cloud API to control light switches. Now I tell Siri via my car “phone” button to Telegram Manuel:

“Encender las luces de la cocina”

And it does, while I park. It’s fun, simple, helpful, and has that “wow factor” that lets people who never thought of agents (and who will never read this blog post) see what they can do. Like my brother-in-law when he offloaded a reminder to his agent while waiting for a traffic light.

Jaime may be a shallow and simple agent. He’s still as smart as his Haiku model: he interprets “kitchen”, “all”, “back” or “exterior lights” without me having to predefine groups in an app. People could have done this with Siri, Alexa, and others for years, but while I know many who own them, I know that one weird person who actually uses them in daily life. She also sells them. But almost everyone I know uses a chat app like Telegram every waking hour. The user experience is so much better.

Fifth need: writing this article (Fede)

I called this one Fede, honoring my brother-in-law’s blog. I’m glad he started it, I’m quite enjoying it and you may too.

When I thought of writing this piece, I first built a subagent to draft it in my voice. It has:

Read-only access to this Mastra code so he could inspect and describe it
Email tool via Dino to email drafts when done (Manuel’s approval button goes through Fede to Dino. After a bug fixed in Mastra, it works surprisingly well)
Instructions about my voice, audience, and topics I cover

I told Manuel (typo included):

“Plese write a blog post describing this project”

He delegated to Fede, who read the git history and agent definitions, and wrote two drafts of this post.

Lessons I took, and next steps

Specialized agents beat one general agent. When Manuel started delegating, every interaction got more fruitful. Each agent has a focused set of tools, specific instructions, and a model tuned to its task’s cost and complexity. Focused agents are easier to debug and simpler to extend, like classes in Ruby.

Evidence over claims. Dino has to pass a proof of work before reporting an event created. If it says “done, I scheduled X” but the response doesn’t include the event ID, execution fails and the task is retried. Same principle for Tito and git commit SHAs.

Memory is a sharp tool. Subagents have memory disabled except for the current thread. Memories add to their context, and when not relevant it can lead them astray. The relevant context is in the tools, not in past conversations. Manuel does have memory, because he orchestrates: he may need to edit an event just created, or retry a task that didn’t properly finish.

A friend asked me: who should use agents like these? Pretty much everyone I know. Anyone with a job that has routines will benefit. “This is tedious, could an agent help me do it?” The answer is most often, yes.

The pattern works: identify a repetitive task, design and implement an agent and its tools, and assign it tasks. If you want to build something similar, start with one agent and one real problem. Try Mastra. Tell me how it goes!

Some technical notes if you care for more detail

Summary of my AI team so far, their tools and models:

Agent	Role	Model	Key tools
Manuel	Orchestrator	Opus	Telegram, memory
Dino	Assistant	Haiku	Calendar and email
Topo	Self-improvement	Opus	Workspace, shell
Tito	Invoicing, progress	Haiku	GitHub, file system
Jaime	Smart lights	Haiku	Tuya Cloud API
Fede	Writing drafts	Sonnet	Email via Dino

The system runs on my iMac as a macOS LaunchAgent under a dedicated user account. Secrets live in 1Password, loaded as ENV variables at runtime. Telegram webhooks reach Manuel via a Tailscale Funnel. I’m using about $60 a month in API usage with it, it feels very high value for low cost to me. I expect to grow this system with more responsibilities, and learn about evolution, and maintainability. I’m particularly curious about evals: how do I know an agent is doing its job well beyond “it seems to work”? That’s my next path.

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.