You know your interview stories. But can you tell them clearly under pressure?

Most engineers prep by writing notes. But writing isn’t practice. Revarta gives you live audio interviews with follow-up questions and feedback on what’s actually landing.

Built by a hiring manager with 1,000+ interviews at Amazon an…

Read more

If you aren’t familiar with Ethan, he’s a prolific writer and content creator. I’ve also written about his Maven course, which I took and recommend if you’d like to build your e…

Read more

Today’s article features a special guest, Colin Matthews, instructor of multiple top-rated AI courses on Maven. In this article, you’ll learn how to build ChatGPT apps, enabling you to embed your code directly into ChatGPT.

Since this article is highly detailed, I’m sharing Colin’s links that I recommend expl…

Read more

Running engineering shouldn’t feel like firefighting. Missed deadlines, hidden bottlenecks, and endless status meetings kill momentum. DevStats changes that.

DevStats makes it simple:

✅ Align engineering with business goals
✅ Keep delivery predictable and on track
✅ Spot bottlenecks early and keep delivery flowing

Wi…

Read more

The HubSpot Developer Platform gives you the tools to build, extend, and scale with confidence. Create AI-ready apps, integrations, and workflows faster with a unified platform designed to grow alongside your business.

Build AI-ready apps

Thanks to HubSpot for sponsoring this week’s newsletter!

Read more

Your devs waste time on internal support tickets. Marketing is blocked. Your roadmap is drowning in “quick fixes.”

We built the Directus MCP so you can connect the AI tooling of your choice to your backend with guardrails. Your permissions, your schema, your control.

Now? Marketing can ship content without tickets. Dev…

Read more

Augment Code is built for real engineering teams. It understands your codebase across 10M+ lines, 10k+ files, and every repo in your stack—so it can actually help: writing functions, fixing CI issues, triaging incidents, and reviewing PRs.

All from your IDE or terminal. No vibes. Just progress.

Ship code faster 🚀

Read more

Up to 4.25% Annual Percentage Yield (APY) on your cash. No monthly fees. No minimums.

Wealthfront’s high-yield Cash Account earns 9x the national average interest rate of a typical savings account by providing a 3.75% APY through program banks – one of the highest in the market – on all your uninvested cash. They…

Read more

In this part, I’ll share the guiding principles that helped me build influence to mak…

Read more

Augment Code is built for real engineering teams. It understands your codebase across 10M+ lines, 10k+ files, and every repo in your stack—so it can actually help: writing functions, fixing CI issues, triaging incidents, and reviewing PRs.

All from your IDE or terminal. No vibes. Just progress.

Ship code faster 🚀

Read more

If you're building AI applications, securing identity and access is just as important as the models themselves. Scalekit gives you a tool calling infrastructure and ready-to-use auth for AI apps — without any custom plumbing.

You get: Dynamic client registration, verified JWT tokens, scoped access, per-user per-…

Read more

If you’ve been curious how AI can help in your day-to-day engineering work, I highly recommend Formation’s Ship Faster with AI course.

You won’t just read about AI tools—they walk you through real problems you actually face on the job, like working in large codebases, generating useful tests, and breaking down complex tasks. Plus, you’ll get regular interactive mentorship from experienced engineers, like the famous L7 “Code Machine” at Meta, who’ve been applying AI to their workflows.

They’re running exclusive early access pricing, and most companies will let you expense it. It’s definitely worth checking out.

Enroll by August 17

How can you tell when another person is lying to you? Well, you either know what they’re saying is wrong, or you have a feeling. What gives you that feeling? Your instincts, from when you’ve been lied to before, or a sign, like fidgeting, looking down, looking away, or just acting different. Ok, but what if the person lying is a master at lying? It’s a lot harder! They don’t show any differences in behavior, and they’re confident about what they’re telling you. AI, as amazing as it can be, is just like that, and IS a master at lying.

It can lead you in the wrong direction and be incredibly confident about what it’s saying. You believe the set of commands it tells you to run, you’re going back and forth in a conversation with the output you’re seeing, only to realize later that AI dug itself in a rabbit hole of lies because it misunderstood what you wanted.

If you’ve experienced this, you’re not alone. I use AI 25+ times per day, and it generates 75%+ of my first draft code before I review and edit it. I’ve seen it lie and misunderstand what I wanted plenty of times. Some people would throw up their hands and say, “I’m not dealing with it if it’s going to make things up.” But don’t do that! Once you learn a few tricks to tell when AI is leading you in the wrong direction, you can safely reap the 10x+ promise of it.

Who doesn’t love a little adventure to get to a treasure? 😄

To learn how to spot when AI is misleading you, we’ll first dig into the fundamentals of how it decides what to tell you. Knowing this, you’ll know where its responses are coming from, which will make you a more confident lie detector. Then, we’ll go into 6 battle-tested ways to catch AI in the act of lying, red-handed.

