Ambiguity, Specificity, and Sunshine: How AI Exposes Clarity Gaps

How AI is exposing the hidden gaps in your Organization — and how Clarity is the new Superpower in Engineering

AI doesn’t expose Intelligence or Skill gaps, rather it exposes Clarity gaps.

“The Models aren’t good enough yet” — I’ve heard this a bunch over the past year. The models are pretty darn good at this point. My team is shipping fully generated code without edits. It’s not the models. If you’ve heard this recently the issue may be something deeper.

The teams that struggle the most with these tools don’t lack for intelligence or skills. They are often overburdened with both. Their problem isn’t resources, it’s clarity of intent. Knowing what they are trying to accomplish and being able to articulate it clearly.

This isn’t new, software has always been a pursuit of precision but it’s being exposed by artificial intelligence and the new ways of working.

Meet Bruce the Cheese Plant

There are huge picture windows almost floor to ceiling in my apartment (the ceilings are 9’ high). I’ve been growing plants next to one of them for a while now, houseplants, vines, even some pineapple plants!

The window is flooded with light during the day. I think about the journey those photons have been on. They’ve each survived somewhere between 100,000 and a million years inside the fusion reactor we call the sun before escaping and traveling their final eight minutes and twenty seconds to Earth, where they finally wink out of existence after donating their energy to the plants. Thanks photons.

One plant in particular loves this arrangement, my cheese plant — Bruce.

Bruce’s limbs contort toward the light so that his leaves can absorb as much of it as possible. Some leaves never respond. Others seem to crave the light and crane themselves toward the window.

Bruce’s cells are opaque to me. I can’t control which leaves respond. I can’t explain why. All I can do is create the conditions for the plant to thrive.

LLMs work the same way¹ - we cannot look inside the model to figure out which Perceptrons, Weights, Features, Embeddings, etc. caused it to zig when it might’ve zagged.

The 0.001x Engineer: Why Writing Less Code Creates More Impact

When the shade is fully open the room fills with light. It reflects off the walls and becomes ambient, coming from every direction. Bruce grows every direction.

But when I close the shade and let only a narrow beam through, something interesting happens; Bruce focuses. The plant strains toward that single bright signal.

If the plant is the agent then the light is the objective. All I control is the environment and hence the signal.

When the signal is vague and diffuse, the behavior is vague and diffuse.
When the signal is precise, the plant aligns itself accordingly.

An Uncomfortable Mirror

When one of my colleagues recently started working with Claude her first reaction was

“What do I tell it?”

I said: “Anything you want.”

She paused for a moment and then said something prescient.

“Gosh… I’m going to need to improve my communication skills.”

Her first instinct was to look inward. That level of humility is pretty rare.

Humans are story tellers and pattern matchers and we are very good at filling in missing intent. When instructions are vague, a good engineer infers what you meant. The word “good” here is doing a lot of work. A “good” engineer, understands their job, has context, knows the environment, understands their dependencies upstream and down, understands the Quality bar that’s required to ship and much more besides.

Agents don’t do that. Agents start from a blank slate and execute what you said, literally and hopefully precisely but precision is hard when dealing with probabilities.

In a human-led workflow there’s an easy back and forth between colleagues to clarify what’s needed. When AI is in the loop and expected to work autonomously that makes ambiguity impossible to hide. Interview-mode and Planning are essential to set the task up for success.

Writing Forces Clarity

In my time at Amazon (almost 8 years) I hardly ever saw slides. Slides are simple to put together but they restrict your thinking to surface level bullets. They are easy to hide behind. Bullets on a screen let you gesture at a thought without ever finishing it. Writing a document on the other hand forces you to think deeply about a problem.

The famous six pager. Single spaced. No fluff. Long FAQ. That’s hard. You can’t write a document like that about something you don’t understand.

When we teach we learn twice. I think I know something, then I go to explain it to you and that explanation exposes the gap in my own understanding. Working with AI does the same thing. It holds up a mirror…and the mirror doesn’t lie.

