Improve AI system prompt to enforce Gutenberg blocks over custom HTML

[epeicher]

Adds a reference table of Gutenberg block equivalents for the most common
page patterns (hero, features, testimonials, pricing, FAQ, etc.) so the AI
has concrete guidance on how to replace core/html blocks with native blocks.

Also strengthens the HTML block check step (step 5) to be explicit and
mandatory, and clarifies the top-level principle around avoiding HTML blocks.

https://claude.ai/code/session_01DFErnsqRQDVsmDNYudL55G

[youknowriad]

Did you find that this improves the output. I tried a few things in the past but when testing, I was not certain about the results, it depended more on the prompt (site to be built) that I gave it and less on how I framed the system prompt.

[youknowriad]

So this is the prompt that I always use to test

"Build a one page site for a luxury furtniture brand called Auran, known for its precision and high quality manufactoring. Use Iconify Simple Icons for company logos that are clients (Nasa, SpaceX, Uber, Visa, Grab, bose, Discover, dji, Nikon, craftsman, sony). Use light colors"

And in my tests, this PR is still producing big sections of HTML blocks, maybe it's a bit less though, it's hard to tell.

I wonder if we should have a dedicated skill or validation tool that we call like we call take_screenshot would work or something. I have tried a few things already personally but I can't find the magic sauce just yet.

[epeicher]

I tried the following prompt for a real use case. The prompt was provided by a user with no technical background, as you can see is vague in technical details:

"I want a web page aimed at immigrants in Spain where the services of a lawyer are offered, and that specifies each of the services the lawyer provides. I want it to be simple and easy to understand. The procedures and processes offered on the web page correspond to the types of permits covered by the Immigration Law in Spain."

The result was great in look and feel, and even the content was good, ready for small amendments. But all blocks were HTML, so they were not easily editable.

After the changes in this PR, I have tried the same prompt again, but I'm afraid the result has been the same, all html blocks. After prompting to replace all HTML blocks with Gutenberg blocks, it works, but it would be great if it did that on the first try, without explicitly requesting those technical details.

I agree that adding a validation step that prevents those HTML blocks to be used unless strictly required is something to investigate. Currently, this suggested approach doesn't work as expected, so I might be closing this.

[sejas]

@epeicher , is this PR trying to solve STU-1439 ?

[epeicher]

Hi @sejas, I created this PR because I identified the issue on my testing, but I was not aware of STU-1439. I have now assigned to me the task STU-1439, and I plan to work on this. Please let me know if you have a suggestion for this, as this current approach doesn't seem to be working.

[youknowriad]

@epeicher My suggestion right now is to try to build a "code" tool. Something that parses the block and checks how many html block we have where the wrapper dom element is a "div", "section", "aside", "h1", "p"... If it exceeds some threshold (like 4) it fails, or if it's even 1 but the content of that blocks is a huge tree of nested divs... it fails as well.

In other words, I believe we should try a deterministic (code) tool that we call in a step like we do for the "validate_blocks" tool or "take_screenshot" tool.

[epeicher]

@epeicher My suggestion right now is to try to build a "code" tool. Something that parses the block and checks how many html block we have where the wrapper dom element is a "div", "section", "aside", "h1", "p"... If it exceeds some threshold (like 4) it fails, or if it's even 1 but the content of that blocks is a huge tree of nested divs... it fails as well.

In other words, I believe we should try a deterministic (code) tool that we call in a step like we do for the "validate_blocks" tool or "take_screenshot" tool.

Thanks for the suggestion @youknowriad, I will work on that approach

[epeicher]

Hi @youknowriad, I implemented an approach based on your suggestion in #3016. It required multiple iterations and some changes to the system prompt, as the agent seems to lean toward using core/html all the time. I left the PR as a draft for early review because I’m not sure whether the complexity of the changes is justified. It also couples the solution a lot to existing core blocks. I’d appreciate your thoughts on that.

I can also explore alternative approaches using skills, for example WordPress skills like this one, but I’d be interested in your opinion, especially if you’ve already tried similar approaches.