An interesting, and mostly unplanned, side-effect of the ongoing advancement of my personal agent orchestration system is that it has organized itself to produce high quality pull requests for Apache TinkerPop’s documentation. What I’ve found fascinating about these pull requests is that they are the polar opposite to the massive thousand line diff types agents can so easily produce for us and that we struggle to review and integrate into production. In contrast, these pull requests are small, usually affecting one file, and create a diff of 10 lines or less, making them astoundingly easy to review and merge quickly. I’ve found them to be of high value despite their size. I accidentally referred to them in a discussion with colleagues as Micro Pull Requests (MPR), as way to make their tiny stature stand out in a time where the idea of greater review burdens from agent generated content creates collective groaning sounds from the engineers who need to examine them. There is much discussion about the amazing, large bodies of code being produced by agents and how to handle that, but I think there is room to think about the MPR a bit as we continue to figure out how we can use agents to accelerate and expand our work.

What makes this worth writing about is not only the shape of the contributions, but where they come from. The same shift that put agents to work repairing documentation also put them to work reading it, and that second role is quietly changing what documentation is for and how much it costs us when it is wrong.

The agent system behind the pull requests

In a prior blog post titled Graphs, Agents, and the Characters Between, I described the importance of metaphor to help ground human connection to complex systems. One of the metaphors that I detailed was the one I use for operating my personal multi-agent orchestration system, a home grown tool that features characters like Monkeys for workers, a Toucan to help manage infrastructure and a Hammock from which I direct the work of this rain forest-inspired veil for an agent interface. Since the time of that writing, I’ve expanded the jungle considerably with a swimming pool area as an alternative place monkeys work, which correlates to a scalable, emphemeral remote agent instance set and a “human” administrative assistant, naming herself Miss Pemberton, who serves as the long-term memory for the jungle mapping to an IronClaw instance, handling reporting, automation and other tasks I want to offload.

It’s worth clarifying that while Pemberton (she told me it was acceptable to drop the formality of “Miss” if I preferred) has a broad view of what’s happening across the system, she also serves as the memory of the jungle. Her role is both coordination and recall. She observes the activity of monkeys, tracks the changes applied by Toucan, and retains context across builds, tickets, and schedules so that nothing is lost to time. Where she becomes particularly useful is in how she translates that accumulated awareness into action.

How the documentation testing works

One of the more effective responsibilities I’ve given her is ownership of an ongoing documentation testing effort against TinkerPop.

As Documentation Testing Manager, Pemberton identifies candidate sections of documentation and constructs test plans that frame a concrete goal based solely on what is written in the section. Because she maintains memory of what has already been tested, she avoids redundant effort and builds a growing ledger of coverage and findings over time. These plans are handed off to worker agents, monkeys operating in the pool, where isolation is cheap and parallelism is easy. The pool may grow or contract in accordance with the workload the jungle is seeing. A testing monkey attempts to execute the task exactly as a new user might, including making reasonable mistakes or assumptions along the way. A second monkey evaluates the attempt to ensure the result wasn’t achieved by implicitly filling in gaps the documentation failed to cover (i.e. this monkey tries to ensure the first didn’t “cheat” at the task). If the second monkey finds a gap, they also suggest a way to fill that gap.

It is worth pausing on what this arrangement actually is. The testing monkey is not standing in for a confused new user as a rhetorical exercise. It is an agent reading documentation in order to accomplish a task, which is increasingly what documentation gets read by. When it fails, it fails for the same reason a person would, which is that the instructions were wrong. The difference is that its failure is legible. The entire attempt is recorded, and a second agent is assigned to determine whether the docs earned the outcome or the first monkey quietly covered for them.

Pemberton takes this reporting and serves it to the jungle in much the way that I would, effectively asking a monkey to do a fix. In all transparancy, I’ve currently injected myself in the middle of this process to be sure I approve her asks, but after about twenty of these requests for monkey resources, I’ve not found anything egregiously wrong and if the monkey doing the work had sent these directly to a pull request, I don’t think I would have been disappointed.

What MPRs actually contain

It is at this point where we come back to my notion of the MPR and why my disappointment would have been absent if they were autonomously submitted. The fixes that emerge from this process are rarely sweeping changes. They don’t attempt to rewrite sections wholesale or introduce large new narratives. Instead, they target specific points of friction in an exacting way that involved multiple agents performing specific tasks meant to challenge one another in a coordinated fashion. In this way, they surface issues like:

  • A configuration value that no longer works as written.
  • An example that produces different output than what is shown.
  • A missing step in a defined process that an experienced user would infer, but a new user would not.
  • A statement that was once true, but has since drifted out of alignment with the code.