You can’t get what you want….if you don’t know what you want.

A Lack of Clarity not Skills or Smarts

This transition is hard, in part, because it’s shining a light on things that were broken to begin with. That can be genuinely painful to reckon with. Especially if you’re the one responsible for why things are broken.

I’ve talked about it before in Burn the Boats — AI won’t fix what’s fundamentally broken in your org.

Burn the Boats! We're Never Going Back Again (...again)

It’s worth noting this is not a critique at all on Intelligence or your skills as a person. This workflow change is like a spotlight that shines brightest on organizational dysfunction and a lack of Clarity.

I’m Living It too (even before AI)

My first draft of this article was all over the place, it had five metaphors and almost no concrete examples.

That was my first clue.

I felt the intuition of what I was trying to say, but I hadn’t yet forced myself to articulate the mechanism. Writing forces your thoughts through the sieve of your fingers into the keyboard and they stare back at you from the screen. Sometimes they don’t look so great.

Engineering Is Shifting Toward Specification

Software engineering has traditionally been limited by how fast humans could produce code but that’s no longer the constraint.

The bottleneck is no longer implementation, it’s specification — describing systems clearly enough that machines can build them correctly.

I’ve talked before about the need to switch roles — from pair programmer to Orchestrator. The pushback I get is “yes but we still need humans in the loop” and I agree at least for now but the more we work in this new paradigm the more moments I see calling out that humans in their traditional roles are holding things back.

By letting go and assuming higher-order functional roles we start to see a step function improvement in Quality.

Some recent real-world examples;

1. Accidental Bug Discovery — The other day we set an Agent a task to change how we were processing some data. In the course of its work it found an undiscovered bug in the code through static analysis and offered to fix it. That bug was a corner case but legitimate and had existed unbeknownst to us for over a year. This code had been reviewed many times by our team. We took it up on its offer to fix it.

This makes me wonder and it’s an uncomfortable question; Does that human/manual code review really find the things you think it does?

2. Launch Readiness — A while back a team member (BB) made an awesome little fitness test during a hackathon. Everyone loved it, including our Instructors but we never felt it was launch-ready. Just as a thought experiment I sent an Agent on a mission to evaluate the launch readiness of this test through analysis of the code in Github. It produced a full detailed report across 13 different dimensions, including UX and Accessibility, Security etc. and we were much closer than we thought. That feature’s going to be live in the next month (hold me to it).

3. The Zero-Developer Code Change — We’ve recently started seeing full tickets driven to PR without a developer involved. The most recent complex example was an algorithm change but we’ve had success with UX Fit and Finish, Infosec and similar isolated and well defined tickets. This is an example of how software is proliferating through the org.

4. Agent Orchestration - In the past few weeks our team has prompted an Agentic Orchestration Platform into existence. Two people (TK and TM) pair programmed the first MVP to the point where it could spin up an Agent on access Github…and then turned it on it’s own codebase. This thing deploys Claude to K8s on demand and because it’s internal and we wrote it, it’s connected to all our relevant systems internally through MCP. With the MVP functional the engineers turned it on itself and afer a wild couple of weeks orchestrating and delegating it had written the remaining 80% of its own PRs.

This last example is how we’ve scaled access to AI within our group, alleviating the burden of setup for folks that don’t need it whilst simultaneously forcing collaboration and a shared common context. Maybe more on this in a future article.

What Good Specification Looks Like

Here’s where I’d start:

1. Lead from the front — About a month ago I literally drew a Miro with our entire SDLC lifecycle on it, from User Research, Product, Design, Development to Production Deployment and beyond and annotated and rewrote every place I thought we could simplify the process and leverage Agents, either synchronously or autonomously. Then I implemented a few examples (see previous examples). The diagram was nowhere near accurate but it was enough of a guide that it combined with the examples made the whole thing real for people. Asking teams to “use the tool” is not enough guidance and frankly not the point.