Let’s begin!

Know these aspects of how AI works

1) AI is a glorified autocomplete

Before the days of AI, googling was the primary way anyone found information. You’d type your question into Google, a bunch of articles would come up, and you’d sift through them for 10+ minutes until you found something you were happy with.

Now, AI exists and bridges that 10+ minute gap, so you no longer need to look through all those articles yourself. It’s already done that work for you. It’s been trained on a curated set of the internet.

BUT, there’s a huge problem. It doesn’t think. At least, not in the way humans do. It’s a probability machine. It predicts the probabilities of the next word, and generally gives you the next highest probability word, based on its training of the internet. It’s only thinking one word (or token) at a time.

So, if in training, there was a highly reputable source with just 1 question and answer pair, but there were 1000 other pairs saying something different from non-reputable sources, AI might give you that non-reputable answer. Now, most companies apply higher weights to authoritative sources, but it’s also probably not perfect either.

You can think about AI as a probabilistic parrot (as mentioned in the talk above). It repeats what it has heard before. If in training it hears something wildly inaccurate over and over again, eventually it will just start repeating it.

Taking an example, let’s consider how AI comes up with a response to:

“What is the best way to structure a React application?”

There’s no objective way to say one way is “best,” and there are tons of different opinions online to answer this question. So when it gives me the response like this:

Jordan — short answer: use feature-first, co-located files, and strict module boundaries. Treat “app shell” as plumbing and “features” as the product. Everything else is shared utilities.

It’s giving this by approximating the most common recommendations, often by authoritative sources in training data. Not because it truly is the best and correct answer. And it might even respond differently based on how you word the question or if you ask enough times.

AI effectively combines billions of data inputs and tries to boil that down into a concise response. Those billions of inputs come from sources like Stack Overflow, help forums, Reddit, and blog posts, among others. That’s why it struggles with bespoke code or patterns it hasn’t been trained on. Once you think of AI as combining its training inputs behind the scenes and responding based on probabilities, you take less of what it says for granted and start questioning where it’s getting what it said from, because it’s not its own experience like your tech lead. It’s a combination of the world’s experience, which is good sometimes, and not-so-great other times.

2) AI is often a “helpful assistant”

System prompts tell AI to be a helpful assistant; however, this leads it to be too helpful. The out-of-the-box system prompts in most systems lead to AI trying to give you an answer even if it’s incorrect, rather than telling you they don’t know.

We can see this in the Claude 3.7 system prompt:

Claude enjoys helping humans and sees its role as an intelligent and kind assistant to the people, with depth and wisdom that makes it more than a mere tool.

That’s why adding “Be honest if you aren’t sure” to your prompts can help Claude avoid being too helpful in trying to give any response, and know that it’s ok to say “I don’t know.” Without it, an AI can’t distinguish what “helpful” means—is it giving you an answer, even if it’s incorrect, or is it being honest about factuality?

On top of providing any answer, the “kind assistant” instruction can make Claude too nice, trying to make you feel good about everything you say—leading to, “Oh, I’m sorry. You are absolutely right!” even if there’s more nuance to it for Claude to then further correct you.

For that case, I add “Be brutally honest” to my prompts, particularly when asking for feedback.

Be brutally honest. Is this approach the best way we could do it or are there other better ways?

I’d say that for an approach I recommend to AI, or an approach it came up with on its own. Without it, I noticed AI wanted to appease me with things like, “It’s definitely the best approach!” without actually thinking deeply about it.

Caveat: Newer models are better at being honest, particularly for high-confidence questions with lots of training. For example, you’ll have a hard time getting newer models to agree that 2+2=5. However, this tip is helpful for areas AI has lower confidence, like your codebase, where it would typically default to trusting you more because it wasn’t trained there.

Know how to catch AI lying, red-handed

Now that you’re armed with how AI works, let’s dive into ways to catch AI red-handed.

1) Use AI with sources where possible, then check them

Verify AI’s sources. As we mentioned before, AI is effectively a refined Google search. It eliminates the need to sift through many articles and piece information together. Some models and interfaces display sources, and I highly recommend quickly verifying the response AI gives you.

In the past, I mistakenly assumed that because AI provided sources, it couldn't be lying. Wrong! AI may mistakenly associate two distinct pieces of information together, making the statement incorrect. For example,

You: “Use deep research to find me companies that improved their build speeds by adopting new Github action runners.”

AI: “Stripe improved their build speed by 65% by adopting Github action runners (source).”

But when you check the source, you find that yes, Stripe improved their build times, but it doesn't necessarily say it was because of those new runners. The 65% was an aggregated stat across many changes Stripe made, with the new runners as only one change out of ten. AI tried to give you what you want, but was dishonest about it.

This problem was researched, showing LLMs have difficulty creating accurate citations, highlighting the importance of actually verifying the source.

