Not every agent task needs a plan

A bug in Haze left the blur showing old content while a list scrolled underneath it. asqar’s report came with a minimal reproduction and a likely cause in the legacy Android rendering path. I asked the agent to check whether an earlier fix already covered it. It didn’t.

Once the investigation confirmed the stale capture, I asked it to fix the bug, with no spec or plan in between. We already knew what we wanted: the blur should update when the content moved.

That’s the choice I want to make with coding agents. Some tasks need a plan. Others need a diagnosis, a bounded change and a convincing check. Picking the right one matters more than running every task through the same stages.

How I got here

#

I used to use Superpowers. It’s a very good set of skills that connects design, planning, implementation and review into one process, which is valuable when the work needs thought before anyone changes code.

Over time, I wanted more say in how much of that process a task got. Even a small bug fix could involve brainstorming, a spec and an implementation plan when I already understood the problem. The specs and plans also regularly ended up committed to the repository, when they were really documentation for the agent doing one task.

That led me to Matt Pocock’s skills and some of my own, where I choose which stages to invoke. Two Haze tasks show what I mean.

A bounded fix still needs evidence

#

The scrolling bug became Haze PR #1367. On Android 11 and earlier, moving items in a lazy list could leave the blur sampling an old capture; the fix refreshes that capture when the list items move. With the cause and the intended behaviour understood, a plan would have had little left to decide.

The regression test showed the failure: after scrolling, the source changed from blue to cream while the blurred pixel stayed blue. With the fix, the blur followed blue → cream → blue.

Then an automated review from Greptile caught a weakness. If the blur disappeared entirely, the source underneath would still show the expected colours and the test would pass. Hiding the source behind an opaque cover meant the colours had to come from the effect. The device test passed, and the PR merged.

So skipping the plan didn’t mean accepting whatever the agent produced. Diagnosis, regression coverage and review all stayed, and review changed the evidence we relied on. I can go straight to implementation when I can state the intended behaviour, identify the affected area and explain how to check the result. If the investigation turns up a design choice or a wider dependency, that changes the decision.

When planning changed the shape of the work

#

In Haze issue #1274, winter-love-dev suggested that a newly public Android backdrop-rendering API could become a native backend for Haze, with the existing implementation as a fallback.

I worked through the proposal in an agent session. The main question was whether the new API could select particular content to blur, as Haze does. It turned out to sample whatever had already been drawn behind the effect in the same window. That difference mattered to callers, so the plan made the native path an explicit opt-in, with the existing implementation as a fallback. Existing callers would keep their current behaviour.

No written plan could settle whether the integration would actually render correctly, so the plan put a bounded prototype first, checking sampling, transforms and clipping before the full integration.

The implementation PR added the opt-in backend and fallback, with device acceptance tests and benchmark support. It left physical-device profiling pending and makes no performance claim. winter-love-dev had also been prototyping the idea locally, covering bounds, transforms and clipping, and offered to compare notes and help with testing.

Planning earned its place by settling behaviour that could have changed the public API, and by identifying what the prototype needed to prove. It required a discussion, a written handoff and a prototype gate. I can’t measure the time it saved, but it gave the implementation a more specific target.

Keeping documentation with the work

#

That example also shows a documentation gap: the plan stayed in the agent session instead of alongside the issue discussion. I particularly like how Matt’s to-spec skill turns a discussion into a spec and publishes it to the issue tracker. That’s where I want task-specific requirements, decisions and plans: next to the conversation about the work. Documentation that explains the system, such as architecture decisions, domain terminology and guidance for working on the project, still belongs in the repository.

Choosing a stage

#

The question I ask is: what’s still uncertain, and who needs the answer to do the work?

flowchart TD
    start([New task]) --> problem(Problem understood?)
    problem -- No --> investigate[Investigate the problem]
    investigate --> problem
    problem -- Yes --> choices(Behaviour settled?)
    choices -- No --> plan[Plan, and prototype risky assumptions]
    plan --> owners
    choices -- Yes --> owners(Separate owners?)
    owners -- No --> implement[Implement directly]
    owners -- Yes --> handoff[Make handoffs explicit]
    implement --> verify([Verify and review])
    handoff --> integrate[Implement and integrate]
    integrate --> verify
    %% Colours come from the flow-* classes in assets/css/custom.css.
    classDef question stroke-width:1.5px
    classDef step stroke-width:1px
    classDef done stroke-width:1.5px
    class start,problem,choices,owners question
    class investigate,plan,implement,handoff,integrate step
    class verify done

Whichever path a task takes, it still ends with verification and review. The table spells out what that means at each step.

For the third situation, my to-plan skill grounds the plan in the repository and records decisions and acceptance checks. In GitHub mode, I review a local draft before it posts the plan as an issue comment for an implementer. For a ready issue, for example:

/to-plan #123

For direct implementation, I use Matt’s implement or give the agent a direct instruction with the scope and verification I need. When separate implementation owners help, my implement-with-subagents can dispatch independent tasks concurrently and requires review of the integrated result. That adds handoff and integration work, so I want a reason to use it.

Once there’s a pull request, shepherd can follow through on review feedback and CI, though it still needs explicit permission to merge.

Trying one skill

#

The installation instructions cover Codex, Claude Code and OpenCode. With the skills CLI:

npx skills add chrisbanes/skills

For behaviour changes, implement-with-subagents needs Matt’s tdd skill, installed separately:

npx skills add mattpocock/skills --skill tdd

Matt’s implement calls his tdd and code-review skills, so follow his setup instructions if you use it. implement-with-subagents also needs an agent client that can run workers and an independent reviewer; installing the files doesn’t provide that.

What I want from any extra stage is an answer, a decision or evidence that the next person or agent needs to proceed.