DOCS-1640 - Consolidate Claude commands and add bulk change guidance

.claude/commands/audit-doc.md

@@ -1,26 +1,19 @@
 # Audit Doc — Documentation Quality Check
 
-Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness.
+Use this command to audit a doc for Sumo Logic style, structure, links, and frontmatter compliance — run it before submitting any PR, after creating a new doc, or when reviewing community contributions.
 
-## What this command does
+## Gotchas
 
-When you invoke `/audit-doc`, Claude will:
-
-1. **Read and analyze the specified doc file**
-2. **Check frontmatter**. Validate required fields and format
-3. **Review content structure**. Check headings, sections, and organization
-4. **Validate links and images**. Check paths, alt text, and references
-5. **Check style adherence**. Apply Sumo Logic style guide rules
-6. **Report findings**. Provide detailed feedback with specific line numbers
-7. **Suggest fixes**. Offer actionable recommendations
+- H1 headings and the `title` frontmatter field use **Title Case**. H2, H3, H4 use **sentence case** (only first word and proper nouns capitalized).
+- Skip warnings for legacy docs with an established style, docs tagged `noindex` (temporary drafts), or third-party content not meant to be modified.
+- `/audit-doc` does not check SEO/AEO/GEO signals — run `/seo-audit` separately for discoverability.
 
 ## When to use this command
 
 * Before submitting a PR to check doc quality
 * After creating a new doc to validate structure
 * When updating existing docs to ensure consistency
 * To identify broken links or missing images
-* To verify adherence to Sumo Logic style guidelines
 * When reviewing community contributions
 
 ## Workflow
@@ -67,7 +60,7 @@ Check for required fields and proper formatting:
 * [ ] Only one H1 heading (the title in frontmatter)
 * [ ] H2 sections used for main sections
 * [ ] No skipped heading levels (H2 → H4 without H3)
-* [ ] Headings use Title Case
+* [ ] H1 uses Title Case; H2, H3, H4 use sentence case (only first word and proper nouns capitalized)
 
 **Required sections (by doc type):**
 
@@ -301,53 +294,6 @@ After presenting the audit report, ask the user if they would like Claude to:
 * Unclear instructions
 * Not linked from parent page
 
-## Example usage
-
-### Basic audit
-
-```
-User: "/audit-doc docs/integrations/databases/postgresql.md"
-
-Claude:
-1. Reads the file
-2. Checks frontmatter (id, title, description, tags)
-3. Validates structure (headings, sections)
-4. Checks links and images
-5. Applies style guide rules
-6. Generates report with:
-   - 2 critical issues (missing image, broken link)
-   - 3 warnings (description too long, inconsistent formatting)
-   - 5 suggestions (add example, improve heading)
-7. Asks if user wants fixes applied
-```
-
-### Audit with doc type
-
-```
-User: "/audit-doc docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md --type c2c-source"
-
-Claude:
-1. Reads the file
-2. Applies C2C source-specific checks
-3. Validates vendor configuration section
-4. Checks authentication setup steps
-5. Verifies required sections present
-6. Reports findings specific to C2C sources
-```
-
-### Audit directory
-
-```
-User: "/audit-doc docs/integrations/security-threat-detection/"
-
-Claude:
-1. Finds all .md files in directory
-2. Runs audit on each file
-3. Generates summary report for all files
-4. Highlights files needing attention
-5. Provides batch fix option
-```
-
 ## Audit checklist summary
 
 Use this checklist template for the report:
@@ -420,63 +366,9 @@ Track common issues across multiple audits to identify systemic problems.
 * Validate CID URL mapping
 * Confirm cross-references
 