Large language models (LLMs) such as DeepSeek, ChatGPT, and ChatGLM have significant limitations in generating citations, raising concerns about the quality and reliability of academic research. These models tend to produce citations that are correctly formatted but fictional in content, misleading users and undermining academic rigor.

2) Understand programming fundamentals

When you use AI, you’re often on one of two ends of a spectrum.

1. High control: You know what needs to be done. AI is a tool for bringing your vision to reality. It’s acting as an intelligent junior engineer that can type 1,000 words per minute, rather than being limited by our typing speed.

2. Low control: You don’t know what needs to be done. You’re relying on AI to tell you what needs to happen and what files to edit.

Ideally, you’re often closer to the “high control” side. Having more control in your hands prevents AI from going off the rails. Being in “low control” mode is akin to someone outside your team making a code contribution who isn’t familiar with the right places to edit, nor the proper conventions your team has set, and why.

Understanding programming fundamentals enables you to be in “high control” mode more often, with more confidence.

I don’t want to leave you with that, though. You need to know which fundamentals. In my experience, these have been most valuable for me:

1. For checking AI’s commands…

   1. Most common bash and shell commands: cd, ls, cat, xargs, grep, rm, rmdir, chmod, sudo, etc.

   2. Interacting with git and Github: add, bisect, diff, blame, push, clone, status, stash, reset, revert, merge, rebase, etc.

   3. Other coding basics: Language syntax, error handling, clean code, immutability, performant loops, secure code.

2. For giving AI instructions…

   1. Debugging strategies: See 12 debugging tools article.

   2. Testing strategies: Unit, integration, end to end, mocking, spying, test setup and tear down.

   3. Common algorithms, data structures, design patterns: Observer, strategy, factory, builder, adapter.

   4. Common scripting patterns: Reading files, writing files, checking truthyness, piping and transforming data and outputs, using loggers

   5. Where code runs: Local vs. CI, how deployment happens, containerization and Docker

If you know these, you’ll be able to confidently tell AI what you want it to do, verify what it did was the best way it could have done it, and more easily tell when what AI told you was wrong.

3) Understand what context it has and doesn’t have

You should know what the AI you’re interacting with is trained on. A basic example of this is if you open up ChatGPT and ask it questions about your codebase, you might get it to start guessing and telling you about your code—but it obviously knows nothing about your codebase, unless it’s open source, because it was trained on publicly available data and sites.

This problem is present in every AI interface. You need to know what context it does and doesn’t have. That’s why you can’t ask the AI in your IDE (agent mode) to “ship xyz feature” at your company, expecting it to find the product requirements, technical design doc, all the JIRA tickets, etc. That’s what Model Context Protocol (MCP) solves. It provides a standard interface to give AI access to all of those tools. But if you don’t have that MCP hooked up, expect AI to lie to you or tell you it doesn’t know.

Additionally, its training is also time-bound, typically to about 6-12 months ago. It can’t answer questions about today’s news without using tools to give it additional context, like Web Search. So if you’re asking a model about the news today without that tool enabled, it might lie to you.

For practical programming use cases, you may see it struggle to help you with new tech, because it won’t know about it at all, and won’t have been trained on what people say about it.

Watch AI’s thought process for clues. It might provide subtle hints like, “The user asked me this, but I don’t have access to this, so I’m going to tell them something different.” Seeing the thought process gives you clues into what context you did or didn’t provide.

Ensure it uses the tool calls you expect. A common tendency of AI is that it doesn’t correctly identify the tool calls it should use to help it gather more context. Two common examples are:

1. You ask it to explain a set of files, and instead of using its file reading tools, it makes guesses based on the names of the files

2. You ask it a question about internal company knowledge, but it doesn’t correctly identify it needs to call out to an MCP tool for that knowledge

The best way to overcome this is to observe its process, identify the tools it’s using, and tell it the mistakes so it can correct them.

Always view working with AI as a collaborative process with a partner, and at least in the somewhat early stages we’re in, expect it to make these mistakes for now. It can only get things right the first time sometimes, and definitely not all the time.

4) Tell AI it’s ok to say “I don’t know”

As we covered earlier, AI systems are trained to be “helpful assistants,” which creates a strong bias toward always providing an answer, even when they’re uncertain or lack sufficient information. This leads to confident-sounding responses that may be completely wrong. You also don’t know the probabilities it had for each next word it came up with. It could have lacked confidence, but it didn’t come across that way in its response.

To fix this, you can tell it any of:

“Be honest if you aren't sure about any part of this.”

“It’s better to say ‘I dont know’ than to guess.”

“If you don't have enough context to give a confident answer, just tell me what additional information you'd need.”

This counteracts potential training where it would have been rewarded for sounding confident and the effect of being a “helpful assistant.” It’s more important to use this when you’re working in areas AI may not have been trained in or doesn’t have the tools available to pull in the context it would need, often when working in internal systems. Using the above prompts in the system prompts for agents has been really helpful in getting AI to just say, “I don’t know” rather than provide an incorrect, time-wasting response.

