DEV Community: David Shimon

Stop Manually Fixing Your Agent’s Output: How and Why We Built a Custom Skill for Monday.com

David Shimon — Wed, 22 Apr 2026 05:53:01 +0000

I'm using my AI agent to create Monday.com tasks. I ask Claude Code to create a task with a proper description, and it does - except when I open the task, the description field is empty. The text I wanted is sitting in the updates thread. Like a comment. Not a description.

The reason I'm doing this from Claude Code at all: context. When you're mid-task - debugging something, writing a spec, reviewing code - and you realize something needs to go on the backlog, the last thing you want is to context-switch to a browser, find the right board, fill in the form, and try to reconstruct what you were thinking. With Claude Code, I just say "add this to the backlog" and it already knows what we've been working on. Nothing gets lost. Then we keep going.

I assumed it was a bug.
It wasn’t. It was worse: the system was working exactly as designed.

What actually happened

The Monday MCP server exposes a bunch of tools. When Claude looks for "how do I add content to a task", it scans the tool list and finds create_update. That sounds like "update an item", but it actually creates an entry in the updates thread. Think comment section, not description field.

It's a naming problem, but also a missing tool problem. There was simply no tool for setting an item's description.

Finding the right mutation

I wanted to understand what the correct path was. So I let Claude read an existing task from my board first. That's when it noticed: "The description is stored as item_description."

Now we knew the field existed. But how do you set it? Claude's next move was to dump the full Monday GraphQL schema via all_monday_api and grep through it. The schema came back as 51KB of JSON. We filtered it down to mutations with "description" in the name — and there it was:

set_item_description_content: Sets an item description document's content with new markdown data.

The right tool existed. It was just completely invisible.

Why it was invisible

No agent is going to figure this out on its own.

set_item_description_content was added to the Monday API on January 26, 2026. The MCP server hasn't caught up yet — so the only way to reach it is through all_monday_api, a generic escape hatch that lets you run raw GraphQL. The mutation is in there, but you'd never know unless you already knew to look.

Monday stores item descriptions separately from item metadata, which is why the correct flow requires two calls:

create_item: sets name, owner, status, etc.
all_monday_api with set_item_description_content: sets the description as markdown

The fix: encode the right behavior

I created a /create-monday-task skill for Claude Code that wraps this two-step flow correctly. The skill does two things the agent wouldn't figure out alone: it explicitly forbids create_update (with a comment explaining why), and it sequences the two API calls correctly: create_item first, then set_item_description_content via raw GraphQL.

The "NEVER use create_update" guardrail is the part that matters most. Without it, any future agent - or future me - would fall into the same trap.

Now when I ask Claude to create a task, it uses the skill, and the description ends up in the right place.

The upstream fix

The real fix is simpler: create_item should just accept a description parameter. Internally it would call set_item_description_content after creating the item. One call, no schema exploration needed.

I filed it here: github.com/mondaycom/mcp/issues/314 — no response yet, but the issue documents the expected behavior if you want to follow along.

The broader lesson

When something goes wrong, the instinct is to fix it manually and move on. Go into Monday, cut the text from the update, paste it into the description, done. I've done this more times than I'd like to admit.

But that's the wrong response — and the leverage gets even bigger when you're on a team. A manual fix helps you once. A shared skill helps everyone, every time, and nobody else has to dig through 51KB of schema to understand why.

The better question is: if I can figure out the right way to do this, why can't the agent? Usually, if there's a path — even a two-step, buried-in-raw-GraphQL path — the agent can follow it once you show it the way. The fix isn't to correct the output by hand. It's to invest a little time understanding why it went wrong, and then encode that understanding: a skill, a guardrail, a better tool description.

That investigation is rarely wasted either. You come out the other side with a working solution and a clearer mental model of how agents actually select and use tools — which makes the next debugging session faster.

Manual corrections disappear. A well-written skill sticks around.

So next time your agent does something slightly off — before you reach for the manual fix — ask: is there a way to make the agent do this right? There probably is. It's almost always worth finding out.

The Skill That Helps Me Do Code Review

David Shimon — Sun, 05 Apr 2026 08:41:07 +0000

I was complaining. Again.

Code review was eating my time, and the problem was only getting worse. We were shipping more features faster, which meant more code, much of it in domains I don't know deeply. Agentic development is great for output. It's not great for the person who still has to understand what got built.

Amitai, a teammate, got tired of hearing about it. He sent me a link.

Tip 26

The article was 45 Claude Code Tips: From Basics to Advanced by @ykdojo. Tip 26 was about interactive PR reviews:

Claude Code is great for PR reviews. The procedure is pretty simple: you ask it to retrieve PR information using the gh command, and then you can go through the review however you want.

You can do a general review, or go file by file, step by step. You control the pace. You control how much detail you want to look into and the level of complexity you want to work at. Maybe you just want to understand the general structure, or maybe you want to have it run tests too.

The key difference is that Claude Code acts as an interactive PR reviewer, not just a one-shot machine. Some AI tools are good at one-shot reviews (including the latest GPT models), but with Claude Code you can have a conversation.

I tried it once. Then again. Then I turned it into a skill.

Why I still read the code

Before getting into the workflow, I want to address the elephant in the room.

Code review in the agentic era is genuinely contested. Some people think it's becoming obsolete. I don't.

Agents write a lot of code. They also produce a lot of slop: suboptimal solutions, non-standard patterns, things that don't match your team's conventions, and sometimes just plain bugs. The responsibility is still ours. Even Boris Cherny, the creator of Claude Code, says he still reads the code he generates.

There's also a practical reason: the person who wrote the code might be on vacation next week. I need to be able to own it, change it, and defend it. That only happens if I actually understood it during review.

At PhaseV, CoPilot runs automatic review on every PR. On top of that, I manually run one-shot reviews using Codex and Claude Code's built-in skills. They catch real things. But automated review isn't the same as understanding the code. That still requires a human.

