More claude stuff

[rickhanlonii]

Overview

Adds more claude stuff.

I iterated on this throughout the useOptimistic, useEffectEvent and useActionState doc revamps.

To create/update these, I had claude comb through the existing docs more throughly to create exhastive rules in each section, then i had it go over them with the skills superpower to consolidate the repetition into the right skills (e.g. voice things in the docs-voice skill). Rinse and repeat until it was working pretty well.

Then I had it run a verification plan where it would create some sham docs, and then run the /docs-reviewer on them, iteratively improving the skills for thing that the skills, or reviewer agent missed.

Finally, I had it do the useEffectEvent docs, and then edited them by hand to do an editorial pass, then had claude review the diff and update the skills needed to write it with my edits. I'll probably do that more in the future PRs and just land the claude files in each PR iteratively.

SKILL Improvements

• [new] docs-voice skill that consolidates and expands on the brand voice rules
• [new] docs-writer-blog skill for writing blog posts
• [updated] docs-writer-learn: expanded
• [updated] docs-writer-reference: expanded a ton
• [updated] docs-writer-components: expanded with all components
• [updated] docs-writer-sandpack: expanded with thing i found it missed

New /review-docs skill

The docs-reviewer agent was completely redone. Now there's a /review-docs skill that spawns a docs-reviewer agent for each skill (docs-components, docs-sandpack, etc). The reviewer agent creates a task list of things to review for that skill, and then reviews the the changes for conformance:

That gives an output of feedback at the end like this:

New /react-expert agent

Adds a /react-expert agent that understands concepts/APIs from the react repo using:

• react tests
• react PR descriptions / comments
• git commit history and messages
• issues referencing the API
• typescript / flow types

This thing is nuts, but really useful.

Workflow for editing docs

This prompt worked really well for useEffectEvent:

/superpowers:write-plan I want to rewrite the useActionState docs. Can you create a plan that will first use the /react-expert agent to understand the api, then take that research and create a task list for the use the docs-writer-reference skill write the new docs, and finally iterate with the /review-docs skill a minimum of 10 times to iterate on feedback?

Here's the plan it ran
And this commit was the output.

[github-actions]

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[rickhanlonii]

Oops i'll remove this, it should be in #8279

[josephsavona]

This is amazing! I love how we’re finally able to “encode” our style and voice for the docs into something more repeatable.

For the last example prompt you gave: you’re still orchestrating a bit w the prompt. should we have a higher-level skill for that? Eg should it be as simple as /skill-name write docs for <api>?

[rickhanlonii]

@josephsavona yeah for sure, I'm still iterating on that prompt a bit to see what works the best