I also like the third prompt of telling AI it’s ok to ask for additional information. I’ve noticed it does a great job using second-order thinking to not just answer, but also consider additional areas where it could improve if it had more information. In practice, it would look like:

“I’m seeing this bug in <x> system, and I think it’s related to <y> folder, but I’m not sure.

Can you look into it and tell me what info you’d need from me or what commands you’d want me to run to give you more info to figure out what’s wrong?”

This makes it a much more collaborative process, rather than AI trying to give you what you want on the first try but getting it incorrect, and then potentially continuing down that invalid rabbit hole.

5) Get a different AI to verify that AI

Once you get a response from AI, you can ask another AI what their thoughts are, and it will start from a fresh slate without any preconceived ideas based on the context that was gathered already.

Think about it like going to a second doctor to get another opinion on what the first doctor found.

To test this, I did the following:

Me to AI 1: Write me an algorithm in javascript to determine when I have a day with meetings that doesn't allow me to make time for the gym and how I can restructure my day with the minimal changes possible. I can't go to the gym unless I have a 75 minute gap between meetings

AI 1 to Me: <responds with the algorithm>

Me to AI 2: I have the following algorithm to help me determine how I can minimally restructure my day to have a 75 minute slot for the gym. Can you verify and check it for me and what changes you would suggest to simplify it?

< pasted algorithm >

It found many mistakes, and one was particularly easy to spot. It had an unused parameter that was totally pointless and just passing `null` around. When I asked the original AI to spot-check itself for mistakes, rather than a new AI, the original AI did not find the same issue.

It’s possible it could have found it, but my hypothesis is that a bias was introduced because it wrote the algorithm itself. That bias isn’t there when asking a new AI. Personally, I view it similarly to how I give much better feedback to my own writing and code after sleeping on it for a day, rather than just after drafting it, when I often feel proud of what I just did. That additional level of separation allows me to give better, unbiased feedback to myself, and it seems like AI works similarly.

Research from MIT also supports this with its similar “debate” approach:

We illustrate how we may treat different instances of the same language models as a “multiagent society”, where individual language model generate and critique the language generations of other instances of the language model. We find that the final answer generated after such a procedure is both more factually accurate and solves reasoning questions more accurately.

6) Ask the right questions

There are many questions you can ask AI to verify its work.

Here are my three favorites:

What process can I go through to verify what you did was correct? Briefly provide a step-by-step summary

Doing the process yourself will give you the most confidence, and ultimately you want AI to show you how it did what it did, so that you can verify it. This prompt helps you do just that by allowing you to verify it step-by-step and check what it might have gotten wrong.

Can you write a test to verify what you did worked? Then walk me through what the test is doing

In the past, this has had mindblowing results for me, with AI writing complete, isolated, idempotent test scripts that can prove one point or another. For example, I wanted to compare how Docker builds performed under one set of commands vs. another, and it created two separate Dockerfiles with the relevant parts switched, set up timing code, and made a runnable test script.

You still need to verify what the script is doing, which goes back to the programming fundamentals point, but it’s a great way to get further along with verification. I’ve still found that using AI’s output + verifying it has been faster than me doing it all myself.

What assumptions are you making that I should verify?

AI will always “fill in blanks” based on the information you do or don’t provide. It’s nearly impossible for you to give all the context, all the time. Knowing that AI will make assumptions, and sometimes get those wrong, is what this prompt helps with.

It gets AI to be explicit about the assumptions it made, so that you can correct it. In my case with the Docker example, it assumed a few things about the environment setup that weren’t initially true, but I helped correct it after asking this question. Next time you want to check AI’s work, try this out!

📖 TL;DR

• Know how AI works under the hood

  • AI is a glorified autocomplete. View it as a probabilistic parrot, repeating the most frequent points said across the internet. That may or may not be what you’re looking for.

  • AI often has the role of a “helpful assistant.” The default system prompt in most AI interfaces can lead to it giving you any answer, rather than the correct answer. To combat this, tell AI to be honest about answers it doesn’t know.

• Know how to catch AI lying, red-handed

  • Use AI with sources where possible, then check them. AI can incorrectly tie two distinct pieces of information together.

  • Understand programming fundamentals. Knowing the fundamentals helps you stay closer to the “high control” spectrum and enables you to more easily verify what AI tells you.

  • Understand what context it has and doesn’t have. By knowing what context it has, you can know if the answer it gave you was made up or based on reality.

  • Tell AI it’s ok to say “I don’t know.” Without this, its training may lead it to give you an incorrect, confident-sounding answer rather than being honest that it isn’t sure.

  • Get a different AI to verify that AI. When you start fresh, it removes the preconceived notions from past responses and context. The new AI will give better feedback and be able to more easily fact check the original AI’s response.

  • Ask the right questions. You can ask it what process you can go through to verify its correctness, ask it to write a test to verify itself, or ask about the hidden assumptions it made.

