<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Plainionist on Medium]]></title>
        <description><![CDATA[Stories by Plainionist on Medium]]></description>
        <link>https://medium.com/@plainionist?source=rss-6f5a9effd211------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*5m7U_mRul6jcEkNlnI5ybg.png</url>
            <title>Stories by Plainionist on Medium</title>
            <link>https://medium.com/@plainionist?source=rss-6f5a9effd211------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 15:15:51 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@plainionist/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Agentic Refactoring — Using Agents to Reveal the Sculpture from Vibe-Coded Rock]]></title>
            <link>https://medium.com/@plainionist/agentic-refactoring-using-agents-to-reveal-the-sculpture-from-vibe-coded-rock-2e4d73bb1bc8?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/2e4d73bb1bc8</guid>
            <category><![CDATA[genai]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Thu, 17 Sep 2026 04:57:10 GMT</pubDate>
            <atom:updated>2026-09-17T04:57:10.330Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CRybzgoDw9SD2jDFbjMXNg.png" /></figure><p>I vibe coded a working application — and then discovered that neither I nor my coding agents could explain its architecture.</p><p>The diagrams looked like a big ball of mud, and eventually a medium-complex feature got stuck in an endless cycle between coder and reviewer.</p><p>So I stopped feature development and spent the next days applying <strong>agentic refactoring</strong> until the architecture became visible.</p><h3>The Starting Point</h3><p>At the start of the refactoring, the codebase consisted of roughly 27k lines of C# and TypeScript.</p><p>It had been almost completely vibe coded with only a few general rules such as KISS and separation of concerns. There was no deliberate architecture or test strategy, and most of the system lived in one frontend and one backend project.</p><p>So the first task was not to design the perfect architecture. It was to make the existing structure visible enough to know where to start.</p><h3>First Cut: Abstractions and Contracts</h3><p>I started by separating abstractions from implementations.</p><p>Abstractions define contracts, and contracts reveal dependencies. So we extracted interfaces, contracts and other technology-independent types into dedicated modules, then separated categories such as UI, hosting and runtime.</p><p>Once those contracts and dependencies were visible, they gave me clues where to cut the implementation next. Classes dealing with configuration became configuration, hosting code became hosting, and so on.</p><p>This happened iteratively. I asked Copilot Chat to describe module responsibilities and boundaries, discussed unclear areas, and turned the next one or two refactorings into tickets for my agent team.</p><p>At that point, I did not know whether those modules would survive. That was not important yet. I just needed to start untangling the code somewhere. At one point we split a module into two, merged it again the next day, and later split it differently. Types moved between modules more than once.</p><h3>Creating an Abstraction of the Architecture</h3><p>As the first boundaries emerged, I needed a way to inspect the architecture without constantly reading implementation details.</p><p>So we started building <em>modules.md</em>, describing the current modules and their responsibilities.</p><p>It became an important communication tool between Copilot and me. If a module description basically said it does this AND this AND this, I had something to investigate. The same was true when two modules appeared to have similar responsibilities. The <em>modules.md</em> gave me an abstraction of the codebase without constantly reading the implementation.</p><p>We also added API documentation for important types, mainly so agents did not have to reverse engineer their purpose repeatedly.</p><p>Another useful tool was my old <a href="https://www.plainionist.net/Plainion.GraphViz/">Plainion.GraphViz</a> tool, which visualizes module and type dependencies. A type sitting in a strange module or depending on something it probably should not know about became much easier to spot.</p><p>Those observations were never final decisions. They reflected my current understanding of the system — and that understanding kept evolving.</p><h3>Removing Obvious Complexity</h3><p>Once the first major concerns were separated, I went one level deeper.</p><p>There were classes with 15 or more members and several responsibilities. Instead of designing the perfect replacement, Copilot and I identified the major responsibilities, split the class and moved on.</p><p>Many classes created during this phase no longer exist. Later refactorings reworked that intermediate design almost completely. But that was fine. Splitting the obvious god classes reduced the complexity enough to expose the next layer.</p><p>We applied the same principle to smaller things: unnecessary custom exceptions, dead code and low-value tests. By low-value I mean tests where the behavior was already sufficiently covered elsewhere or failures would immediately be caught by broader acceptance coverage.</p><p>With the obvious noise reduced, the next architectural problem became much easier to see: the tests themselves were getting in the way.</p><h3>The Tests Were in the Way</h3><p>During vibe coding, the agents had created many unit- and component-style tests. A large part of the internal system was exposed to tests, and production code contained indirections — mostly delegates — primarily to enable mocking.</p><p>Almost every structural change therefore required corresponding test changes.</p><p>The tests were supposed to give us confidence while refactoring, but they were coupled to exactly the internal design we wanted to change.</p><p>So we introduced a small, explicit <strong>Test API</strong>. Whenever possible, tests should use the same APIs as the UI or user. Dedicated testability APIs were added only where necessary. The goal was to get as close to black-box testing as reasonably possible. The tests finally became the refactoring safety net I needed.</p><p>Now we could move types, change ownership, remove indirections and restructure modules without rewriting large parts of the test suite. Once that coupling was gone, we could also remove indirections that existed only for testability and consolidate some modules again.</p><h3>Dependency Inversion — Where It Helped</h3><p>With the larger boundaries becoming clearer, we could also see where abstractions actually added value.</p><p>Interfaces, factories and DI add complexity too. They help when they separate things that should actually be independent, but introducing them everywhere does not automatically improve an architecture.</p><p>So we introduced factories, dependency injection and dependency inversion only in selected places.</p><p>For example, one part of the system still referenced a concrete external runtime directly, while another abstraction mixed availability checks, preparation, deferred context creation and backend construction.</p><p>Once those responsibilities and dependencies were visible, the right abstractions and factories became much easier to identify.</p><p>That cleared the way for the part I cared about most: the domain model.</p><h3>Revealing the Domain Model</h3><p>The first signs of trouble were simple. Some classes had names that no longer made sense in the picture I had developed.</p><p>Looking closer, the real problem was often incorrect ownership and therefore incorrect relationships between key entities.</p><p>Primitive obsession made those relationships harder to see.</p><p>When parameters are strings, or several classes contain dictionaries keyed by strings, it is difficult to understand which concepts actually depend on each other. Once a string becomes a <em>CustomerId</em> or <em>OrderId</em>, the relationship gets a name — and misplaced responsibilities become much easier to spot.</p><p>So we introduced proper domain types, split classes, moved responsibilities and rearranged ownership.</p><p>Again, this took several rounds.</p><p>With every step, aggregate boundaries, ownership and relationship cardinalities became clearer. Shortly before the end, the target state finally became obvious enough to discuss the remaining gaps and create the last few refactoring tickets.</p><p>At that point, the sculpture was finally starting to show.</p><h3>How I Worked With the Agent Team</h3><p>I did not start the refactoring with a fully worked-out plan.</p><p>Instead, I fell back on a few old principles: divide and conquer, reduce noise, do not dive too deep too early, and make the problem simpler until the next step becomes visible.</p><p>Throughout the journey, I took the human architect role. I owned the diagnosis, direction, architectural judgments and stopping decisions. I did not change code myself or review every code change. When I looked at code, I was mainly scanning for key modules and types, their responsibilities, dependencies, ownership and relationships.</p><p>Once Copilot Chat and I had identified the next refactoring, we created a ticket for the agent team.</p><p>That team also had an Architect agent (GPT-5.6 Sol Max), but with a different responsibility: it took an approved refactoring goal and decomposed it into small, individually integrable slices. The Coder (Sonnet 5 High) implemented each slice, the Reviewer (Grok 4.6 xHigh) reviewed it, and once the slice was clean the team continued.</p><p>The Reviewer had findings quite frequently — perhaps in around 30% of the cases — but small slices and regression tests kept the changes manageable.</p><p>I manually reviewed almost none of the code changes, but throughout those two weeks I did not observe a behavioral regression escaping that process.</p><h3>The Architecture Finally Became Visible</h3><p>Near the end, I tried the architecture diagrams again.</p><p>This time they worked. C4 gave the agent a useful viewpoint and vocabulary, but more importantly, there was finally a clear architecture underneath: key modules and types, responsibilities, boundaries, dependencies, relationships, lifecycle, and control and data flow.</p><p>That was the mental model I had been looking for from the beginning. The codebase was also ready for feature development again: the architecture had meaningful boundaries and the tests protected behavior without being coupled to internal details.</p><p>With vibe coding, you can build software quickly.</p><p>But someone still needs to recognize the sculpture and decide where to cut.</p><p>And the cutting itself can safely be left to the agents again — <strong>agentic refactoring</strong>. 😎</p><h3>How This Article Was Created</h3><p>Yes, this article was written with AI. 😉</p><p>The story is mine. The input was a journal I kept during the refactoring journey.</p><p>I gave those notes to ChatGPT, which interviewed me with <strong>29 </strong>follow-up questions before drafting the article.</p><p>I reviewed the draft, and we refined it together through <strong>8 </strong>iterations until we arrived at this final version.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2e4d73bb1bc8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Vibe Engineering?]]></title>
            <link>https://medium.com/@plainionist/vibe-engineering-05acedd35550?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/05acedd35550</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[agentic-engineering]]></category>
            <category><![CDATA[vibe-coding]]></category>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Tue, 01 Sep 2026 04:51:36 GMT</pubDate>
            <atom:updated>2026-09-01T04:51:36.892Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PxzRQEpIxoY0MoCXGMtbCg.png" /></figure><p>What would I do if all I had was my favorite coding agent CLI — Claude Code, Codex, or GitHub Copilot?</p><p>No custom agents, no custom skills, no MCP, no fancy tools, and not even a multi-agent framework.</p><p>After using such a setup for the last few days, here is my simple and pragmatic workflow.</p><h3>The Essence</h3><p>The basic idea is simple:</p><ol><li><strong>Define a goal and make a plan</strong></li><li><strong>Break the plan down into small slices</strong></li><li><strong>Incrementally implement and verify each slice until the goal is achieved</strong></li></ol><p>When working with coding agents, there is one additional rule I consider important:</p><p><strong>Planning, implementation, and verification should happen in separate sessions.</strong></p><h3>The Workflow</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/955/1*3cUmfVDSPsxTY8ouaNZNvg.png" /></figure><h4>1. Create the plan</h4><p>Open your coding agent CLI and describe what you want to achieve. Give it the goal, acceptance criteria, and relevant constraints. Then ask it to create an implementation plan and break the work down into slices that can be implemented and submitted individually.</p><h4>2. Review the plan</h4><p>Review the proposed plan, including the slicing. If you are not happy with it, iterate with the planner until you are. Once the plan looks good, close the session.</p><h4>3. Implement the first slice</h4><p>Open a new coding agent session and ask it to implement the first slice. Let it make the changes and verify the implementation. Once it is done, keep the session open.</p><h4>4. Review the implementation</h4><p>Open a second session and ask it to review the pending changes. The reviewer should check whether the implementation matches the plan and whether it introduced any bugs or design issues. Tell the reviewer to write its findings into files.</p><p>If there are any review findings, switch back to the implementation session and ask it to fix them. Once the findings are fixed, ask the reviewer to review the changes again.</p><p>Repeat this until the slice is completed without any further review findings.</p><h4>5. Continue with the next slice</h4><p>Repeat implementation and review for every remaining slice until the complete plan is implemented. Then close all open sessions.</p><p>That is the whole workflow.</p><h3>Tips &amp; Tricks</h3><p>For planning and review, use a high-end model like Sol with <em>high</em> or even <em>max</em> reasoning effort.</p><p>For implementation, a medium model like Terra with medium effort seems to be sufficient for most tasks.</p><p>Keep your prompts generic. That way, you can simply use cursor-up and run the same prompt again instead of continuously writing new instructions.</p><p>Here are a few examples:</p><blockquote><em>Review the pending changes. Do they fulfill the task? Any bugs introduced? Do not run any tests — just do a code and design review. Only report real issues — no cosmetics. Create one issue for every finding with priority 1 and prefix `review` under `docs/issues/`, if any.</em></blockquote><p>After the implementer has fixed the findings:</p><blockquote><em>Findings fixed — re-review.</em></blockquote><p>And in the implementation session:</p><blockquote><em>New review findings — pull all priority 1 issues prefixed with `review`.</em></blockquote><h3>Surprisingly Little Setup</h3><p>I have used this workflow for the last few days to develop some non-trivial features, and it worked surprisingly well with almost no setup.</p><p>I did not specify any roles explicitly. There are no special agent files describing a Planner, Implementer, or Reviewer. I only have some very basic repository instructions, such as my preferred naming conventions and general principles like KISS and separation of concerns.</p><p>Even with that minimal setup, the reviewer regularly found real issues. For some non-trivial slices, it took three or more implementation-review cycles until no findings were left.</p><p>And I did not carefully review all tests myself or establish architecture fitness functions or other deterministic quality gates. I mostly left that to the agents.</p><p>Still, the results were remarkably good.</p><h3>The Drawback</h3><p>There is one downside to this approach: <strong>Micromanagement.</strong></p><p>You have to start the sessions, tell the next agent what to do, switch back to the implementer when there are findings, trigger another review, start the next slice, and so on.</p><p>At some point, you cannot avoid the feeling that you are working for the agents instead of the agents working for you. 😉</p><p>And that is exactly why, in the long run, you probably want some kind of multi-agent orchestration. 😉</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=05acedd35550" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[discover.sh — The Tool That Made My Agents More Efficient]]></title>
            <link>https://medium.com/@plainionist/discover-sh-the-tool-that-made-my-agents-more-efficient-4b96568ff363?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/4b96568ff363</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Sat, 11 Jul 2026 14:39:14 GMT</pubDate>
            <atom:updated>2026-07-11T14:39:14.550Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*VxnC38Lnoqg9cQ_E" /></figure><p>AI coding agents can write code remarkably fast. But writing code is only part of the job.</p><p>They also spend a surprising amount of time and tokens searching, reading, and trying to understand the codebase.</p><p>Over the last few weeks, my agent team developed several small scripts to make that work faster and more focused — saving time and tokens.</p><h3>One Entry Point, One Workflow</h3><p>All tools are available through a single entry point: `<a href="https://discover.sh/">discover.sh</a>`.</p><p>An agent only needs to know commands such as:</p><blockquote><em>./tools/discover.sh find “shortlist best effort”<br>./tools/discover.sh explain system/Shortlist.fs<br>./tools/discover.sh def Shortlist</em></blockquote><p>A built-in <em>help</em> command makes the available tools discoverable.</p><p>But providing the tools is not enough.</p><p>My agents are explicitly instructed to use the source-discovery workflow before reading large parts of the codebase. This ensures that they use focused tools instead of falling back to broad searches and loading unnecessary files.</p><h3>Better Grep</h3><p>The first group of tools works directly on the source files using Bash, ripgrep, Git, and a little Python. They require no index, are always up to date, and answer the questions my agents ask most often.</p><h3>Finding Entry Points</h3><p>The <em>find</em> tool turns a task description into search terms and looks for them in file names and contents across F#, Vue, TypeScript, and Gherkin.</p><p>Instead of returning every match, it ranks the most promising files. The agent gets a useful starting point without filling its context with noise.</p><h3>Explaining an Area</h3><p>The <em>explain</em> tool identifies the project owning a file, its compile-order neighbors, dependencies, declarations, sibling files, and a suggested reading order.</p><p>This is where a custom tool can outperform a generic code index: it understands our F# compile order, project structure, and codebase conventions. It does not just find code-it helps the agent navigate our architecture.</p><h3>Finding Callers</h3><p>The <em>callers</em> tool searches the solution for definitions and usages of an F# symbol.</p><p>It is name-based rather than compiler-based, so it may include unrelated symbols with the same name. But it quickly reduces a solution-wide investigation to a small set of likely callers.</p><h3>Finding Relevant Specifications</h3><p>The <em>specs</em> tool searches our Gherkin feature files for a term.</p><p>For each matching file, it returns the feature title and its scenario names instead of dumping complete scenario bodies. The agent can identify potentially relevant behavior with a very small context footprint.</p><h3>Resolving Domain Terms</h3><p>The <em>term</em> tool combines results from our domain glossary, Gherkin specifications, and F# definition sites.</p><p>With one command, the agent gets a compact answer to three questions: What does this term mean, where is it specified, and where is it implemented?</p><h3>Finding Related Changes</h3><p>The <em>related</em> tool uses Git history to find files that frequently change together.</p><p>Very large commits are filtered out to reduce noise. The remaining results can reveal hidden dependencies and unexpected architectural coupling.</p><h3>A Lightweight Code Index</h3><p>Some questions were still inefficient to answer by repeatedly scanning the entire codebase. The team therefore created a small Python index stored as worktree-local, Git-ignored JSONL files. The line-delimited format keeps the index transparent and makes incremental updates simple.</p><h3>Building the Index</h3><p>The <em>index</em> tool extracts F# symbols, source locations, projects, and compile order.</p><p>It hashes each file and reparses only those that have changed. This provides fast code navigation without requiring a database, background service, or external dependency.</p><h3>Finding Definitions</h3><p>The <em>def</em> tool looks up a symbol definition by name.</p><p>It returns the file, lines, project, declaration, and qualified name. When several definitions match, it provides a short disambiguation list instead of making the agent inspect unrelated files.</p><h3>Showing File Outlines</h3><p>The <em>symbols</em> tool returns a compact outline of a source file containing its modules, types, functions, and members.</p><p>The agent can decide whether a file is relevant without loading its complete contents. If the file has changed, its index entry is refreshed automatically.</p><h3>Finding Record Construction Sites</h3><p>The <em>field</em> tool finds assignments to an F# record field and distinguishes normal construction from copy-and-update expressions.</p><p>When adding a new field, the agent can focus on construction sites that probably need to change while ignoring updates that inherit the existing value.</p><h3>Let the Agents Build Their Own Tools</h3><p>I did not plan this toolkit upfront.</p><p>The agents created and improved it whenever our retrospectives revealed repeated search work, unnecessary output, or missing context.</p><h3>Do We Need Something More Sophisticated?</h3><p>I discussed parsers, ctags, MCP servers, and more advanced indexing several times with the team and separately with ChatGPT.</p><p>So far, the answer has always been no. Our tools produce deterministic, bounded, and transparent results without hidden services or opaque state-and they already fit our codebase and workflow remarkably well.</p><h3>Conclusion</h3><p>Small, focused tools can make coding agents significantly faster while reducing token usage.</p><p>Let the agents solve real bottlenecks and continuously improve the tools through retrospectives. Over time, you get tooling that fits your setup almost perfectly-almost for free.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4b96568ff363" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Loop Engineering — My Current Setup in a Nutshell]]></title>
            <link>https://medium.com/@plainionist/loop-engineering-my-current-setup-in-a-nutshell-cb853081a5dc?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/cb853081a5dc</guid>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Fri, 26 Jun 2026 15:36:15 GMT</pubDate>
            <atom:updated>2026-06-26T15:36:15.988Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*IfilDK66eSn1MRTo" /></figure><p>Loop engineering is often explained in abstract terms.</p><p>Here is my concrete, current, and pragmatic implementation in a nutshell.</p><h3>What is loop engineering?</h3><p>Definitions of loop engineering differ in some details, but the common building blocks seem to be these:</p><ol><li><strong>Sub-agents</strong>: Multiple specialized agents working together. One agent does the work, another verifies it independently, and a third one keeps the big picture and focuses on the goal.</li><li><strong>Worktrees</strong>: Isolated workspaces, typically Git worktrees, that let multiple agents work in parallel on the same repository without file conflicts or overwriting each other’s changes.</li><li><strong>State</strong>: Persistent storage outside any single conversation, for example `STATE.md` or issue boards. It tracks what is done and what is next. This is essential for long-running or multi-cycle loops.</li><li><strong>Skills</strong>: Persistent, codified instructions, usually in files like `SKILL.md`. They capture conventions, standards, and reusable workflows, preventing agents from re-deriving context every session.</li><li><strong>Plugins and connectors</strong> (often via MCP): Integrations that connect the agent to real external tools like issue trackers, PR systems, or databases. This allows the agent to act rather than just suggest changes.</li><li><strong>Automations**</strong> (scheduling/triggers): Scheduled or event-driven processes that discover tasks, triage work, and initiate execution. Examples are cron jobs, `/loop`, or GitHub Actions.</li></ol><h3>My pragmatic setup</h3><h3>Sub-agents</h3><p>I use SwarmForge by <a href="https://x.com/@unclebobmartin">@unclebobmartin</a>, which brings the idea of different roles, realized as separate agents.</p><p>I have an Architect, which prepares the plan, an Implementer, which only changes the production code, and a Verifier, which checks the result and writes the tests. This splits the responsibilities of planning, coding, and verification.</p><p>Furthermore, I have instructions that tell agents to use sub-agents for detailed analysis or research. For example, my Architect instructions include this:</p><blockquote><strong><em>## Research</em></strong></blockquote><blockquote><em>If you require details from the code, do not read it directly. Use sub-agents instead.</em></blockquote><p>GitHub Copilot then seems to spawn temporary sub-agents automatically for different tasks, such as analysis and verification of details. When I watch my team working, I see those temporary sub-agents being used quite a bit.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*MiS1tiRJe-AjDltw" /></figure><h3>Worktrees</h3><p>SwarmForge provides dedicated workspaces for each role or agent.</p><p>Its tooling creates and maintains a dedicated worktree and branch for each agent. It also provides instructions to keep agents disciplined in that regard.</p><h3>State</h3><p>The overall state of my loop is persisted in tickets: simple Markdown files inside the repository. Open tickets show which work still needs to be done. Completed tickets are simply deleted.</p><p>The details and slices of the current ticket are persisted in an <em>implementation plan</em>. It is written by the Architect and read by the rest of the team. It is stored as a Markdown file in a shared folder called `agent_context`.</p><p>Internally, the team also maintains a logbook. I only gave them the instruction to keep track of handoffs and status. I never look into this file. They use it for coordination.</p><h3>Skills</h3><p>My skills mostly describe capabilities and reusable workflow steps.</p><p>Many people bundle factual knowledge with skills, but I like to keep descriptions of the domain and architecture separate in my knowledge base. The same is true for guidelines like “how to write good Gherkin specs”.</p><p>So I only have a few skills, for example:</p><ul><li>writing an implementation plan</li><li>pulling the next ticket</li><li>running a retrospective</li></ul><h3>Plugins and connectors</h3><p>I do not have any actual CLI plugins or MCP servers yet.</p><p>There is simply no need for them right now. All relevant artifacts, such as tickets, the knowledge base, and code, can be accessed directly by my agents through the file system.</p><p>However, my AI team wrote quite a few scripts and tools over the recent weeks. Those tools help with codebase discovery, regression checks, and team workflow. What exactly those tools do is something I will share in a later article.</p><h3>Automations</h3><p>I do not use an external trigger or scheduler yet, mostly because I still do the final review and approval manually. If everything ran fully automatically, I would probably end up with a long pile of unapproved work.</p><p>What I do instead is simpler: I put a certain amount of tickets on “ready”. Then I tell the team to process them according to priority. And they do, except for high-risk changes, where they have to ask for my approval first. That assessment is done by the Architect.</p><h3>How I work</h3><p>My “loop” does not run without me yet.</p><p>But my role has changed a lot.</p><p>I almost stopped coding directly. I also spend less time explaining individual coding steps. I write tickets for new features and improvements, and I review the final outcome. In most cases, I simply approve it. In some cases, I write more tickets for the review feedback.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*W_Ul2GpL7B3hvH63" /></figure><p>So the value is not full autonomy.</p><p>The value is that more and more of my work moves from doing individual changes to improving the system that delivers those changes.</p><p>Now I am interested in your thoughts 😉</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cb853081a5dc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How My AI Team Cut Token Waste]]></title>
            <link>https://medium.com/@plainionist/how-my-ai-team-cut-token-waste-a5a623b6daf6?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/a5a623b6daf6</guid>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Sun, 21 Jun 2026 06:19:55 GMT</pubDate>
            <atom:updated>2026-06-21T06:19:55.776Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*ItaF98IX32So0VDi" /></figure><p>Recently, I described how I transitioned one of my brownfield codebases into an AI-first setup. My primary goal was quality. The agents had to understand the codebase, follow their roles, respect the architecture, and produce changes I could review easily.</p><p>After about two weeks, this worked reasonably well. The team was not perfect, but it was delivering mostly good results. So the next bottleneck became visible: efficiency.</p><p>How can I help the team deliver features faster?<br>How can I reduce the number of tokens the team uses?</p><p>Here are five improvements the team made.</p><h3>The Setup</h3><p>I use SwarmForge by <a href="https://x.com/@unclebobmartin">@unclebobmartin</a> with three roles: Architect, Implementer, and Verifier.</p><p>The <strong>Architect</strong> plans the work, slices it, protects the architecture, and performs the final review. The <strong>Implementer</strong> changes production code and does not change specs. The <strong>Verifier </strong>changes specs and test automation, but does not change production code.</p><h3>1. Role Cards</h3><p>This separation is part of my strategy to ensure quality. It keeps responsibilities clear and lets the agents check each other. But it also increases handoffs.</p><p>Initially, every handoff started with “Re-read your role and constitution.” The idea was simple: if I remind the agents frequently what their role is and what their responsibilities are, they are more likely to stay disciplined during the work.</p><p>The problem was that one task can involve several handoffs between Architect, Implementer, and Verifier before final acceptance. Every handoff caused the receiving agent to re-read the full rule setup: six prompt files plus the role-specific “agent.md”.</p><p>Depending on the role, this was around 500 to 800 lines, often before the agent did any useful work.</p><p>To improve this, the team introduced “<a href="https://make-role-card.sh/">make-role-card.sh</a>“. It extracts the important rule lines into a compact, hash-stamped role card. For a new task, the agent still does a full re-read. Inside an existing task, the agent only syncs the role card.</p><p>The role card is around 42 lines instead of 500 to 800 lines. If the role card hash changed, if the context was compacted, or if a task runs too long, the agent falls back to the full re-read.</p><p>This was the biggest saving. In the analyzed window, the Implementer estimated around 10 handoffs inside the same task context. Replacing roughly 700 lines with around 40 lines removed approximately 7,000 lines of repeated reading. Both Implementer and Verifier ranked this as the most useful token-saving change.</p><h3>2. Summary-First Tool Output</h3><p>The next source of waste was tool output. Builds, test runs, verification scripts, and Git operations printed too much information into the agent context.</p><p>For a human, this is often fine. We scan a console quickly, ignore progress output, and jump to errors. Agents do not work like that. If a command prints hundreds or thousands of lines, the agent has to process that output as text.</p><p>A green test run is a good example. A full “dotnet test” output can contain hundreds of lines per project. This is useful when debugging, but mostly noise when everything passes.</p><p>So we changed the tools to be summary-first. Full logs still go to timestamped files, but the console output is compact. A passing spec project went from roughly 600 lines to around 5 lines. A full regression run went from thousands of lines to a table of around 15 lines.</p><p>On failure, the tools still print the important information: failing project, focused snippet, root cause, and path to the full log. So debuggability is still there, but green runs no longer pollute the context.</p><h3>3. Better Code Navigation</h3><p>Another source of waste was code reading. At first, agents often navigated the codebase with broad text search and full-file reads. That works, but it is expensive.</p><p>Finding one definition may require opening a 300-line file. Finding all places where a type is constructed may require a broad search, followed by opening many files one by one.</p><p>So the team improved the repository-specific discovery tools. These are small shell and Python scripts that help the agents search the codebase more effectively. The most important addition was an index of symbols in the F# codebase.</p><p>With that index, agents can ask precise questions: where is this symbol defined, where is this type constructed, and which files contain relevant callers? Instead of opening several files, the tools return precise locations first. The agent can then read only the relevant parts.</p><p>This helped especially during larger refactorings. One particular rename involved around 70 relevant files. With the index, the agent could first get the relevant locations and then only read what was needed.</p><h3>4. Fewer Unnecessary Turns</h3><p>Token usage is also about turns. Every unnecessary approval, clarification, retry, or recovery sequence costs tokens.</p><p>Initially, my instructions for the Architect were intentionally cautious. The Architect had to create an implementation plan and then wait for human approval. This gave me a chance to check whether the planned change made sense before the team started implementing it.</p><p>That was useful for quality, especially in the beginning. But over time, it became clear that not every change needs the same level of approval. Some changes are very low risk: tooling improvements, documentation changes, small mechanical updates, or reversible improvements without behavior impact.</p><p>Now the Architect classifies work by risk: LOW, MEDIUM, or HIGH. Low-risk plans can self-approve. Higher-risk work still requires approval.</p><p>In the analyzed batch, nine small retro items skipped a human approval round-trip. The team estimated this saved around 13 turns.</p><p>We also made the landing workflow more robust and quieter. A flaky or noisy automation step does not only waste time. It creates recovery conversations.</p><h3>5. Smaller Artifacts</h3><p>Agents write artifacts for each other. Plans are read by Implementers and Verifiers. Handoffs are read by the next role. Logbook entries and retro reports become input for future work.</p><p>Initially, those artifacts were more verbose on purpose. I wanted to preserve context and ensure quality. But once the process became more stable, some of that detail no longer improved decisions. It only increased the amount of text the next agent had to read.</p><p>So we reduced the size of plans, handoffs, logbook entries, and retro reports. Handoffs now focus on the essentials: branch, commit, changed behavior, verification result, open issues, and next role.</p><p>Less narrative, more signal.</p><p>The important point is that we did not remove structure. We removed text that no longer helped the next agent do the job.</p><h3>Retrospectives</h3><p>None of this came from one big redesign. It came from retrospectives.</p><p>Every few cycles, the team looks at what wasted time, tokens, or attention. Then we create small issues and ship the improvements like normal work.</p><p>The agents do not only work on product features. They also improve the system they work in: documentation, skills, tools, logs, handoffs, and workflow rules.</p><p>“If you get one percent better each day for one year, you’ll end up thirty-seven times better by the time you’re done.” — James Clear</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a5a623b6daf6" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Day My AI Team Went Off Track]]></title>
            <link>https://medium.com/@plainionist/the-day-my-ai-team-went-off-track-4eac036d3037?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/4eac036d3037</guid>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Thu, 18 Jun 2026 16:17:18 GMT</pubDate>
            <atom:updated>2026-06-18T16:17:18.606Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*tf6A3Cy7s4i16XWj" /></figure><p>Today my AI-first codebase journey hit an unexpected speed bump.</p><p>When I started my agent team, Copilot no longer offered the usual model selection. My normal setup uses Opus 4.8 for the Architect, Sonnet 4.6 for the Implementer, and GPT-5.3-Codex for the Verifier.</p><p>But for whatever reason, I only had access to Opus 4.5 and Sonnet 4.5.</p><p>So I thought: how bad can it be?</p><p>I chose Opus 4.5 for the Architect, Sonnet 4.5 for the Implementer and Verifier, and gave them the next ticket.</p><p>The ticket was not trivial, but also not rocket science. Just a normal backlog item in a brownfield codebase.</p><h3>The First Signal</h3><p>The first thing I noticed was that everything took longer than usual.</p><p>The Architect needed longer to analyze the work. The Implementer needed longer to make progress. The Verifier needed longer to create tests.</p><p>That was not great, but also not surprising. A weaker model being slower is something I can accept if the result is still good enough.</p><p>But speed wasn’t the real problem.</p><h3>The Real Problem</h3><p>What actually surprised me was the outcome.</p><p>The Architect suggested writing unit tests. In principle, that made sense. So the Verifier created three test fixtures with around ten tests each.</p><p>On paper, that sounds useful.</p><p>Until you actually look at the tests.</p><p>None of them called a single API of the system under test.</p><p>Here is one example:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*0c5Z77FADby4pzXS" /></figure><p>You do not need much context about the actual ticket to see the problem. This test is total garbage. It basically asserts what it arranged itself.</p><p>But the story does not end there.</p><p>Not only did the Verifier produce those tests. The Architect even accepted them. To be fair, the Architect role is not designed as a deep code reviewer. Its main responsibility is to check whether the delivery matches the requested ticket.</p><p>But still: I never got such an obviously nonsensical result from my usual setup during the last three weeks of processing tickets in more or less the same team setup, just with the latest models.</p><h3>Why This Matters</h3><p>This is the dangerous part of agentic coding: the workflow can look productive while producing no real value.</p><p>Files are created. Tests are written. The test count goes up. Everything looks structured.</p><p>But garbage tests are worse than no tests. No tests make the risk visible. Garbage tests hide it behind green checkmarks.</p><h3>My Takeaway</h3><p>This was not a benchmark. It was one real task in one real codebase.</p><p>The problem is not only that an agent gets something wrong.</p><p>The problem is confident nonsense wrapped in professional-looking artifacts.</p><p>When we stop reviewing the code, at least briefly, how would we even spot such nonsense?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4eac036d3037" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Is Faster File Search Worth It for AI Coding Agents?]]></title>
            <link>https://medium.com/@plainionist/is-faster-file-search-worth-it-for-ai-coding-agents-d0d7d0b76fee?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/d0d7d0b76fee</guid>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Wed, 17 Jun 2026 20:14:06 GMT</pubDate>
            <atom:updated>2026-06-17T20:14:06.098Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*qCfdsem_YWU_PhGc" /></figure><p>When your AI coding agents work around the clock and deliver mostly good, sometimes even great results, the next step is obvious:</p><p>Increase productivity. 😉</p><p>One thing stood out: The agents spend a lot of time analyzing the codebase, and so far they have mostly used standard grep-based tools for that.</p><p>Then I found <a href="https://github.com/dmtrKovalenko/fff">fff</a>, which claims to address exactly that.</p><p>So I wanted to know: Is faster fff MCP actually worth it?</p><h3>Installation</h3><p>I installed it as described in the README:</p><blockquote><em>curl -fsSL </em><a href="https://raw.githubusercontent.com/dmtrKovalenko/fff.nvim/main/install-mcp.sh"><em>https://raw.githubusercontent.com/dmtrKovalenko/fff.nvim/main/install-mcp.sh</em></a><em> | bash</em></blockquote><p>Then I added this to .bashrc:</p><blockquote><em>export PATH=”$HOME/.local/bin:$PATH”</em></blockquote><p>After that, I configured it as an MCP server in Copilot CLI using /mcp add.</p><h3>Usage — Trickier than Expected</h3><p>The README suggests adding this to your agent instructions:</p><blockquote><em>For any file search or grep in the current git-indexed directory, use fff tools. Pass this rule explicitly to any sub-agents you spawn!</em></blockquote><p>So I did that and put my agents back to work. The agents initially confirmed that they were using fff, but when I asked again after the task was finished, they said they had not.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/679/0*bLiBMNyK6bQW6bFk" /></figure><p>After some further experiments and a discussion with the Architect, we came up with a stronger prompt:</p><blockquote><em># File operations</em></blockquote><blockquote><em>## Hard constraints</em></blockquote><blockquote><em>- Use `FFF` MCP tools for all repository search and file discovery.<br>- Do not use `grep`, `rg`, `find`, `glob`, bash-based search, or built-in file search.<br>- If `FFF` MCP tools are unavailable, stop and report the blocker.<br>- Pass this same constraint as a hard constraint to every sub-agent.</em></blockquote><blockquote><em>## Forbidden shortcuts</em></blockquote><blockquote><em>Do not use non-FFF search even for quick checks.<br>Do not use bash to bypass this rule.<br>Do not spawn sub-agents without copying this rule into their prompt.</em></blockquote><p>That one actually did the trick.</p><p>I could see in the output that the agents were using fff instead of grep.</p><h3>Was It Worth It?</h3><p>Over the next few days, my agents worked on several tasks, and I monitored their fff usage. They now reliably chose fff over the built-in grep tools.</p><p>But regarding codebase analysis performance, I personally did not notice any meaningful difference.</p><p>When I asked my team about it, the Architect responded with this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*ITAED1bFPSqwNYp9" /></figure><p>“Mild ergonomic improvement.” 🤷‍♂️</p><p>It also detected stale cache problems multiple times.</p><p>So for my setup and codebase, it was not a game changer.</p><p>I removed it again.</p><p>Since uninstalling it, my agents seem to use significantly fewer tokens. 🤔</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d0d7d0b76fee" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How I Made My Brownfield Codebase AI-First]]></title>
            <link>https://medium.com/@plainionist/how-i-made-my-brownfield-codebase-ai-first-53f8c207ed6d?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/53f8c207ed6d</guid>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Fri, 12 Jun 2026 16:00:42 GMT</pubDate>
            <atom:updated>2026-06-12T16:00:42.154Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/680/0*qbnYL2j0CqeXUOD8" /></figure><p>Over the last few weeks, I transitioned one of my real codebases so AI agents can work on it much more independently.</p><p>My motivation was simple.</p><p>I work on many things in parallel, and I never have enough time to implement all the features and improvements I would like to see.</p><p>At the same time, I wanted to learn how agentic engineering works in a real brownfield project: with existing architecture, domain rules, tests, and real consequences if something breaks.</p><p>This article summarizes what I changed, how the setup evolved, and what I learned so far.</p><h3>The Codebase</h3><p>This was not a toy experiment.</p><p>The codebase is a real product used for backlog planning and execution support in <strong>multi-million-dollar projects</strong>. It contains functionality for cut lines, burndowns, projections, and reporting.</p><p>The codebase has around 70k lines of code.</p><p>The backend is built with F# and <a href="https://asp.net/">ASP.NET</a>. The frontend is built with Vue 3 and Vite. The system uses a microservices and microfrontend architecture, with Clean Architecture internally and shared functionality across the “micro apps”.</p><h3>0. Tests</h3><p>The existing quality base was already quite good.</p><p>Domain rules were explicitly modeled in the F# type system, and the codebase had high test coverage through BDD/Gherkin acceptance specs.</p><p>These Gherkin specs now act not only as a safety net for the agents, but also as executable requirement specifications and a source of truth.</p><p>I have almost no classic unit tests. Some may see that as a disadvantage, but I see it as an advantage because my tests are very loosely coupled to the product code. And those acceptance tests are fast. Fast enough for agents.</p><h3>1. Knowledge base</h3><p>The weak spot was documentation.</p><p>I had only limited domain, architecture, and project documentation, which worked well as long as I mostly worked alone in the project. I simply knew the system.</p><p>But agents cannot work well independently with implicit knowledge, so the first thing I improved was the documentation.</p><p>I created a single `Manual` folder with subfolders for architecture, domain, testing, development, and operations.</p><p>Inside, I created separate Markdown files for each section, each usually not bigger than around 200 lines.</p><p>The focus is on concepts and background information.</p><p>Detailed requirements and behavior remain in the Gherkin `.feature` files, and the documentation points to those files where needed.</p><p>I built those documents step by step with Copilot in VS Code: analyzing code and specs, discussing questions, and building up the key documentation step by step.</p><h3>2. Roles</h3><p>Once the knowledge base was in better shape, I focused on the team setup.</p><p>I knew that it was not only important to provide context, but also to keep it clean. So I decided to use different agents for different roles, focusing on context separation.</p><p>I tried different ideas and finally decided on three roles.</p><p>The <strong>Architect</strong> does architecture and requirements engineering. Since the domain and architecture of my project are rather stable, this seemed reasonable. The Architect plans, slices the work, protects the architecture, and performs the final review regarding feature completeness and architecture.</p><p>The <strong>Implementer</strong> changes production code and never changes specs.</p><p>The <strong>Verifier </strong>changes specs and test automation, but never changes production code.</p><p>The agent files focus on role descriptions, workflows, contracts, dos, and don’ts.</p><p>Especially the Architect has instructions to use sub-agents for detailed analysis to keep its own context clean.</p><p>This clear separation between production development and test development resulted in agents controlling each other, which I observed multiple times.</p><h3>3. Engineering codex</h3><p>With the roles in place, I turned the Copilot instructions into an engineering codex.</p><p>It covers things like:</p><ul><li>size of code changes</li><li>code sharing versus coupling</li><li>safe refactoring</li><li>coding rules for readable code in this project</li><li>stop conditions</li></ul><p>This became the place for rules that apply to all agents, regardless of their role.</p><h3>4. SwarmForge</h3><p>At that point, I wanted my different agents to work together as a team.</p><p>When Uncle Bob posted on X about SwarmForge, I knew I wanted to try it. So I installed it and configured it for my setup.</p><p>SwarmForge comes with a constitution, project setup, and workflow descriptions explaining how agents communicate, branch, and hand off work — basically describing the team workflow.</p><h3>5. Handoff rules</h3><p>With the team workflow in place, I was ready to try my new team on actual features.</p><p>It took a while to fix serious gaps in the documentation and harden the handoff gate: which tests to run, what to review, and how to ensure quality.</p><p>Eventually, I turned the handoff process into a skill.</p><h3>6. Skills</h3><p>Initially, I had no explicit skills.</p><p>But as I identified repeated workflow steps, such as regression testing, I asked my team to build skills along the way.</p><p>For me, skills became a way to preserve process knowledge, not just project knowledge.</p><h3>7. Architecture fitness functions</h3><p>At some point, I noticed that we kept updating the architecture documentation in particular.</p><p>That was useful, but it also showed a limitation.</p><p>Describing what to do and what not to do is helpful. Automated rules are better.</p><p>So I asked the team to write <em>_Architecture Fitness Functions_</em>.</p><p>These are realized intentionally as simple scripts, mostly based on regex checks, that detect major architecture violations.</p><p>Example rule themes are:</p><ul><li>project dependency boundaries</li><li>Gherkin file conventions</li><li>layering checks</li></ul><p>All checks have tests and were fully written by AI. I only reviewed the tests.</p><p><strong>This became an important pattern:</strong> When implicit knowledge becomes explicit, I first document it. Then I ask whether it can become an automated check.</p><h3>8. Tools</h3><p>Once the output quality had become quite stable, I focused on productivity.</p><p>Some features still took unexpectedly long.</p><p>I tried MCP servers like <em>fff</em> and <em>serena</em>, but they did not make a noticeable difference in my setup.</p><p>I discussed this topic with ChatGPT, and it suggested writing repository-specific tools.</p><p>The first script was <a href="https://find-entry-points.sh/"><em>find-entry-points.sh</em></a>, which makes it easier to find entry points in the codebase for a given topic.</p><p>The second was <a href="https://explain-area.sh/"><em>explain-area.sh</em></a>, which explains the code around a given file.</p><p>These scripts were initially written by ChatGPT and later improved by my team based on their usage observations.</p><h3>Status quo</h3><p>Meanwhile, I have implemented various features with this setup quite successfully.</p><p>My own role has changed. I am now focusing more on writing backlog items that state the goal and what is important to me, and then handing them over to the team.</p><p>The Architect often still asks clarification questions, but the team delivers.</p><p>I still briefly review everything that ends up on `master`, but no longer every detail.</p><p>Instead, I mostly scan for nonsense and violations of the project rules.</p><p>For example, just recently the team introduced reflection in a test because it was not explicitly forbidden by the rules.</p><p>That was a good example of implicit knowledge.</p><p>I had not even thought about documenting it because, to me, it was an obvious no-go.</p><p>So I asked the Architect to improve the documentation accordingly and to add an architecture fitness function for it.</p><p>I still review generated and modified Gherkin specs carefully, because they are the ultimate quality gate.</p><h3>Retrospectives</h3><p>Doing a retrospective with the team after every major piece of work has become a habit.</p><p>We ask:</p><ul><li>What did we learn?</li><li>Which documentation needs updates?</li><li>Which new architecture fitness rules are needed?</li><li>Did the tools help?</li><li>Which skill should be created or improved?</li></ul><p>And eventually, we even turned this into a skill.</p><p>This way, we improve all artifacts as we go: documentation, rules, skills, tools, and architecture fitness functions.</p><h3>Main lessons learned</h3><p>Turning a codebase into an AI-first codebase successfully is less about the AI models themselves than about improving the environment around the agents:</p><ul><li>making implicit knowledge explicit</li><li>having a strong test safety net, preferably BDD/Gherkin specs</li><li>separating agent roles to keep context and responsibilities clean</li><li>automating rules as architecture fitness functions</li></ul><p>In the end, this became less about one big setup step and more about continuously sharpening the system around the agents.</p><p>“Habit #7 — Sharpen the Saw.”</p><p>— <em>The 7 Habits of Highly Effective People</em>, Stephen Covey</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=53f8c207ed6d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Dark Side of Pull Requests for Managers]]></title>
            <link>https://medium.com/@plainionist/the-dark-side-of-pull-requests-for-managers-3f4dec42ecc8?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/3f4dec42ecc8</guid>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Sun, 02 Nov 2025 00:00:19 GMT</pubDate>
            <atom:updated>2025-11-10T06:43:23.564Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eIsydFqQOXNurUpf_v-AoQ.png" /></figure><h3>Abstract</h3><p>Pull Requests (PRs) were invented for Open Source projects. They allow “untrusted contributors” to suggest changes and ask “trusted committers” to pull them in. Committers review these requests on their own schedule, leave comments, demand changes, or simply reject the “pull request” altogether. For this reason, PRs work extremely well in Open Source.</p><p>Work in commercial teams is fundamentally different. Team members collaborate long-term, share goals, and trust each other. Changes are not “suggested” but planned — it’s rarely a question of whether but how something gets done.</p><p>PRs were not made for this. They optimize for control and gatekeeping, while commercial teams optimize for flow and delivery speed without sacrificing quality.</p><blockquote><em>Using pull requests for code changes by your own team members is like having your family members go through an airport security checkpoint to enter your home. It’s a costly solution to a different problem.</em></blockquote><blockquote><em>Kief Morris, Why your team doesn’t need to use pull requests</em></blockquote><h3>Motivation</h3><p>Many great articles and YouTube videos already discuss this topic — see the references — including well-known voices like Dave Farley, author of “Continuous Delivery”.</p><p>This article provides a concise overview of the real-world consequences of PRs for commercial teams, written for managers and team leads.</p><h3>Setting the Stage</h3><p>Before getting into the arguments, let’s clarify a few facts.</p><h4>Git ≠ PR</h4><p>Git doesn’t require Pull Requests. It’s a version control system that works perfectly well without them.</p><h4>Code Review ≠ PR</h4><p>Code reviews are valuable for code quality, knowledge sharing, and finding bugs. PRs are not required to practice code reviews.</p><h4>Working incrementally</h4><p>Developers rarely complete a feature in a single commit. Bug fixes might fit in one, but most features need multiple commits to be completed.</p><h3>How Pull Requests work</h3><p>Pull Requests always require a branch. A PR can contain one or many commits. It is a “gated submission”: changes are integrated into mainline only after all gates have passed — usually automated tests and code review. A developer cannot start a second PR on the same branch; further changes will update the existing PR.</p><h3>The Arguments</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*fR2HeeiS3K0SqnPv.png" /></figure><h4>Passing gates takes time</h4><p>Running build pipelines takes time. The larger the codebase, the longer it takes. Reviews take time as well. A PR may wait hours or even days for review. If reviews are expected immediately, context switching creates new problems (see “reviewing code immediately”).</p><h4>Continuing on the same task during PR verification is difficult</h4><p>Feature work usually requires several changes. While one PR is under review, continuing the same story requires creating a new branch from the first one. This adds effort and becomes messy if the first PR fails validation.</p><h4>Bigger PRs</h4><p>To avoid this overhead, developers tend to group several changes together and open one PR when the story is finished. As a result, a single PR often contains multiple logical changes.</p><h4>Longer-living branches</h4><p>Producing more changes takes more time, which means feature branches live longer.</p><h4>Delayed Feedback</h4><p>The longer branches live, the longer feedback gets delayed — from tests, from teammates reviewing the design, and from product owners or users who can only verify that the right feature was built after integration.</p><h4>Higher reluctance to apply global refactorings</h4><p>The longer branches live, the higher the reluctance to apply refactorings that span multiple files or affect public APIs because developers fear the effort of complex merges. Skipping refactoring means not paying back technical debt, which means lowering code quality.</p><h4>Bigger integration chunks</h4><p>The bigger the PR, the bigger the chunk of code changes that is integrated at once into mainline.</p><h4>Higher merge complexity</h4><p>The bigger the chunks that get integrated, the higher the risk of complex merges. Complex merges cause more effort.</p><h4>Higher risk of bugs</h4><p>The more complex the merge, the higher the risk of mistakes and regressions, reducing product quality.</p><h4>Harder to analyze build failures</h4><p>The bigger the chunks that get integrated, the harder it is to figure out which change actually caused the issue when the build fails which increases the effort required to finish the feature.</p><h4>Higher reluctance to reject changes</h4><p>Bigger PRs also raise the mental barrier for reviewers to reject changes and demand rework. In the end, it’s one team aiming for the same goal — and it’s hard to tell a teammate to throw away a week’s work.</p><h4>Reduced need to work incrementally</h4><p>It is common sense in the software industry that working incrementally leads to less waste and better results.</p><p>But when accepting bigger PRs, developers lose both the incentive and the skill to work in small increments. Over time, this leads to even larger PRs.</p><h4>Harder reviews</h4><p>Reviewing large, multi-purpose changes takes longer and increases cognitive load. Feedback becomes shallow, resulting in a higher risk of technical debt or even new bugs.</p><h4>Higher barrier for minor cleanups (Boy Scout Rule)</h4><p>When integrating small improvements requires the overhead of a PR, developers skip them. Over time, this lowers code quality.</p><h3>But what about …</h3><h4>… working in isolation?</h4><p>Feature branches may feel productive because they isolate work, but that’s a local optimization. It benefits an individual’s focus at the expense of team flow.</p><h4>… running CI builds on feature branches?</h4><p>Running pipelines on branches is possible if the build farm scales, but it provides partial feedback at best. It shows whether a branch works in isolation — not whether it integrates with everyone else’s changes. By definition, that’s not Continuous Integration.</p><p>Immediate reviews reduce PR delay but force frequent context switches for reviewers. Each context switch costs time (~ 15 minutes) and mental focus. More PRs mean more context switches, lowering overall team productivity.</p><h4>… short-lived branches?</h4><p>Short-lived branches reduce some problems but don’t resolve the fundamental ones. Each PR still acts as a gatekeeper, breaking the flow. More PRs simply multiply the overhead.</p><h3>Continuous Integration</h3><p>Continuous Integration (CI) is the alternative that optimizes for flow and productivity.</p><p>By default, there are no feature branches. All developers commit directly to mainline and every commit triggers the build pipeline. Tests run after each commit, and code reviews happen asynchronously. No gatekeeping!</p><p>The key point is that integration does not mean release. That’s why changes are integrated even before a feature is completed. Still, every change getting integrated must meet production quality.</p><p>Builds can fail — that’s normal. When mainline breaks, fixing it becomes the top priority (“green-to-green” principle). Because integrations are small, fixes are quick and rollbacks low-risk.</p><p>Even if the latest commit is broken, the last green build is always releasable. Release branches can be created from there if needed.</p><p>CI enforces small, incremental changes, solving all the problems introduced by PR-based workflows. It aligns developer behavior with team performance rather than individual convenience.</p><h3>Are branches and PRs entirely bad?</h3><p>Of course not — they have legitimate uses.</p><h4>Prototypes</h4><p>When exploring a problem using a prototype, it’s fine to work on a branch. The branch helps manage work-in-progress, but its purpose is learning, not integration. Once a solution is known, development restarts cleanly on mainline.</p><h4>Integrating Dependencies</h4><p>External dependencies come from outside the team and are therefore trusted less. Using a gated submission for validation before integration is often appropriate.</p><h3>But why does everyone else do PRs then?</h3><p>Many teams adopted PRs because they are the default in popular tools like GitHub and GitLab. Others assume it’s the standard way to use Git. Few stop to question whether a model designed for untrusted collaboration fits a trusted commercial team.</p><h3>Conclusion</h3><p>The key question is: what do you want to optimize for?</p><p>If your goal is control, use PRs. If your goal is flow and productivity, adopt Continuous Integration.</p><h3>References</h3><ul><li><a href="https://medium.com/better-programming/are-pull-requests-holding-back-your-team-e8aec48986c2">Are Pull Requests Holding Back Your Team?</a></li><li><a href="https://hamvocke.com/blog/better-off-without-pull-requests/">You Might Be Better Off Without Pull Requests</a></li><li><a href="https://thinkinglabs.io/articles/2021/04/26/on-the-evilness-of-feature-branching.html">On the Evilness of Feature Branching</a></li><li><a href="https://www.youtube.com/watch?v=ASOSEiJCyEM">Why Pull Requests Are A BAD IDEA</a></li><li><a href="https://www.youtube.com/watch?v=lXQEi1O5IOI">Why CI is BETTER Than Feature Branching</a></li><li><a href="https://www.youtube.com/watch?v=WmVe1QrWxYU">I’ve Found Something BETTER Than Pull Requests</a></li><li><a href="https://www.youtube.com/watch?v=_w6TwnLCFwA">Git Flow Is A Bad Idea</a></li><li><a href="https://youtu.be/aVcfv9uZPpQ">The Dark Side of Pull Requests</a></li><li><a href="https://www.infoq.com/presentations/death-continuous-integration/">The Death of Continuous Integration</a></li><li><a href="https://youtu.be/GfGEtCcWUi4">Continuous Integration — Flow Beats Control!</a></li><li><a href="https://dora.dev/research/2024/dora-report/">DORA</a></li><li><a href="https://www.amazon.com/Accelerate-Software-Performing-Technology-Organizations/dp/1942788339/ref=sr_1_1?dib=eyJ2IjoiMSJ9.jemhPhEOvE34eI5T6fVSy6wFBpNPjjBfe3kwxZx76OaYiUzDk_wk895lrRWwY6HIQ0je12lhE6TcAVUA4586GZaPmZt1olHYZ0MTmw6C2EgF2NkPfWx1r3i2oWWk2BDQXDQfRCoHxWIV8ML8Z2eNNORbMWi2JzJFTyit6xsxFEoeivek_tLAVhtXMr6kga89XiSNYVZ9VMTwV9D2cVpnfHyUkibjWIVuL5WxTtEcJdM.c_xcXYbe2_zgsL6vOgYSOY0pQTCNTX5wma1-lzBYNww&amp;dib_tag=se&amp;keywords=accelerate&amp;qid=1762072349&amp;sr=8-1">Accelerate</a></li><li><a href="https://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912/ref=sr_1_1?crid=30S5B45LGZKU6&amp;dib=eyJ2IjoiMSJ9.itY9oApzOE7dyjDO0Qqy4ck16gK5272nG-QCzwli1F01vVhqFAJZpqOHz0ikilr40Rl1tvv-BlCC0bx5uQ26S_vTsxdSnbObYYe9WlumcKefqH345eo1ZIlGDtxTk3UhbcGFZN9-taZWlswTg0gan4PhqL94XQOOUfGMflLcAdzXuhcs7lUCpme0W0d4vbISWRO3Vl6pCq7SAL6oIEj4unsHsWFvtSQm7168hINMMZw.0dhWm5CfAo2sTBfHGUs8XfbNKd2E1JWVeWLaofbluD8&amp;dib_tag=se&amp;keywords=continuous+delivery&amp;qid=1762072356&amp;sprefix=continuous+deliver%2Caps%2C190&amp;sr=8-1">Continuous Delivery</a></li></ul><p><em>Originally published at </em><a href="https://www.plainionist.net/Dark-Side-of-PRs-for-Managers/"><em>https://www.plainionist.net</em></a><em> on November 2, 2025.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3f4dec42ecc8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What actually is Task<T>?]]></title>
            <link>https://medium.com/@plainionist/what-actually-is-task-t-e0e25fb60712?source=rss-6f5a9effd211------2</link>
            <guid isPermaLink="false">https://medium.com/p/e0e25fb60712</guid>
            <category><![CDATA[asynchronous]]></category>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Plainionist]]></dc:creator>
            <pubDate>Thu, 02 Nov 2023 00:00:21 GMT</pubDate>
            <atom:updated>2023-11-05T13:31:53.560Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wYRgVrt1SSrr15I3kwFiqA.jpeg" /></figure><p>If you see such source code, do you immediately think of multi-threading?</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/ef87f0a4f5e5a6e6a1b3cfbade830570/href">https://medium.com/media/ef87f0a4f5e5a6e6a1b3cfbade830570/href</a></iframe><p>What if I would tell you that Task&lt;T&gt; is nothing but a fancy delegate which is not coupled to threads at all?</p><p>Let’s start with some very simple component. It provides a single API which accepts a request object, does some computation and returns a response object.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a039396159ecbc00a2d1ce582988dc37/href">https://medium.com/media/a039396159ecbc00a2d1ce582988dc37/href</a></iframe><p>Such an API design obviously forces the caller to “actively” wait for the response to be available in order to be able to continue the processing. This design couples the control flow of processing a request and the control flow of handling its response.</p><p>Now let’s assume you want to decouple these two parts of the control flow e.g. because the processing of the request is delayed because of some queue or it runs in a different thread or process or even on a different machine or in the cloud.</p><p>One common way to achieve this in .NET is using events.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a6e520c1cb4b49b5655d477ab6c41a55/href">https://medium.com/media/a6e520c1cb4b49b5655d477ab6c41a55/href</a></iframe><p>(Hint: This sample code is kept as simple as possible, event deregistration is skipped for this reason.)</p><p>An alternative to .NET events would be passing a simple delegate which we could also call <a href="https://en.wikipedia.org/wiki/Continuation">continuation</a>.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a27e743db740d0aff0ea1ff613e14327/href">https://medium.com/media/a27e743db740d0aff0ea1ff613e14327/href</a></iframe><p>In order to improve the readability of this design, let’s get it closer to the initial request-response semantic by inventing a small class called Promise which is returned from the Execute API and which is then used to hook up the continuation.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/2d3d3f4dee47120966befb35ac25f7f1/href">https://medium.com/media/2d3d3f4dee47120966befb35ac25f7f1/href</a></iframe><p>Let’s also add error handling to this design.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fa4bc7742c442b8cc1fe24850a318ac1/href">https://medium.com/media/fa4bc7742c442b8cc1fe24850a318ac1/href</a></iframe><p>The implementation of the IComponent interface would use the Promise class like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/924da892e798ea3af5c3aab2b9de838c/href">https://medium.com/media/924da892e798ea3af5c3aab2b9de838c/href</a></iframe><p>Now this design is already pretty close to the one of Task&lt;T&gt; which shows us that Task&lt;T&gt; is actually nothing but an implementation of a <a href="https://en.wikipedia.org/wiki/Futures_and_promises">promise</a> provided by .NET.</p><p>But what about async/await? Isn&#39;t that what makes Task&lt;T&gt; so powerful? Well, actually async/await is an compiler feature which is completely independent from Task&lt;T&gt; and the Task Parallel Library (TPL). To prove this, let&#39;s enable it for our custom Promise implementation as well.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/2f7d09794d495888a9b0140369a5d1e3/href">https://medium.com/media/2f7d09794d495888a9b0140369a5d1e3/href</a></iframe><p>Therefore, we just need to provide an API (e.g. an extension method) called GetAwaiter which returns a type or an interface which has the following properties:</p><ul><li>it implements INotifyCompletion</li><li>it provides an API called IsCompleted</li><li>it provides an API called GetResult</li></ul><p>And with this the compiler allows us to use async/await for the Execute API as usual.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/7378600032e120280ac3d6aefa34af62/href">https://medium.com/media/7378600032e120280ac3d6aefa34af62/href</a></iframe><p>In essence, that’s exactly how Task&lt;T&gt; works! So let&#39;s use it instead of our custom Promise implementation.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/6387e0ebd693a4d35b4e41f7a307c889/href">https://medium.com/media/6387e0ebd693a4d35b4e41f7a307c889/href</a></iframe><p>Quod erat demonstrandum.</p><p>Task&lt;T&gt; and async/await are quite convenient and powerful concepts when dealing with asynchronous APIs and concurrency BUT neither of these concepts is causing (!) threads or concurrency.</p><p>Full source code: <a href="https://github.com/plainionist/AboutCleanCode/tree/main/Promise">https://github.com/plainionist/AboutCleanCode/tree/main/Promise</a></p><p><em>Originally published at </em><a href="https://www.plainionist.net/What-is-Task/"><em>http://www.plainionist.net</em></a><em> on November 2, 2023.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e0e25fb60712" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>