> In fact (or IMO?), this "problems.md" document is entirely unnecessary. In many cases, simply describing the issue and providing the relevant context is enough for AI to come up with a working solution.

I don't mean to respond to your 'professional work' scenario, but I find it quite useful to first let it draft a PLAN.md, even when "in many cases" it would one-shot some implementation without it. I mostly prompt it with a problem statement, "write a PLAN.md", "ask me any questions in prose and numbered", "don't start implementation until my say-so". The back-and-forth questions are often pretty significant to the final result, and I can (skim) review the plan and make other adjustments.

When you ask most models to write that plan, you see an extended thinking trace similar to implementation itself, but now all the decisions are made up front. If you one-shot it an implementation, those decisions are sprinkled all over the implementation phase, while half of it has been written and some architectural choices have already been locked in. I then frequently adjust that plan to end up (IMO) with a much better implementation, or much better suited to my situation, with less shortcuts.

Yeah, I wouldn't do this for code that I was expecting anyone else to review.

This is actually the first time I've told an agent to write out a "problems.md" document - it was an experiment to see if stating the problem provided decent results, as opposed to working directly on a spec.

It did seem to work well though. I was outsourcing as much judgement as possible to the model, and the model did a good job at making decisions that got me to my required end result.

In this case, the AI could do the reasoning for me. Opus 5.5 and Fable 5.2 are really good!