👏 Shout-outs of the week

• 10 Leadership Lessons from 10 Years of Parenting by — Timeless leadership lessons with a fun personal anecdote for each lesson

• A project prioritization framework by Sidwyn Koh on

  Path to Staff Engineer — A great way to figure out what to work on for the highest impact and growth opportunities.

• Curation newsletters - check out by Alexandre Zajac for a solid set of curated, weekly articles in tech. High Growth Engineer is a frequent shout-out!

Thank you for reading and being a supporter in growing the newsletter 🙏

You can also hit the like ❤️ button at the bottom of this email to support me or share it with a friend to earn referral rewards. It helps me a ton!

I tried Lovable this week and created a personal toolkit for myself in less than 10 minutes. My tool handles common tasks like converting timestamps to date strings, converting YAML to JSON, string transformations, and more. Lovable is super flexible, so you can use it to build whatever you want.

I recommend checking out Lovable and automating something you do often, or building something totally different! On their homepage, they have a showcase of other apps people have built as inspiration.

Build anything 🚀

This is the tool I built for myself. Thanks, Lovable, for sponsoring this week’s issue!

It’s been a while since we picked up the “Communicate like a Senior” series. If this is your first one, strap in for an overwhelming amount of actionable tips! I’ll also share past issues in this series at the end.

Today, we’re diving into the art of providing both the right context and the right amount of context. Great communicators are masters at this, which means they get unblocked faster and build more trust with their teammates.

You’ll learn the 6 most important areas to provide the right context, where people often make mistakes, and what to do instead. Let’s start!

(1) Tagging someone in a long thread

Tell me if you’ve seen or been on the receiving end of this before:

Now, I’m usually a big fan of the “What do you think?” question, but not here! Not in a long Slack thread with no context. By doing this, you’re putting the entire burden on the person you’re tagging to read through the thread and figure out what you’re asking.

When that happens, the person you tag either won’t respond, will be bothered, or ask for a summary of the thread and what you’re asking. All of these are negative interpersonal outcomes and increase the number of feedback loops for the person being tagged to help you. If you’ve done this before, don’t feel bad. I definitely have and sometimes need to catch myself when I’m thinking and working quickly.

To fix it, here’s what to do instead, shown through an example:

Hey @Person, we’re discussing <x> and are currently at <y> on the decision.

We’re wondering whether you think we should go with <a> or <b> based on these considerations.

<list out considerations>

Let us know what you think and if it would help to provide more context.

This message is much better, but why? The high-level principles are to:

1. Get to the point quickly on what you need help with. In this case, it’s a decision between two choices.

2. List a summary of additional context below the main point.

3. Offer to provide more context if needed. This shows you are considerate toward tagging them in a long thread that they might need to catch up on.

By doing these, the person tagged isn’t burdened with reading the whole thread, so they appreciate the effort you put into the clear ask. Plus, they can answer right away, with fewer feedback loops, meaning you get your answer faster and can move on.

(2) Pull requests

As engineers, we all want our pull requests to be merged faster. It feels good. You’re getting things done. But in trying to move faster, it can actually slow you and your teammates down in the future.

For example, consider if you put up a pull request and in a rush, barely provided any context in the description, and the changes themselves weren’t clear on why they were needed.

A teammate begins reviewing, and they have tons of questions:

• “What’s the context behind the change?”

• “Why do we need to touch this file?”

• “What is this line changing?”

Now, you end up in back-and-forth mode. You’re spending time responding to each question, and it’s harder to communicate the context since they’re all in separate comments, rather than a clear description from the beginning. Then, after you respond, you need to wait for a second review round, which may take another 4 hours.

Finally, they get around to it and understand, so they approve the changes. However, all of that could have been avoided if the context had been there from the start. So when you’re writing pull requests, follow these tips:

1. Explain why: Every change has some reason for it. It could be that an engineer complained and started a thread, or a customer complained, or performance is bad, or we’re seeing an increase in errors. Whatever it is, list it.

2. Link the why: It’s not enough to just say the why. Link to the context so that a curious reviewer can check it out for themself. This is typically a Slack thread, JIRA, Google Doc, customer report, or screenshot of a bug happening.

3. Self-review and comment on your code: Review your own code, check for silly mistakes like leftover console logs, and comment on anything you see where someone might ask, “Why are we doing it this way?” or “What is this doing?” This is particularly helpful if you get reviews from people who aren’t actively working in your domain area.

Doing these not only gets you faster reviews, but also saves you and your teammates time when revisiting the code 6-12 months later and trying to remember why a particular line is the way it is.

(3) Asking someone for help

When asking for help, make helping you as easy as possible.

Let’s work from an example of what not to do:

