[TASK] Refactor and Cleanup Claude-related Documentation for Usability and Developer Workflows

Description

Our Claude-related documentation has become cluttered and less helpful following expanded Claude adoption. The current docs focus too much on the 'what' and not enough on practical user intent and workflows. This has led to confusion, as evidenced in repeated questions and requests for clarification in our Slack help channels.

This task is to refactor and clean up all documentation related to Claude, with the following goals:

• Clarify structure and intent of docs used by Claude (especially in the .claude directory and any linked docs)
• Make it obvious how Claude consumes documentation as context, and how files interlink
• Provide clear, user-focused guidance for developers working on core—especially around using Claude via GitHub workflows (e.g., .github/workflows/issue_comment_claude-code-review.yaml provided by @dotCMS/ai-workflows)
• Emphasize how-to guides, limitations, troubleshooting, and best practices for using Claude in real-world code review and development scenarios
• Use real examples from Slack or developer feedback to illustrate common pain points or confusion
• Reduce duplication, cross-link appropriately, and remove unnecessary busywork or outdated content

Acceptance Criteria

• Docs are reorganized to prioritize user/developer workflows and real-world tasks
• Key journeys (e.g., How to use Claude for code review via GitHub comments) are clear and discoverable
• The relationship between .claude/, linked docs, and workflow files is documented
• Duplicative or busy information is removed or replaced with cross-references
• At least two real-world examples of confusion from Slack or developer feedback are included
• Troubleshooting, limitations, and usage tips are provided for both human and AI (Claude) consumers
• The refactor follows principles outlined in docs/claude/DOCUMENTATION_MAINTENANCE.md

Priority

Low

Additional Context

See docs/claude/DOCUMENTATION_MAINTENANCE.md for maintenance guidelines. Also review recent Slack conversations for examples of confusion or repeated questions about Claude usage and documentation. The .github/workflows/issue_comment_claude-code-review.yaml workflow and its connection to @dotCMS/ai-workflows should be described and clarified.