The size of these changes is not something I asked for. No one told the monkeys to keep their diffs small and there is no rule in the jungle capping the lines they are allowed to touch. The size falls out of the detection method. This style of adversarial documentation testing can only surface discrepancies at this grain, so it can only produce corrections at this grain.

That strikes me as the more useful finding. The standing complaint about agent contributions is that the diffs are too large to review, and the usual answers are better review tooling or more discipline in the prompt. This suggests a third option, which is to choose tasks whose findings are small by construction. Reviewability stops being a constraint imposed on the output and becomes a property of how the work was framed.

Individually, then, these MPRs are almost trivial to review. The reviewer can focus on a single, well-defined question: does this correction accurately resolve the discrepancy identified by the test?

Merged examples

Here are some examples that have merged:

  • #3533 - Remove stale/incorrect absent-key null-sort claim from order()-step docs
    • Detected that the documentation was making a false claim about order step. This was a remnant of documentation that should have been removed in 2022.
  • #3542 - Document that asBool() trims whitespace before parsing strings
    • Identified semantics that were missing from the asBool step.
  • #3543 - Fix inaccurate vertex label description in reference docs
    • Found a mistake in how the documentation referred to the actual shape of the sample data in a query example leading to conflict between the example and its explanation.

Why MPRs hold value

What has surprised me is not just how easy these are to review, but how consistently valuable they are. These are more than cosmetic edits and fix real points of failure in the onboarding experience and troubleshooting. These are the places where someone, or their agent, following the documentation would get stuck, confused, or misled.

In aggregate, they represent a steady tightening of the contract between documentation and implementation. This stands in stark contrast to the dominant (and interesting) narrative around agent-generated contributions. Much of the current discussion centers on scale: large diffs, end-to-end features, and the growing burden of reviewing work that no individual developer would reasonably produce in one pass. Those concerns are valid, but they are not the only dimension that matters.

There is also a reason work like this has been hard to sustain, and it is not that nobody cared. Any maintainer or technical writer would correct a stale line in minutes if something pointed them at it. The scarce resource is detection. Documentation drifts one commit at a time, quietly, and finding that drift means re-reading and re-executing material that mostly still works, with no signal indicating which of a thousand documented claims stopped being true last quarter. Code solved this problem with test suites a long time ago, where a broken assertion announces itself. Prose never got that, so verification stayed manual, and manual verification against a moving codebase is bounded by available attention no matter how much anyone cares.

What the monkeys supply is not better judgment than the people who wrote these docs. It is continuous coverage of a surface too large to keep re-reading. The MPR is simply what that coverage looks like when it finds something.

There is also a subtle but important shift in how work is initiated. These pull requests are not the result of a human deciding to improve a particular section of documentation. They are the byproduct of an ongoing, automated effort to verify that what we say matches what actually happens.

That loop, where we test, detect, and correct, runs continuously. Pemberton queues the work, informed by what she already knows, what new changes to the documentation arrive, and what remains untested. The monkeys execute it in isolation. Findings are evaluated and turned into fixes. And without much direct intervention, the system produces a steady flow of small, high-quality contributions. None of this replaces the need for larger, more intentional changes. But it does suggest that there is meaningful value in cultivating this other category of contribution—one that trades size for frequency, and breadth for accuracy.

Documentation as an operational surface

We’ve long thought of documentation as something to be repaired. The testing process quietly assumes something else, which is that documentation is something to be executed.

Consider what #3533 actually was. The reference docs made a claim about how order() handled absent keys that had been wrong since 2022. The cost of that error used to be bounded. A person reading it would write a query, get output that did not match the description, and go find out why. The documentation was wrong, but the reader had a feedback loop and a healthy instinct to distrust prose that disagrees with a result on screen. An agent reading that same sentence has neither. It holds no independent belief about how order() handles absent keys, has no sense that the sentence is four years stale, and feels no pull to go read the source and check. It writes the query, moves on, and the error surfaces somewhere downstream where tracing it back to a line of prose is considerably harder.

That is what shifts documentation quality from an editorial concern to an operational one. Stale documentation used to cost a reader some time. It is now an input to systems that will act on it directly, confidently, and at a volume no human readership ever reached.

Conclusion

If the industry is currently grappling with how to absorb massive agent-generated diffs, it may also be worth asking how we can better embrace the opposite extreme in the MPR. While I’ve focused the MPR on documentation, I sense that it has potential for wider applicability for granular, high quality code changes.

But the more durable finding, for me, is that these are two halves of one story. Agents are on both sides of documentation now, reading it and repairing it, and the repairs exist only because something is trying to use the docs and failing. The jungle produces a steady flow of small, high quality corrections precisely because it contains a population of readers that cannot skip past a sentence that does not hold. Keeping documentation honest used to be a discipline we asked people to maintain. It is becoming something a system can be arranged to do on its own, which is fortunate, because the cost of not doing it is going up.