❌ “Hey, the code you shared earlier isn’t working. What should I do?”

Now, this is actually a perfect starting point—but definitely not what you should hit send on. To improve this, you need to work backward from what the persons next question will be.

In this case, it’s likely, “What is not working about it?”

So we improve it more:

⚠️ “Hey, the code you shared earlier isn’t working. The error is <x>. What should I do?”

What’s their next question? It’s likely, “What have you tried so far?”

So we improve it more:

✅ “Hey, the code you shared earlier isn’t working. The error is <x>.

I’ve tried to do <a>, <b>, and <c> so far, but they all result in the same error.

Do you have any other ideas?”

This is much better. It answers all the upfront questions the person would have, and gets right to what you need from them, which is whether they have any other ideas on what to try.

Additionally, there are a few bonus tips. Often, you’ll be asking for help from busy people who may be managing 3-6 contexts at once, so even saying “the code you shared” could be unclear. I know this because I’ve had the person I’m asking for help tell me they have no idea what I’m talking about, even though they only shared their suggestion with me the day before. To account for this, add hyperlinks and screenshots to the relevant parts that would make it easier for them to quickly gather the context and help you.

In this case, if they shared the code with me via Slack, I would hyperlink “the code” to their Slack message. Or if I already pushed the code to Github, I might hyperlink it to the file on Github where that code is like this, then hyperlink their message to the “shared earlier” part, like this:

“Hey, the code you shared earlier…”

This way, they can get all the context they need purely from everything you provide in the message, without having to scroll up in Slack or find your branch on GitHub.

Additionally, share relevant screenshots, draw arrows, boxes, and write text on the screenshots to communicate it even more clearly.

Combining all of these makes your message crystal clear and makes it a joy to help you out, which gets you answers faster.

(4) Asking a support channel for help

Now, let’s consider the same situation, but in a support channel rather than DMing someone directly. The dynamics change slightly because the amount of context that any given person has in the channel is low, compared to when you're messaging a person directly—they likely have medium to high context on what you're asking and working on.

All the same principles and tips from the previous step apply, but there are two more to keep in mind. Let's assume you want to ask something like:

❌ “How can I build an AI agent in CI?”

From this question, you’re likely to only be met with confusion. But why? For two reasons:

1. Specificity: The question is not specific. It’s not clear what you’re trying to do.

2. Motivation: They don’t understand why you’re doing it.

On specificity, both “AI Agent” and “in CI” are unclear. Agent is an overloaded term and can mean so many things, so you really need to dig into your use case more. And “in CI” can also mean many things, since at large companies, CI exists in so many forms. We can solve this by adding more details:

⚠️ “How can I wire up code to run in our <specific pipeline> that uses our new AI agent library?”

Sidenote: Both “pipeline” and “AI agent library” should be hyperlinked to their source

This communicates much more of the intent of what you’re trying to do by being specific. However, it’s still missing the second piece—motivation.

You’ll know you missed this when someone responds with, “Can you explain more of the underlying use case or why you’re trying to do this?” This is a pretty common response in support channels, and it makes sense. They want to give you the simplest possible solution for your problem. It’s similar to how we always recommend asking “why” to product managers so we can propose simpler solutions.

To add the why, you can either explain it inline or link to a doc below your request.

✅ Option 1 (inline): For context, I’m trying to build an agent that can autogenerate documentation at PR time.

✅ Option 2 (doc link): For context, this is the relevant 1-pager doc

Personally, I prefer a combination of both—option 3

✅ Option 3 (combination): For context, I’m trying to build an agent that can autogenerate documentation at PR time. This is the relevant 1-pager doc

This is nice because it gives a TL;DR for those who don't want to go into the doc, but provides the doc for those who are extra curious.

The next time you're asking a question in a support channel, just remember specificity and motivation. Be specific with your request, and explain why you need it.

(5) Project updates

There are two places where project updates typically occur—emails and Slack (or your messaging app).

In both of these, my big tip is to use linked list updates (learned from Rahul Pandey). Whenever you give an update, you also link to the previous update.

Why? For two reasons:

1. Entire history available: It allows anyone to view the entire project history by following the linked list of updates. Having this reference is great for quickly accessing important links or understanding the changes from week to week.

2. Easy monthly updates: It makes it easier for you to write aggregated monthly updates or your launch email when discussing challenges and the process involved. It’s also great for reference during your performance review. You can link to the last update and suggest the reader follow the chain for details, and you can use it for information gathering.

To do this in emails, first draft them in Google Docs via the @email helper. Then in your update email, link to the past update at the end for those curious about the update chain.

Once you hit enter, you’ll see an interface like this:

In Slack, this becomes a lot easier, and it would look like this:

And voila! You can quickly access every single update by tracing the linked list. It’s one of my favorite applications of computer science in communication 😂

📖 TL;DR