-## Tips and best practices
-
-**For effective audits:**
-* Run audit before requesting PR review
-* Fix critical issues first, then warnings
-* Use audit reports in PR descriptions
-* Re-run audit after making fixes
-* Consider doc type context (release notes vs feature docs)
-
-**Common quick fixes:**
-* Add missing frontmatter fields
-* Update relative link paths
-* Add language tags to code blocks
-* Fix heading capitalization
-* Remove trailing whitespace
-
-**When to skip warnings:**
-* Legacy docs with established style
-* Marketing pages with intentional tone
-* Third-party content that shouldn't be modified
-* Temporary draft content (with noindex tag)
-
-## Error handling
-
-**If file not found:**
-* Show error message
-* Suggest using Tab completion for path
-* Check if file was recently moved or renamed
-
-**If file is not markdown:**
-* Show error: "Audit only works with .md files"
-* Suggest appropriate file type
-
-**If doc type cannot be determined:**
-* Ask user to specify doc type
-* Provide list of supported types
-* Offer generic audit without type-specific checks
-
-**If many issues found (>20):**
-* Suggest focusing on critical issues first
-* Offer to generate summary instead of full report
-* Recommend gradual fixes in multiple PRs
-
-## References
-
-* [Sumo Logic Style Guide](/docs/contributing/style-guide)
-* [Contributing Guide](/docs/contributing)
-* [Doc Templates](/docs/contributing/templates)
-* [Docusaurus Documentation](https://docusaurus.io/docs)
-
----
-
 ## Related commands
 
-`/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not
-check SEO/AEO/GEO signals. For discoverability, run both:
+`/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not check SEO/AEO/GEO signals. For discoverability, run both:
 
 * **`/seo-audit`** — checks title length, description quality, question headings, GEO patterns
 * **`/geo-optimize`** — rewrites content to improve AI citation and search visibility
-* **`/tone-check`** — checks voice and tone against Sumo Logic style rules (standalone voice check)

.claude/commands/doc.md

@@ -1,18 +1,6 @@
 # Create New Doc
 
-Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides.
-
-## What this command does
-
-When you invoke `doc`, Claude will guide you through:
-
-1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting.
-2. **Gather information**. Title, description, file path, and keywords.
-3. **Create markdown file**. Generate file with proper frontmatter and basic structure.
-4. **Add to navigation**. Guide on adding to sidebars.ts.
-5. **Add to hub page**. Suggest adding card to parent index page.
-6. **Create CID mapping**. Add permanent URL if needed for UI links.
-7. **Validate and preview**. Check structure and provide next steps.
+Use this command to create a new feature doc, how-to, concept, reference, or troubleshooting guide — it scaffolds the file, frontmatter, structure, and sidebar entry.
 
 ## When to use this command
 
@@ -386,40 +374,6 @@ Before finishing, verify:
 * [ ] No negative contractions (use "cannot", "will not", "do not").
 * [ ] No trailing whitespace.
 
-## Example usage
-
-### Feature Doc Example
-
-```
-User: "Create a doc for the new access keys feature"
-
-Claude:
-1. Confirms type: Feature Documentation
-2. Gathers info: title, path, description, keywords
-3. Creates: docs/manage/security/access-keys.md
-4. Generates frontmatter with proper fields
-5. Scaffolds feature doc structure
-6. Guides on adding to sidebars.ts under Manage category
-7. Suggests adding card to docs/manage/security/index.md
-8. Asks if CID mapping needed
-9. Provides validation checklist
-```
-
-### How-to Guide Example
-
-```
-User: "Create a how-to guide for installing the OpenTelemetry Collector on Windows"
-
-Claude:
-1. Confirms type: How-to Guide
-2. Gathers info: title, path, description
-3. Creates: docs/send-data/opentelemetry-collector/install-collector/windows.md
-4. Generates frontmatter
-5. Scaffolds how-to structure with prerequisites and steps
-6. Guides on sidebar placement
-7. Provides checklist
-```
-
 ## Common patterns
 
 ### File path conventions
@@ -472,120 +426,3 @@ keywords:
   - reports
 ```
 
-## Safety principles
-
-* **Check existing files** before creating to avoid duplicates.
-* **Follow existing path conventions** in the category.
-* **Use descriptive filenames** that indicate content.
-* **Keep titles concise** but clear.
-* **Validate frontmatter** has all required fields.
-* **Use appropriate structure** for the doc type.
-
-## Post-completion message
-
-After successfully creating the doc, tell the user:
-
-```
-✅ Documentation file created successfully!
-
-File created:
-* 📄 {file-path}
-
-Summary:
-* Type: {doc-type}
-* Title: {title}
-* Category: {category}
-
-Next steps:
-1. Add content to the doc sections
-2. Add doc to sidebars.ts:
-   * Open sidebars.ts
-   * Find the {category} category
-   * Add '{doc-id}' to the items array
-3. Optional: Add card to hub page at {parent-index-path}
-4. Optional: Create CID mapping in cid-redirects.json
-5. Preview locally: yarn start
-6. Check preview at: http://localhost:3000/docs/{doc-path}
-7. Submit PR: "DOCS-XXX - Add {doc-title}"
-
-Checklist:
-* [ ] Content complete and follows structure.
-* [ ] Added to sidebars.ts.
-* [ ] Added to hub page (if applicable).
-* [ ] CID mapping created (if needed).
-* [ ] All links work.
-* [ ] Style guide compliant.
-
-The doc will appear in the navigation menu after you add it to sidebars.ts.
-
-Would you like me to help add content to any specific section?
-```
-
-## Error handling
-
-**If file already exists:**
-* Show existing file path and title.
-* Ask if user wants to:
-  * Edit existing file instead.
-  * Use different filename.
-  * Overwrite (requires confirmation).
-
-**If title is too long:**
-* Show character count.
-* Suggest shorter alternative.
-* Recommend using `sidebar_label` for long titles.
-
-**If path does not follow conventions:**
-* Suggest correct path based on category.
-* Explain repo conventions.
-
-**If no description provided:**
-* Explain importance for SEO.
-* Suggest generating description from title.
-
-## Tips and best practices
-
-**General:**
-* Start with a clear introduction that sets expectations.
-* Use second person ("you") to address readers.
-* Keep paragraphs short (2-4 sentences).
-* Use active voice.
-* Include concrete examples.
-
-**Structure:**
-* Use headings to organize content logically.
-* Put most important information first.
-* Group related information together.
-* End with related topics or next steps.
-
-**Links:**
-* Link to related docs for additional context.
-* Use descriptive link text.
-* Prefer relative paths for internal links.
-* Test all links work.
-
-**Images:**
-* Use images to illustrate UI steps or concepts.
-* Always include descriptive alt text.
-* Store images in `/static/img/` directory.
-* Optimize image file sizes.
-
-**Code:**
-* Specify language for syntax highlighting.
-* Keep code examples concise and relevant.
-* Include comments for complex code.
-* Show realistic examples, not placeholders.
-
-## References
-
-* [Style Guide](/docs/contributing/style-guide).
-* [Create or Edit a Doc](/docs/contributing/create-edit-doc).
-* [Sumo Logic Word List](/docs/contributing/word-list).
-
----
-
-**Note:** This command is for general documentation. For specialized content types, use the appropriate command:
-
-* **App integrations**. Use `/app-doc` for creating app documentation with standardized templates and structure.
-* **Cloud-to-Cloud sources**. Use `/c2c-source-doc` for Cloud-to-Cloud source integration documentation.
-* **Release notes**. Use `/release-note-cse`, `/release-note-collector`, `/release-note-csoar`, `/release-note-developer`, or `/release-note-service` for product release notes.

.claude/commands/geo-optimize.md

@@ -125,8 +125,7 @@ After the user confirms which changes to make:
 
 After applying changes, tell the user:
 - Which checks in `/seo-audit` this resolves
-- Whether any remaining GEO suggestions need a larger rewrite (offer `/rewrite-intro` if the opening paragraph needed major work)
-- Whether the doc would benefit from a `/tone-check` pass afterward
+- Whether any remaining GEO suggestions need a larger rewrite (offer to rewrite the opening paragraph if it needed major work)
 
 ---
 
@@ -227,4 +226,4 @@ After the first use, the abbreviation alone is fine.
 * Preserve technical accuracy above all else — if a rewrite would require fact-checking, flag it and ask the user to verify
 * Do not alter frontmatter except `description` if explicitly requested
 * Keep the Sumo Logic voice — do not make the doc sound like a Wikipedia article
-* If a section is very long and difficult to restructure safely, recommend `/rewrite-intro` or `/simplify` instead of attempting a full rewrite here
+* If a section is very long and difficult to restructure safely, flag it and ask the user how they'd like to proceed instead of attempting a full rewrite here