2. Define your Objective Function — Be Specific. Remove the ambiguity. You don’t even need to be good at writing prompts — I’m certainly not. I have Claude write precise prompts for me based on my loose articulation of what I’m trying to achieve. But that articulation has to be real. Concrete. If you can’t explain your goal, no amount of clever prompting will save you.

   1. e.g. “make sure the implementation will scale” might be an ok heuristic for a human but not nearly enough guardrails for an LLM. Versus “use an asynchronous call pattern with Kafka in the middle. Use Kafka Topic “xyz”... Use the team’s existing Service template. Make sure subsequent calls are idempotent. Assume no state on the server-side”, starts to be come much more directed and constrained.

   2. Optimize for:

      1. Functionality (highest priority)

         • No regression in existing functionality

         • All edge cases handled (nulls, retries, partial failures)

      2. Performance

         • P95 latency increase ≤ 5%

         • No additional synchronous blocking calls on critical path

      Tradeoffs:

      • Prefer reliability over performance

      • Prefer simplicity over cleverness

3. Measurement — Define your evals and break conditions. What you want cannot be hand-wavy. It must be measurable. If you can’t articulate what good looks like the agent won’t know either. Neither would a new employee. You wouldn’t hire someone and tell them “just make things better” — don’t do it to your agent.

   1. If an LLM is generating a service change, an eval function might include:

      • passes unit tests

      • preserves API contract

      • uses approved service template

      • handles retries idempotently

      • does not introduce new P1 security findings

      • latency increase < 5%

4. Provide Context — The agent is a blank slate. It doesn’t know your business, your team’s goals, your constraints, your history. Conduct a longitudinal assessment of your organizations knowledge base and internal documentation. How can you use that as context for the Agent before it attempts your directive? This should be a living set of documents that your whole group can iterate on over time.

Context; New Ways to use Old Knowledge

Machiavelli² took the historical texts available to him and did something no one had done before: he read them longitudinally, across time, looking for patterns. Of all the battles fought near rivers, what did commanders do, and what were the outcomes?

That meta-analysis gave us political science. A generation later, Galileo et al did the same with knowledge of the natural world. We got the Scientific Revolution and the Renaissance.

Your organization has so much institutional knowledge that can serve as powerful Context for your Agent. Confluence, Slack channels, GDocs - it’s easy to expose all of this through MCP — your job is to think about how to synthesize it in a new way so that it serves a new purpose in your Agentic workflow.

Don’t forget the untapped sources of insight, e.g. call transcripts from member support. Returns and Warranty claims. Social Media sentiment. These are all ripe for meta-analysis and easy to accomplish with LLM capabilities.

Survival of the “Fittest”

There’s a common misconception that by “fittest” Darwin meant the strongest or most athletic or physically robust. He actually meant most Adaptive; those that can “fit” into the given situation the best.

This moment is not going to be won by the people with the most impressive résumés, or the longest tenure, or the most polished slide decks. Curiosity and Humility win the day — be willing to look at the mirror and say “okay, I need to get better at this.”

Sunshine on a Cloudy Day

Louis Brandeis said that sunlight is the best disinfectant. He meant it about government transparency. I think it applies here too.

Superpower #33: Introspection

This moment is a genuine equalizer. The person who couldn’t attend college can now compete with the MIT graduate. The person whose career was derailed by circumstance, by a pregnancy, by an illness, by a layoff at the wrong time, can get caught up in a new field in a timeframe that would have been unthinkable a year ago.

The artificial advantages that used to compound silently in the background are losing their grip.

Bruce loves the sun and pursues it relentlessly. So close the shade. Narrow the beam. Give your team whether they’re Human or Agent one clear signal to grow toward … “and let’s be careful out there.” ³

How are YOU navigating this time? Have you found the secret unlock? Share your wisdom in the comments and let’s support each other through this time of change.

1. For more on this seek ye Chris Olah and Dario’s essays and research on the subject of Mechanistic Interpretability.

2. See the excellent book “Inventing the Renaissance” by Ada Palmer

3. Classic TV - Hill Street Blues - 1981 to 1987