• Tagging someone in a long thread: If you tag someone in a long thread, don't make them catch up on their own. Summarize the situation and make a clear ask.

• Pull requests: Don't just say what the code change achieves. Explain why you're doing it and what problem it solves. Link to the Slack thread, user complaint, error logs, dashboards, etc. This gives valuable context for the next person—who may be you—wondering why the code works this way.

• Asking someone for help: Make it as easy as possible for them to help you. Show and tell them exactly what you did and what went wrong. Provide error messages, screenshots, and repro steps.

• Asking a support channel for help: Your question should be specific enough that they know what you want to do, with enough context on why you want to do it, so they can suggest something better.

• Project updates: Use "linked list" updates. When you write an update via email or Slack, link to the prior one so anyone interested can see more context on how it's been trending. Plus, it makes it easier for you to write each update, since referencing the previous week is important for a complete update.

View previous “Communicate like a Senior” articles here:

• Use clear deltas

• Phrases used by the best leaders

• How to write well

Thank you for reading and being a supporter in growing the newsletter 🙏

You can also hit the like ❤️ button at the bottom of this email to support me or share it with a friend to earn referral rewards. It helps me a ton!

Linear is the issue tracker you’ll enjoy using. Spend less time managing tasks and tickets, and more time building what actually matters.

The less time you spend in your issue tracker, the more time you spend building what matters.

• Designed by engineers who understand flow state is sacred

• Keyboard-first interface with Git…

Read more

If you’re overwhelmed (or sick) of keeping up with the hundreds of new tools that come out every day, this post is for you.

I’m here to tell you that you don’t need hundreds of tools. To be productive with AI, you only need to know your core workflows that you spend the m…

Read more

Today’s article features a special guest, Hugo Bowne-Anderson, AI scientist and instructor of a top-rated LLM/AI course on Maven. In this article, you’ll learn why AI agents are often the wrong first choice and what to do instead. Hugo walks through multiple patterns you should use, when to use them, and how…

Read more

If you haven’t tried it yet, it’s a more advanced ChatGPT in your editor that can understand your codebase, answer questions, write features for you, write te…

Read more

Linear is the issue tracker you’ll enjoy using. Spend less time managing tasks and tickets, and more time building what actually matters.

The less time you spend in your issue tracker, the more time you spend building what matters.

• Designed by engineers who understand flow state is sacred

• Keyboard-first interface with GitHub…

Read more

Unleash the power of HubSpot's enhanced developer tools for faster, more efficient app building. Streamline your projects with updated APIs and feedback mechanisms to turn your ideas into market-ready products quickly.

Start building

Read more

Today’s article features Karthik Subramanian, software engineer at Rippling and author of Karthik’s Newsletter. I’ve been impressed with how actionable Karthik’s writing is. I’ve shared his article on how to succeed as an intern with practically every intern I’ve met 😄.

However, today’s topic is on how to drive incident investigations and create clarity out of chaos. Strap in, this is a good one.

Without further ado, I’ll pass the mic 🎤 to Karthik 👏

“Hey Karthik, we've noticed a sharp decline in our core metrics across the board over the past few days. Any idea what's going on?”

Alarm bells 🚨 fired off in my head. I felt my stomach twist into knots. A critical data pipeline for downstream operations had suddenly stopped working. The pressure was on to figure out the cause and fix it.

Initially, I felt confident, running queries and reviewing dashboards like a detective sifting through clues. But as each new piece of data seemed to contradict my previous theories, that confidence quickly became frustration. I was trapped in a loop, chasing my tail while the clock ticked away mercilessly.

By 2 AM, I was surrounded by a virtual war room of Slack threads and scattered query notebook cells, with no clear answers. It was chaos.

But what if there was a tool that could not only help solve your current crisis, but also supercharge your career growth?

Enter the investigation doc—a simple, yet powerful weapon in your problem-solving arsenal.

“Ugh, another document to write?" you may say, but trust me, this could be the key to transforming how you tackle complex issues and earn the trust of your team.

In this article, we’ll explore:

• Why investigation docs are game-changers for debugging

• How investigation docs led to improving a production system

Ready to turn chaos into clarity? Let’s dive in and discover how a little documentation can make you the go-to problem solver on your team.

🤔 Why Write an Investigation Doc?

As software engineers, we often encounter challenges ranging from tricky bugs to full-blown production alerts that affect stakeholders. In these moments, writing an investigation doc provides the following benefits:

1. Clarity in writing: You’re forced to summarize/articulate the issue in a structured format.

2. Easy Distribution: A well-written doc can be easily shared with team members, stakeholders, and even future you, ensuring everyone is on the same page.

3. Demonstrates Ownership: By documenting your problem-solving process, you show end-to-end ownership of issues. This builds trust within your team and organization and prepares you for more complex and ambiguous projects in your career.

4. Learning Tool: Investigation docs serve as excellent learning resources for the team, helping prevent similar issues in the future and speeding up resolution times.