How the flow works

Our team writes commits that tell the story of a change. Each commit is atomic and focused.

I type /review-pr-interactive and the PR number. From there:

Claude checks out the branch and summarizes the PR's goal
It lists every commit with a one-line description
It starts on the first commit: explains what's happening, flags what deserves attention, and asks for my take before we move on
I read the commit myself. If it's larger than expected, I ask Claude for a recommended reading order for the files before diving in
We decide together what's worth commenting on
Claude uses the GitHub CLI to post the comment on the exact relevant line

Then we move to the next commit.

When I hit something I don't recognize, I ask Claude and learn something new, then usually post it on Twitter under #TIL.

Why a skill and not just a prompt

At this point you might ask: why formalize this as a skill? You could just tell Claude what you want each time.

The answer is consistency. Every time I start a review, Claude already knows our team's conventions, the tone we use for comments, what counts as a Nitpick, and that it should wait for my approval before posting anything. I don't re-explain. I don't forget to mention something. The skill is the accumulated knowledge of every session that didn't go quite right.

One concrete example: before I wrote the skill, it took Claude around 3 attempts each session to figure out the right gh command to add a comment on a specific line in a PR. Now it's written into the skill, and it gets it right the first time.

It also lowers the activation energy. Typing /review-pr-interactive 847 is frictionless. Writing a detailed prompt from scratch is not.

What we added along the way

After using it daily, we refined the skill to fit how our team works:

Define the focus — set what matters most upfront for this type of PR
Nitpick labeling — it's fine to flag style issues, but mark them clearly as Nitpicks
Boy Scout commits — we allow unrelated cleanup in a separate commit within the PR. No separate PR required, just keep it isolated
No auto-commenting — Claude waits for my explicit approval before posting anything

A separate thing we had to shape: how Claude behaves when approving a PR. Early on it would write a full essay summarizing everything the PR did as part of the approval message. Very strange. The PR creator knows what they built. We defined in the skill that a simple LGTM is enough, or a brief note on anything that genuinely stood out.

The thing that surprised me

I expected this to save time. It did.

What I didn't expect was that it would make me more present in the review, not less. With one-shot automated tools, I read a list of findings and move on. With this flow, I'm actually in the code: reading, asking questions, making judgment calls. The AI handles the scaffolding. I bring the understanding.

That feels like the right division of labor.

How are you handling code review as AI writes more of your codebase?

Prompting, Vague and Precise

David Shimon — Sun, 22 Feb 2026 13:13:29 +0000

I was in a session with Shiry, our sharp product manager, demoing Claude Code Web's capabilities. We chose a nice-to-have feature to work on: reflecting the active filter state in our data table.

The product has a table with dozens of columns. Users can filter rows by values in one or more columns, and they can show or hide columns as they like.

The problem: a user can end up with active filters and have no idea which columns they're filtering on. To find the filter indicator in a column header, they'd have to scroll the table horizontally, and maybe unhide columns that are currently hidden. A real game of hide and seek.

First Attempt: Vague about the Problem, Precise About the Solution

I asked Claude Code to add a list of filtered fields above the table:

Add next to the text of "Showing 21 items", the fields we are filter 
the items by (if any). e.g. "Showing 21 items, filtered by Name and Country".

It wrote the code, committed, pushed. We waited for the build, checked the preview environment, and got exactly what I asked for: an ugly list of field names.

Second Attempt: Precise About the Problem, Vague About the Solution

We started fresh.

Shiry, who's a master at building prototypes using LLMs, suggested I try again. This time she dictated the prompt:

On the items table, I want to help the user understand that there is an active filter and what it is.
(without having to look for it on the columns' headers, to scroll, or find  hidden column with filter, etc.)

This time we were much vaguer about the solution, but we described the problem precisely, the same way I described it at the top of this post.

The result impressed me.

Instead of a plain text list, Claude Code rendered a row of chips. Each chip showed the field name and the selected filter values. If more than two values were selected, it showed the count instead. Each chip had a small X to remove that field's filter. And when multiple filters were active, a "clear all" button appeared.

Night and day difference. The second implementation was better by an order of magnitude. It looked familiar, it looked professional, far more useful. It looked like something a designer would design.

The Lesson

When I described the solution, the model built the solution I described.

When I described the problem, the model solved the problem. And it knew a better solution than the one I thought of at first.

Be precise about the problem. Be vague about the solution.

One Word, One Bug, and the Future of AI-Assisted Development

David Shimon — Sat, 14 Feb 2026 21:10:01 +0000

The Pain Point

I was setting permissions for a list of users on our platform. Find a user, toggle the switch, repeat. One by one. With a list of 15 emails staring at me from a spreadsheet.

Then it hit me - the search box is right there. What if I could just paste all the emails at once, space-separated, and see all the matching users at once?

The One-Word Fix

In the code-agentic world, it's probably faster to just try implementing the feature than to open a ticket and wait for prioritization. And honestly, even before AI assistants, I've always loved these low-hanging fruits - the small changes that with a little effort make life easier. Isn't that why we love this job? Especially when the life you're improving is your own.

I described what I wanted to Claude Code. The solution was almost comically simple: change .every() to .some().

But first - why was it .every() in the first place? Respecting Chesterton's Fence, I wanted to understand the reasoning before tearing it down. The original AND logic made sense for its original purpose: if you type "john smith", .every() ensures both "john" and "smith" match, narrowing results to that specific person. It treated the search box as a single query where spaces refine the search. A perfectly reasonable design for searching by name.

But my use case was different. I wasn't searching for one person with a multi-word name - I was searching for multiple people by their emails. And email addresses don't have spaces, so each space-separated token is a distinct person I'm looking for.

// Before: AND logic - all terms must match the same user (refines a single search)
searchTerms.every((term) => user.email.includes(term))

// After: OR logic - any term can match (finds multiple users at once)
searchTerms.some((term) => user.email.includes(term))

One word. That's it. And the trade-off? Even for the original "john smith" use case, the results are still useful - John Smith will still appear, just alongside other Johns and Smiths. A slightly broader result set is a small price for the ability to search for multiple users at once.

I committed, pushed, opened a PR, and kicked off the build pipeline. No local testing - the local environment had some glitches, and with a change this small, I figured I'd validate on the preview environment once the build finished. A one-word change. What could go wrong?

The Vacuous Truth

While I waited, GitHub Copilot reviewed the PR. At first glance, nothing stood out - the review looked clean. But then I noticed a collapsed comment: "Comment suppressed due to low confidence." I almost scrolled past it. I clicked to expand, and there it was - a flag for something I completely missed:

When the search box is empty, searchTerms is an empty array. [].some(...) always returns false. This will hide every user when there's no search query.

This is a real computer science concept called vacuous truth: a statement about all members of an empty set is trivially true. [].every(fn) returns true because "all zero elements satisfy the condition" is vacuously true. But [].some(fn) returns false because "at least one of zero elements satisfies the condition" is false - there are no elements to satisfy anything.

My one-word fix would have broken the entire permissions page. No search query → no users visible → confused admins pinging me on Slack.

The Fix Loop

I asked Claude Code to look at the review comment. It immediately understood the severity, implemented the fix - a simple guard clause:

searchTerms.length === 0 ||
searchTerms.some((term) => /* ... */)

Then it amended the commit, pushed, and we waited for another build cycle.

Three Lessons

1. Test as early as you can - it saves time and tokens.
Of course we'd test before merging. But a unit test written before pushing would have caught this instantly, saving a full build cycle, a review round-trip, another fix, and another build. In the agentic world, tests aren't just for correctness - they're a feedback loop for your AI agents too. A single test case with an empty search string would have told Claude Code "you're not done yet" before it ever opened a PR.

2. AI code review is a gift - but you have to unwrap it.
Copilot understood exactly what I was trying to build - I had a clear commit message explaining the motivation. It simply caught the edge case I missed. Without that review, I would have deployed to preview, seen an empty user list, and spent time debugging what went wrong. Instead, I got a precise comment pointing to the exact problem before I even opened the preview URL. That's time saved, frustration avoided, and a bug caught with a clear explanation - no debugging required on my end. But here's the thing: Copilot hid this critical catch behind a "low confidence" collapse. The bug-saving review was one click away from being invisible. AI review is only as good as your willingness to engage with it - even the parts it's not sure about.

3. The "single-shot" dream isn't here yet - but the pieces are.
Here's what actually happened: Copilot found the bug → I read the comment → I asked Claude Code read it and fix it → Claude Code fixed, committed, and pushed → I waited for another review cycle.

Here's what I wish happened: Copilot finds the bug → Claude Code automatically reads the review, evaluates severity, implements the fix, pushes a new version → I review the final result.

No human in the loop between the AI reviewer and the AI implementer. Let them iterate and converge, then bring me in to approve the final version. Why am I the message bus between two AI systems that could talk to each other?

The Bigger Picture

The entire feature - from idea to shipped fix - involved changing about 10 lines of code. But it touched a real workflow pain point, introduced a subtle bug through a trivial change, and was caught and fixed by an AI pipeline where I was mostly orchestrating rather than coding.

This is what AI-first development actually looks like today: not a single magical prompt that produces perfect code, but a tight loop of human intent → AI implementation → AI review → AI fix → human approval. The gap we need to close isn't in the AI's capability - it's in the connective tissue between the agents.

How to Pass Context to Pydantic Validators

David Shimon — Sat, 14 Feb 2026 20:33:46 +0000

I had a function that needed to behave differently depending on who was calling it. Not what it does, just whether it should log errors or stay quiet.

Sounds simple. It wasn't.

The Setup

We have a phone number normalization function. It takes messy phone numbers from various data sources and formats them consistently. Sometimes the numbers are garbage (missing digits, wrong format, random text). When that happens, the function returns the original value and moves on.

The function is wired into our Pydantic models as a BeforeValidator:

from typing import Annotated
from pydantic import BeforeValidator

PhoneNumber = Annotated[str, BeforeValidator(normalize_phone_number)]

This means Pydantic calls it automatically whenever it constructs a model that has a phone number field. We don't control when or how it's called. Pydantic just passes the value and expects a value back.

The Problem

This function runs in two very different contexts:

API requests - serving data to users. Bad phone numbers are expected (the source data might be messy). Logging every invalid number here would flood our logs with noise on every request.
Data validation pipeline - checking new data files before deploying them. Here we want to see every invalid number so we can catch problems early.

Same function. Same Pydantic model. Two different needs.

The Obvious Ideas (and Why They Don't Work)

My first thought was the simplest one: just add a parameter.

def normalize_phone_number(value, log_errors=False):
    ...

But this function is a Pydantic BeforeValidator. Pydantic calls it with (value). You can't pass extra arguments. The signature is fixed.

OK, what about a global flag?

_log_errors = False

def enable_logging():
    global _log_errors
    _log_errors = True

This works if you only handle one request at a time. But in FastAPI, multiple requests run concurrently. If Request A sets the flag to True, Request B (running at the same time) will see it too - even though Request B never asked for logging.

Global variables are shared across all concurrent requests. That's not what we want.

What about two separate functions? One that logs, one that doesn't?

def normalize_phone_number(value):
    ...  # no logging

def normalize_phone_number_with_logging(value):
    ...  # with logging

Now I'm duplicating the normalization logic. And since the function is bound to the Pydantic model through BeforeValidator, I'd need a separate model just for the validation pipeline. That's a lot of ceremony for a logging flag.

Enter ContextVar

Python has a module called contextvars in the standard library (since 3.7). It gives you variables that are isolated per execution context. When you set a ContextVar value in one async task, other tasks running concurrently don't see it. Each gets its own copy.

Here's what I ended up with:

from contextlib import contextmanager
from contextvars import ContextVar
from typing import Any
import logging

logger = logging.getLogger(__name__)

_validation_logging_enabled: ContextVar[bool] = ContextVar(
    "validation_logging_enabled", default=False
)

@contextmanager
def enable_validation_logging():
    token = _validation_logging_enabled.set(True)
    try:
        yield
    finally:
        _validation_logging_enabled.reset(token)

def log_validation_error_if_enabled(message: str, **kwargs: Any):
    if _validation_logging_enabled.get():
        logger.error(message, **kwargs)

That's the whole module. No dependencies beyond the standard library.

How It Fits Together

The normalization function calls the conditional logger:

def normalize_phone_number(value):
    ...
    try:
        parsed = phonenumbers.parse(value)
    except NumberParseException as e:
        log_validation_error_if_enabled(
            "Invalid phone number format", value=value, error=str(e)
        )
        return value
    ...

The data validation pipeline wraps its work in the context manager:

def validate_incoming_data(data, schema):
    with enable_validation_logging():
        result = validate_records(data, model=schema)
    return result

def validate_records(data, model):
    """Check a each data record through a Pydantic model
    ...

That's it. Inside the with block, errors get logged. Outside of it (like during API requests), they don't. No parameters to thread through the call chain, no global state to worry about.

The Token Pattern

One detail worth understanding: the set() / reset(token) pattern.

token = _validation_logging_enabled.set(True)
# ... do work ...
_validation_logging_enabled.reset(token)

When you call set(), you get back a token. When you call reset(token), it restores the previous value. Not False. The previous value. This means if someone nests two enable_validation_logging() calls, it still works correctly. The inner one resets to True (what the outer one set), not to False.

Wrapping this in a try/finally means cleanup happens even if an exception is thrown.

Starting from Python 3.14, tokens can be used directly as context managers, so you can skip the wrapper entirely:

with _validation_logging_enabled.set(True):
    result = validate_records(data, model=schema)

The with block calls reset(token) for you on exit. If you're on 3.14+, this removes the need for a custom context manager.

Testing It

The tests verify both sides of the behavior. We use pytest's caplog fixture, which captures log records so we can assert whether a message was emitted:

class TestLogPhoneNumberErrors:
    def test_no_logging_outside_context(self, caplog):
        normalize_phone_number("not a phone number")
        assert caplog.records == []

    def test_logs_error_inside_context(self, caplog):
        with enable_validation_logging():
            normalize_phone_number("not a phone number")
        assert "Invalid phone number format" in caplog.text

    def test_context_manager_resets_after_exit(self, caplog):
        with enable_validation_logging():
            pass
        normalize_phone_number("another invalid number")
        assert caplog.records == []

The default is False (silent). You opt in to logging. Existing code doesn't change behavior.

The Trade-off

I'll be honest about the downside: this is "action at a distance." The normalization function reads a flag it didn't receive as a parameter. If you're reading the module for the first time, you might not realize that logging is controlled by something outside the function.

A good docstring helps. And for our use case (a simple boolean flag, two clear contexts), the trade-off is worth it. The alternative would be restructuring how Pydantic validation works just to pass a logging flag through.

When to Reach for ContextVar

ContextVar is a good fit when:

You need to pass context through layers you don't control (like Pydantic validators, middleware, or third-party callbacks)
You're in an async environment where global state isn't safe
The context is simple (a flag, a request ID, a correlation token)
The context is for cross-cutting concerns (logging, tracing, monitoring), not business logic.

It's not the right tool for complex state management. If you need to collect errors into a list or build up rich context, there are better patterns. But for "should this code path behave slightly differently right now?" it's exactly right.

Wrapping Up

The whole change was a small new module and a few test cases. No new dependencies. The data validation pipeline now catches bad phone numbers early, and API request logs stay clean.

Sometimes the right solution isn't a new library or a clever architecture. Sometimes it's a stdlib module you haven't used before.

Have you used ContextVar in your projects? I'd like to hear about your use cases in the comments.

How AI Agents Changed What I Write About (And Why You Should Still Care About Git)

David Shimon — Mon, 02 Feb 2026 11:29:33 +0000

The Moment Everything Changed

Last week, I was working with Claude Code on a feature. We were in flow - the kind where you're solving problems faster than you can type. The code was good, the tests passed, and we had a commit ready to go.

Then I looked at the commit message.

It was organized, clear, and listed three distinct changes we'd made.

Three separate things. In one commit.

I paused. I'd just written a blog post about atomic commits. About how each commit should tell one story. About how good git history makes code reviews easier and future debugging possible.

And here I was, about to commit the exact kind of change I'd been preaching against.

So I asked Claude Code: "Can you split this into three atomic commits?"

And it did. Perfectly. Exactly how I would have done it manually.

That's when the doubt crept in.

"So Why Did I Even Write This Post?"

For the first time in 20 years as a developer, I'd been writing technical blog posts. The rise of LLMs gave me the confidence to write in English. I found myself explaining things I knew well, and that's how I discovered good topics.

Three of my posts were about git. About how to structure commits so they have value. So they help whoever reviews the changes and whoever reads the code in the future.

But now, staring at Claude Code's perfectly split commits, I felt my motivation drain away.

Why does it matter that I know all the tools, shortcuts, and tricks, in a world where I can just ask the agent to do the work?

There are already companies where nobody writes code anymore. People are shipping to production without even looking at what was generated.

What's the value in writing posts that don't directly address how to work with LLMs?

The Answer Was Staring Me in the Face

Then it hit me.

Claude Code split those commits perfectly because I asked it to.

It didn't look at that three-part commit message and think "hmm, this should probably be three commits." It would have happily pushed that large commit if I hadn't intervened.

I was the one who recognized there was a problem. I was the one who knew what good commits look like. I was the one who could evaluate whether the split was done well.

The agent didn't replace my knowledge.It amplified it.

All those posts I'd written about git? That's what gave me the ability to spot the issue and know how to fix it, even through a tool.

From Developer Instructions to Agent Instructions

After working with Claude Code a few more times, I did something interesting: I created a skill that encodes the principles of atomic commits directly. Now, every time the agent creates a commit, it automatically:

Asks itself whether it's atomic
Ensures it has a clear message
Splits it if needed

But here's the thing: I couldn't have created that skill without understanding the principles.

The skill didn't invent the rules. It encodes what I already knew, what I wrote about in my post on The Madman, Architect, Carpenter, and Judge.

This is exactly what I mean when I say knowledge has shifted from "instructions for developers" to "instructions for agents." Same principles, same importance. Only the execution has changed.

And even with the skill in place, I still need to check. The agent isn't perfect. Sometimes I need to correct or redirect it. That requires the same understanding that would have been needed to write the code myself. I'm just using it for review and direction instead of manual implementation.

The Calculator Analogy

We all have calculators in our pockets. But we still learn multiplication tables by heart. We still learn long division with paper and pencil. We understand the calculations.

Not because we want to be faster than the calculator.

We learn it because:

It helps us understand what the calculator is doing
It gives us intuition for when a result looks wrong
It lets us estimate results mentally for simple cases
It helps us know the meaning of the calculation, and when we should use it
It's the foundation for understanding more advanced concepts

The same is true for git add --patch, or any other technical skill. You don't need to be faster than Claude Code. But you should know what it's doing under the hood.

Two Futures

There's both opportunity and risk here.

The Opportunity: If you understand the principles, AI agents make you super-productive. You can ask "split this into atomic commits" and get a perfect result. You can focus on the why and the what, while the AI handles the how.

The Risk: If you don't understand the principles, you'll be dependent on the AI's defaults. You'll get large commits because you didn't know to ask for something different. You'll get code that works but isn't readable. You'll ship to production without looking, and discover problems only when they explode.

The Reality: To use these tools well, you need to understand what's happening under the hood. To know what to ask for, when the result doesn't look right, and how to fix it.

What This Means for Writing

This changes what technical blog posts should be.

No more guides on "how to run git rebase -i step by step." Instead, posts about:

Why atomic commits matter (not how to create them)
What makes code readable vs just working (not how to write it)

And yes, still some “how”. A peek under the hood. Not a tutorial, but enough understanding so you know what's happening. Like learning long division even though you have a calculator.

Because in a world where AI writes the code, our job is to know what to ask for, why it matters, and how to check that we got what we wanted.

In the past, this knowledge was implicit in our technical skills. Now it needs to be explicit.

And that's exactly what this blog will do going forward: show you what's possible, why it matters, and enough "how" so you understand what's happening.

Then you can make sure it happens for you too - whether you do it yourself, or guide an AI agent to do it for you.

Use Git Shortcuts - Because Your Fingers Deserve Better

David Shimon — Wed, 10 Dec 2025 17:09:20 +0000

If you're running git checkout -b feature/new-thing dozens of times a day, you're wasting precious seconds and mental energy. There's a better way.

Why Command Line?

I work with git from the command line. Not (only) because I'm old fashioned, but because once you know the shortcuts, it's faster than reaching for your mouse. My IDE has a great integrated terminal, and with the right aliases, I can navigate git in seconds.

The Secret Weapon: Oh My Zsh Git Plugin

I didn't invent most of the shortcuts I use. I use them from the git plugin of Oh My Zsh (a popular framework for managing your Zsh configuration), which provides a huge collection of aliases and functions that make working with git much faster.

My team members also installed the plugin. Now we speak the same language - when I say "just gpsup it," they know exactly what I mean. We can share tips, and when pair programming, the muscle memory transfers seamlessly between keyboards.

"But I'll Never Remember These Cryptic Shortcuts!"

I hear you. gpsup looks like alphabet soup at first. But here's the thing: they're surprisingly logical once you see the pattern. Most shortcuts follow a simple formula: g (git) + first letters of the command. So gcb = git checkout -b, gco = git checkout, gcmsg = git commit -m (msg). Your brain picks up the pattern faster than you'd think.

How to Enable the Plugin

The git plugin comes bundled with Oh My Zsh, but you need to enable it in your .zshrc:

plugins=(git)

Start Simple: The Essential Shortcuts

Don't try to learn everything at once. Start with the commands you use most often. Like the legend about Harvard's paths that were paved in the ways students walked the most. Here's how to find them:

# See your most-used git commands
history | grep git | awk '{print $2, $3}' | sort | uniq -c | sort -rn | head -10

Check what you use most often and find a shortcut for that command, and get used to using it.

For most developers, these basics cover 80% of daily work:

gst - git status
gco - git checkout
gcb - git checkout -b create new branch
gp - git push
gl - git pull
ga - git add
gcmsg - git commit -m
glog - beautiful git log with graph

Pro tip: Wondering what a shortcut actually does? Type which <shortcut> in your terminal to see the full command.

Once you get used to these shortcuts, they become muscle memory. You stop thinking about git syntax and stay focused on your code. That's the real win - maintaining flow instead of context-switching to remember command flags.

Commands I mentioned in my previous posts about git:

gapa - git add --patch interactively choose which changes to stage from each file
grbi - git rebase -i interactive rebase
gc! - git commit -v --amend. Forgot to include a file in your last commit? Made a typo in the commit message? This fix your last commit without creating a new one. No more "oops, fix typo" commits cluttering your history

My Favorite Power Shortcuts

gpsup - No more copying error messages when pushing a branch for the first time. This shortcut runs git push --set-upstream origin $(current_branch) automatically. One command, done.
gwip and gunwip - Perfect for when you need to quickly switch contexts without losing work. gwip creates a Work In Progress commit with all your changes, and gunwip removes it when you're ready to make a proper commit. Great for handling urgent bugs mid-feature.
gbda - Clean up 10 merged branches in one command instead of typing git branch -d ten times. After a sprint with multiple feature branches merged, this is a lifesaver.
gsta and gstp - Stash shortcuts for when you need to quickly save work and come back to it. Much faster than typing out git stash and git stash pop.

A Real Workflow Example

Here's my typical feature branch workflow:

gcb new-feature          # Create and switch to new branch
# ... do some work ...
gapa                     # Interactively stage changes
gcmsg "Add new feature"  # Commit with message
gpsup                    # Push and set upstream

Compare that to typing it all out manually:

git checkout -b new-feature
# ... do some work ...
git add --patch
git commit -m "Add new feature"
git push --set-upstream origin new-feature

The shortcuts aren't just faster - they let you stay in the zone instead of wrestling with git syntax.

Learning Hidden Git Gems

A bonus of using the plugin: you'll discover git commands and flags you didn't know about. The plugin authors have made thoughtful choices about safer alternatives and useful flags.

For example, gpf isn't just git push --force - it's actually git push --force-with-lease (or git push --force-with-lease --force-if-includes on newer Git versions), which is a safer alternative that prevents you from accidentally overwriting someone else's work. If you really need the dangerous --force, that's gpf! with an exclamation mark.

Another example: even the basic gc (commit) uses the -v (verbose) flag. It runs git commit -v, which shows you the actual diff of your changes at the bottom of the commit message editor. You can review what you're committing while writing the message - a small detail that makes a big difference in writing accurate commit messages.

If you want to learn about other useful flags on git commands, e.g. “git log”, try alias | grep "git log", read about them, try them, and adopt what you like. Maybe glols is your preferred way to see your git log? It's like git log but prettier and includes human readable relative time and which files were changed per commit.

Adding Your Own Custom Aliases

While the Oh My Zsh git plugin is incredibly comprehensive, you might find yourself wanting shortcuts for workflows it doesn't cover. Here's one I added that's become essential to my workflow:

The `fixup` Alias

fixup - git commit --fixup

Add this to your ~/.oh-my-zsh/custom/aliases.zsh file:

alias fixup='git commit --fixup'

This is a game-changer for cleaning up commits during code review. When reviewers point out issues in specific commits, instead of creating "fix typo" or "address review comments" commits, I use fixup to mark them for automatic squashing during an interactive rebase with --autosquash. It keeps your commit history clean without the manual work of reordering commits.

Common Questions

"What if I'm on a machine without my aliases?"

This is real pain. My solution: keep the most critical commands in muscle memory both ways. I can still type git status when needed, but gst is my default.

"How do I see all available aliases?"

Run alias | grep git to see everything. It's a long list! Or check the official plugin documentation.

"Can I customize existing aliases?"

Yes! Add your overrides to ~/.oh-my-zsh/custom/aliases.zsh. Your custom aliases take precedence over plugin defaults.

"Should I learn the full commands first?"

Honestly? Yes. Understanding what git rebase -i does makes grbi powerful instead of magical. The shortcuts are a speed layer on top of solid fundamentals.

The Bottom Line

Git shortcuts aren't just about saving keystrokes - they're about staying in flow, reducing context switching, and making git feel less like a chore.

Give it a try. Your future self (and your fingers) will thank you.

What are your favorite git shortcuts? Share them in the comments!

The Madman, Architect, Carpenter, and Judge: Turning Git Commits Into Stories

David Shimon — Sat, 06 Dec 2025 18:53:32 +0000

We've all done it: make a bunch of changes, then commit everything with a vague message like “fix issues”. But what if we approached Git commits like a writer approaches a manuscript?

When I work on a large change, my commits aren't "pretty" on the first attempt. Still, I invest the time to organize them. I break the changes into atomic pieces - each one doing a single thing that's very easy to understand and review. For example: in the first commit, add a new type of constraint; in the second commit, add a negative constraint; in the third commit, modify one message to use both new constraints; and in the fourth commit, update another message that now needs to use the new constraints.

The Four Roles of Writing

Betty S. Flowers, Emerita Professor of English at the University of Texas at Austin, wrote about roles in the writing process, offering a solution to writer's block by separating the creative and critical aspects of writing. She identified four roles that participate in the writing process, and to avoid getting stuck, they shouldn't "talk" to each other while we're writing. Instead, we need to "wear" a different hat at each stage so each can work without interference. The stages she identifies are: the Madman, the Architect, the Carpenter, and the Judge. If you want to write, I recommend reading her article to understand what each role does at each stage of writing.

Applying This to Git Commits

I borrow her idea from prose writing:

Stage One - The Madman writes the code without thinking too much about who will read it. Fixes what needs fixing, adds what needs adding, checks that everything works and does what it should, without too much self-control.

Stage Two - The Architect comes to organize all the code the Madman wrote. They find the logic in the madness, identify the different stages, separate into the different parts that create the commits that tell the story of the change.

Stage Three - The Carpenter organizes each individual commit - ensures it contains exactly what it should, chooses an appropriate title, and details in the comment about the essence of the change.

Stage Four - The Judge examines the finished work - plays the role of the reviewer.

Why Is This Worth the Investment?

This is essentially self code review. As a code reviewer, it's much easier to review a pull request that's divided into clear, well-defined, and short commits. But beyond hoping I'm making my reviewers' lives easier, the main value of my work is that I'm doing a review for myself. I need to explain the change to myself - why I did each thing and how - in order to build the pull request this way. The additional pass over the recently written code, this time with different eyes - looking for the different stages in the change, the order and logic - helps me improve my code.

The Concrete Benefits

Faster, better code reviews: Reviewers can understand and approve changes faster when they can review one logical change at a time. Instead of facing a wall of changes, they can follow your thought process step by step.

Easier debugging: When something breaks, git bisect becomes a powerful tool. With atomic commits, you can quickly pinpoint which specific change introduced a bug. Compare this to commits that bundle multiple unrelated changes - bisect becomes nearly useless.

Safer reverts: If you need to roll back a change, atomic commits let you revert precisely what's broken without losing good work. You can revert just the third commit while keeping the first two, rather than throwing away an entire day's work.

Better documentation: Six months from now, when you (or a teammate) run git blame to understand why something works the way it does, a well-crafted commit with a clear message tells the story. The commit history becomes living documentation that explains not just what changed, but why. It's like having a time machine. I can go back and ask the writer (usually my past self) why this change was done, and get a clear answer instead of a shrug.

Smoother onboarding: New team members can read through your pull requests and commit history to understand how changes are structured and how features are built incrementally. It's like leaving breadcrumbs for future developers.

The time invested in organizing commits pays dividends every time someone (including future you) needs to understand, debug, or modify the code.

The Tools of the Architect and Carpenter

Once you embrace this workflow, you'll need the right tools to reshape your commits. Here are the essential commands:

Interactive Rebase: Your Primary Tool

Interactive rebase is the Swiss Army knife for organizing commits. It allows you to rewrite history before pushing:

git rebase -i HEAD~5
This opens an editor showing your last 5 commits, where you can:

Reorder commits - move them up or down to tell a better story
Edit commits - modify the code or message of a specific commit
Squash commits - combine multiple commits into one
Split commits - break one large commit into smaller atomic pieces
Drop commits - remove commits that aren't needed

Each commit in the editor is prefixed with a command (pick, reword, edit, squash, etc.). Change the command, save the file, and Git walks you through the changes.

Stage Partial Changes

Sometimes the Madman mixed multiple logical changes in a single file. The Carpenter can separate them:

git add -p

This command presents each change in the file and asks: "Stage this hunk?" You can answer y (yes), n (no), s (split into smaller pieces), or e (manually edit). This lets you commit only the relevant parts of a file, keeping each commit focused.

Example workflow: You fixed a bug and also renamed a variable in the same file. Use git add -p to stage only the bug fix for one commit, then stage the rename for a separate commit.

Quick Fixes with --fixup

When the Judge or the real reviewer find issues during review, create fixup commits:

git commit --fixup <commit-hash>

This creates a commit labeled fixup! Original commit message. Later, when you run git rebase -i --autosquash, Git automatically merges these fixup commits into their targets. It's perfect when you're polishing individual commits.

Pro tip: Make autosquash the default behavior so you don't have to remember the flag:

git config --global rebase.autosquash true

Conclusion

Clean commits aren't just about being a good team player—they're about being kind to your future self. The time you invest in organizing your commits today pays back every time you need to debug an issue, understand why a decision was made, or safely revert a change.

Start small: try this approach on your next pull request. Put on the Madman's hat and write your code freely. Then become the Architect and find the story in your changes. Let the Carpenter polish each commit. Finally, be the Judge and review your own work.

Your reviewers will thank you. Your future self will thank you. And you might just write better code along the way.

How to Fix a Commit Message

David Shimon — Thu, 20 Nov 2025 07:02:51 +0000

Good commit messages are important for improving collaboration, speeding up debugging, documenting a project's history, and simplifying code reviews.

But sometimes we make typos in our commit messages because we are, for now, human. Sometimes the message we wrote isn't clear or detailed enough. In any case, sometimes we want to change the message we wrote for a commit.

In this post, we'll go over two simple ways to change a commit message to make it clearer, more organized, more accurate, correct, etc.

For example, you might want to change:

# Vague message
fix bug

# To something more descriptive
Resolve null pointer exception in user login validation

Case 1: Fixing the Last Commit Message

We want to fix the message of the last commit we made. The command git commit --amend allows us to change the last commit.

Make sure there are no changes you've added to staging with git add, because we only want to change the message, not the files in the commit (I'll cover changing commit content in a future post).

After running git commit --amend, an editor will open and allow us to change the message. Edit, save, exit - and we're done.

Case 2: Fixing an Older Commit Message

What happens if we want to change the message of an older commit? One we made four commits ago, for example, and now we've decided we want to change it?

The command we'll use this time is interactive rebase:

git rebase -i <base>

Where base is a commit in the branch history that comes before the commit we want to change. For example, to modify the last three commits, you would use HEAD~3. If all your branch commits are after the main branch, use git rebase -i main.

An editor will open showing all the commits we've made since the base commit, and will allow us to make changes to their history. Before each commit there's a command that tells Git what we want to do with this commit during the rebase.

pick 4698cbda # Change post header
pick 2f95451c # Add cover image
pick fdae7c1b # Comit message with typo we want to fix

# Rebase 517de4f8..fdae7c1b onto 517de4f8 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message

The command we're interested in for this post is reword - which says: use the commit but edit its message. We'll find the commit (or commits) we want to change, and replace the default pick command (which means use the commit as is) that appears before it with reword, or just the letter r for short.

When we save and exit the editor, the rebase will start executing the commands, and will open an editor with the previous message of the commit that we can change, save and exit until the rebase completes successfully.

⚠️ Warning: You're Rewriting History

In both cases, we're changing history. Even though it's seemingly just a message change, it actually creates a new commit. Therefore, don't do this on branches that are shared with other people and not with commits that have already been merged into main, because it will create a mess for the team. Do this on a feature branch you're working on alone, and that hasn't been merged yet.

If you've already pushed the branch to origin, you won't be able to push it again simply, because you've changed the commits that were there. To push the updated commits, you'll need to use git push --force-with-lease. We're essentially saying that our local, corrected changes are what we want and we're happy to give up what's in origin.

Conclusion

Now your reviewer will be able to understand what you meant in each commit, and if in the future you need to understand why you made the change - you'll see clear and well-written messages on the commit.

The Mystery of the Invisible Tab: A YAML Debugging Tale

David Shimon — Sat, 15 Nov 2025 17:14:25 +0000

TL;DR

Spent hours debugging why my OpenFGA CLI config file wasn't working. Turned out YAML doesn't support tabs. Good error messages matter.

The Setup

This week, I started using OpenFGA, an open-source authorization system. It offers multiple ways to configure connection settings:

Command-line flags
Environment variables
A YAML configuration file (.fga.yaml)

The YAML option caught my attention. Why? Because I work with multiple OpenFGA servers. With YAML configs, I could create separate .fga.yaml files in different directories and just run the CLI from the appropriate folder. Elegant!

Or so I thought.

The Problem

I created my config file, added the server URL, API token, and other settings. Ran the CLI. Nothing.

The CLI completely ignored my configuration file and fell back to defaults. No errors. No warnings. Just... silence.

The Debugging Session

Enter debugging mode - with some LLM assistance, naturally. After lots of trial and error:

✅ The file path was correct
✅ The YAML syntax looked valid
✅ All values were properly formatted

Yet somehow, it didn't work.

Plot twist: I created a config file for my local environment, and that one worked perfectly. Same format, same structure, different values. Very strange!

At this point, I cloned the OpenFGA CLI repository, ready to hunt down this mysterious bug in the source code.

The Breakthrough

I asked Cursor to generate a sample config file. After replacing the values with my own, this generated file worked flawlessly.

Time for a diff:

diff working-config.yaml my-config.yaml

The output? Two "blank lines" at the end of my file. I deleted those lines, and suddenly everything worked.

But wait - if I added blank lines back to the working file, it continued to work fine. What was going on?

The Culprit

Closer inspection revealed the truth: those weren't blank lines. One of them contained a tab character.

I discovered that YAML doesn't support tabs. In fact, it's FAQ #2 on yaml.org (right after "What's the official file extension?").

Mystery solved. The culprit found. And as usual in these stories: it was me.

The Lesson: Error Messages Matter

Here's what bothered me most about this experience: the CLI found my config file but silently ignored it when parsing failed.

If a configuration file exists but contains invalid syntax, the tool should tell me! A simple error message:

Error: Failed to parse configuration file '.fga.yaml'
YAML parsing error: tabs are not allowed

That's why I opened an issue suggesting this improvement.

The Takeaway

Good error messages are crucial for Developer Experience (DX). When building CLI tools:

Fail loudly when something is wrong - Silent failures lead to frustrating debugging sessions
Be specific - "Config file not found" vs "Config file found but failed to parse"

This is especially important for configuration files that developers might edit in different environments, with different editors, and different settings.

In Conclusion

YAML doesn't like tabs. CLI tools should tell you when your config is broken. And when in doubt, blame the developer (me) first - but make it easier for developers to catch their mistakes.

Have you had similar debugging experiences with invisible characters or silent failures? Share your stories in the comments!

DEV Community: David Shimon

Stop Manually Fixing Your Agent’s Output: How and Why We Built a Custom Skill for Monday.com

What actually happened

Finding the right mutation

Why it was invisible

The fix: encode the right behavior

The upstream fix

The broader lesson

The Skill That Helps Me Do Code Review

Tip 26

Why I still read the code

How the flow works

Why a skill and not just a prompt

What we added along the way

The thing that surprised me

Prompting, Vague and Precise

First Attempt: Vague about the Problem, Precise About the Solution

Second Attempt: Precise About the Problem, Vague About the Solution

The Lesson

One Word, One Bug, and the Future of AI-Assisted Development

The Pain Point

The One-Word Fix

The Vacuous Truth

The Fix Loop

Three Lessons

The Bigger Picture

How to Pass Context to Pydantic Validators

The Setup

The Problem

The Obvious Ideas (and Why They Don't Work)

Enter ContextVar

How It Fits Together

The Token Pattern

Testing It

The Trade-off

When to Reach for ContextVar

Wrapping Up

How AI Agents Changed What I Write About (And Why You Should Still Care About Git)

The Moment Everything Changed

"So Why Did I Even Write This Post?"

The Answer Was Staring Me in the Face

From Developer Instructions to Agent Instructions

The Calculator Analogy

Two Futures

What This Means for Writing

Use Git Shortcuts - Because Your Fingers Deserve Better

Why Command Line?

The Secret Weapon: Oh My Zsh Git Plugin

How to Enable the Plugin

Start Simple: The Essential Shortcuts

My Favorite Power Shortcuts

A Real Workflow Example

Learning Hidden Git Gems

Adding Your Own Custom Aliases

The fixup Alias

Common Questions

The Bottom Line

The Madman, Architect, Carpenter, and Judge: Turning Git Commits Into Stories

The Four Roles of Writing

Applying This to Git Commits

Why Is This Worth the Investment?

The Concrete Benefits

The Tools of the Architect and Carpenter

Interactive Rebase: Your Primary Tool

Stage Partial Changes

Quick Fixes with --fixup

Conclusion

How to Fix a Commit Message

Case 1: Fixing the Last Commit Message

Case 2: Fixing an Older Commit Message

⚠️ Warning: You're Rewriting History

Conclusion

The Mystery of the Invisible Tab: A YAML Debugging Tale

TL;DR

The Setup

The Problem

The Debugging Session

The Breakthrough

The Culprit

The Lesson: Error Messages Matter

The `fixup` Alias