Investigation Docs act as a catalyst for your growth!

📝 What It Looks Like

The components of an investigation doc usually include the following:

• TLDR: A brief summary of the issue and resolution for quick reference.

• Background/Context: Outline any underlying context behind the system or process of context. This section can also add any context on what the ongoing projects were for that system.

• Detection: How was the issue detected? Include a timeline if relevant

• Investigation Steps: Detail the steps taken to identify the root cause. Be specific about queries run, dashboards checked, and thought processes.

• Resolution: Describe the steps taken to resolve the issue once the root cause was identified.

• Learnings: Reflect on what the team learned from the investigation and how to prevent similar issues or speed up future investigations.

Let’s break down each section with an example! 🎬

💡Example: The Case of the Missing Donation Receipts

We’ll examine this example doc. It would be difficult to show an analysis of the full document in this post, but I’ll highlight the 2 most important sections: The “TLDR” and the “Investigation Process.”

In the TLDR, your goals are:

1. Describe the issue so anyone can understand

2. Summarize the root cause

3. Highlight the business impact and how you’ll resolve it

In the “Investigation Doc,” your goals are to:

1. Keep track of what you’ve tried so you can constantly move forward

2. Record for others for the future how to solve similar issues

You can see below that I keep track of each step I took, which helps me avoid being drowned in different theories and keep a clear step-by-step thought process.

To see each section analyzed, head to this part of the example doc.

How and When I Use the Investigation Doc

In a similar scenario to the above, I was drowning in a flurry of Slack threads, scattered query notebook cells, and no clear path forward.

I wasted valuable time retesting the same hypotheses and lacked a systematic approach to zero in on the root cause. The ideas and rabbit holes were all in my head!

Investigation Docs turned confusion into a solution!

They forced me to step back, clearly document the issue at hand, and list out the investigation steps I’d already taken. This process helped me organize my thoughts and quickly identify new hypotheses to test. Eventually, I was able to pinpoint the root cause.

When I needed to involve another engineer, I shared the doc instead of sending a giant paragraph of context in Slack. This saved time and quickly aligned us on the problem.

And as a bonus, structuring the problem-solving process using the Investigation Doc framework revealed opportunities to improve the system’s observability. I used it to add new charts to the dashboard, which made the next issue easier to handle!

📤 Sharing and Acting on Your Investigation Doc

Writing the doc is just the beginning. Now that you have an artifact, you can share it to maximize learning, impact, and prevention of future issues.

1. Share Widely: Present your findings in team meetings or relevant threads/channels.

2. Invite Feedback: Encourage team members to comment and provide additional insights. This collaborative approach can uncover blind spots and lead to even better solutions.

3. Create Action Items: Turn your learnings into concrete tasks. In the example investigation doc, some action items might include:

   1. Improve observability of the Receipt Generation step of the donation processing pipeline → Add charts and alerting to the existing dashboard

   2. Improve test coverage of the entire donation flow → enhance unit tests and end-to-end testing of the system

   3. Uplevel team’s knowledge base of the Receipt Generation system → Setup a Lunch-and-learn session, update wikis/documentation

4. Follow Up: Regularly revisit your action items to ensure they're being implemented. This shows dedication to continuous improvement and helps prevent similar issues in the future.

📖 TL;DR

• Investigation docs drive systematic problem solving, knowledge sharing, and career growth. You can use them for issues ranging from small bugs to big production issues

• The general components of an investigation doc generally include the following:

  • TLDR

  • Background/Context

  • Detection

  • Investigation Steps

  • Resolution/Next Steps

• By taking the time to document your investigative process, you’re not just solving today’s problem—you’re setting yourself and your team up for success in tackling future challenges

To get started easily with implementing investigation docs in your engineering toolbox, check out this template

🙏 Thank you to Karthik

Thank you again to Karthik for the highly actionable article on creating structure and clarity in highly intense situations at work, plus creating a full template and example we can all use. It also reminds me of the popular MECE Framework article section on investigation updates. The template you gave provides a structured doc to use MECE.

Check out his newsletter if you’d like to see more from Karthik.

👏 Shout-outs of the week

• The 13 Software Engineering Laws on by Anton Zaides — One of the most viral tech articles this year. It’s the best reference on software engineering laws you’ve heard throughout your career, explaining how and why to use them.

• How to collaborate cross-functionally on by Torsten Walbaum — Decades of experience packed into a single article of actionable advice on working effectively across teams. A must-read.

• How to use Cursor AI to build side projects on — Check this collaboration post between Gregor, me, and Sidwyn Koh, which shows you the top ways to use Cursor IDE to build quickly.

Thank you for reading and getting us to 90k subscribers! INSANE! I appreciate you 🙏

You can also hit the like ❤️ button at the bottom of this email to support me or share it with a friend to earn referral rewards. It helps me a ton!