This file is the canonical source of context and guardrails for AI coding agents (Claude Code, Cursor, GitHub Copilot, Codex, etc.) working in this repository. CLAUDE.md is a one-line pointer to this file, kept only because Claude Code looks for that filename specifically.
Open-source Sumo Logic documentation site built with Docusaurus 3. Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic style guide.
This repo takes contributions from both Sumo Logic employees and external community contributors (see docs/contributing for the fork-and-PR workflow external contributors follow). Most of this file — the skills, directory conventions, frontmatter rules, and slash commands below — works the same for anyone with the repo cloned and Claude Code installed. The exception is anything under Jira Rules and the Jira-specific steps in Pull Requests: those require internal Sumo Logic Atlassian access, so external contributors should skip them and follow the plain PR steps in docs/contributing instead.
@https://github.com/SumoLogic/sumologic-documentation
@https://github.com/SumoLogic/sumologic-documentation/tree/main/docs
.claude/skills/sumo-style/SKILL.md— Sumo Logic writing conventions. CRITICAL: Always invoke this skill before writing or editing any file in/docs,blog-service,blog-collector,blog-cse,blog-csoar, orblog-developer. Do not wait to be asked. The skill fetches the live style guide and word list — both must be applied to every PR, including release notes..claude/skills/docusaurus/SKILL.md— Docusaurus 3 syntax, frontmatter templates, and sidebar config patterns..claude/skills/pr-template-guide/SKILL.md— PR template structure, formatting examples, and best practices..claude/skills/geo-guide/SKILL.md— Reference guide of GEO principles and patterns loaded as context by/geo-optimizeand/seo-audit. Not an invocable command.
When reviewing any PR or doc, always check existing docs of the same type in the same directory before flagging issues. A pattern consistent with neighboring docs is not a bug — it is the established convention. Only flag it if it's a deviation from the pattern or a net-new problem introduced by the PR.
Some directories have conventions that differ significantly from standard docs. For example, /docs/integrations/automation-integrations/ intentionally uses description: '', omits id, opens with a logo image, and includes a ***Version / Updated*** block — all correct for that directory. When in doubt, read two or three neighboring files before forming an opinion.
A comment Claude posts should read as though a person wrote it. This section governs the prose in GitHub PR comments, GitHub issue comments, and Jira ticket comments.
Run the humanizer skill on the draft of every comment before posting it. Use the skill's embedded mode, which returns only the final text. It rewrites the patterns that mark prose as machine-written, keeps the meaning, and leaves code, commands, paths, and link targets alone. This is not a manual step to be requested; it applies to every comment.
The following hold whether or not the skill runs:
- No em dashes. Rewrite with a period, semicolon, colon, commas, or parentheses.
- Be concise. Lead with the point. No throat-clearing preambles, no filler ("simply", "just", "of course", "it's worth noting"), no sentences that restate what was just said.
- Plain language. Short sentences, one idea each. When two phrasings say the same thing, use the shorter one.
On a PR, use inline comments whenever possible. Attach each point to the line or file it refers to instead of collecting everything in one top-level comment. Reserve a single summary comment for feedback that is not tied to a specific line, such as overall scope or a concern that spans several files.
For any change touching 50+ files (e.g. terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules:
Enter plan mode at the start of any bulk change. Present scope, file count, directory breakdown, and before/after samples — then wait for explicit approval before touching any files.
- Define scope first, get sign-off. State the exact pattern, included paths, excluded paths, and known edge cases before touching files.
- Dry-run before writing. Report total file count, per-directory breakdown, and ~10 before/after samples. Wait for confirmation.
- Apply in batches by directory, not all at once. Show
git diff --statand a few spot-checks after each batch. - One commit per batch/category — never bundle multiple directories into one commit. Atomic commits stay revertable.
- Never revert from memory. If reverting, validate against actual file content — do not trust "the original had X."
- Never commit helper/detection scripts to the repo. Run them ephemerally.
Every doc requires at minimum: id, title, description. New docs also need a sidebar_label if the title is long.
CRITICAL: Never add a slug field unless explicitly requested — it overrides the URL path derived from the file location.
- Start dev server:
yarn start— use this to preview changes locally
CRITICAL REQUIREMENT: Before creating ANY PR, MUST read .github/PULL_REQUEST_TEMPLATE.md and use EXACT checkbox labels from that file.
Non-negotiable rules:
- Read template first - Get current checkbox labels from
.github/PULL_REQUEST_TEMPLATE.md(never guess or use old labels) - Use exact text - Copy checkbox labels verbatim from the template file. Example current labels: "Minor Changes", "Update Content", "New Content", "Site and Tools" — but always read the file, these may be outdated.
- Keep all checkboxes - Pre-check one box, leave all four in the list
- PR title format:
TICKET - Description(e.g.,DOCS-1234 - Add PostgreSQL app) - Ask for ticket number - Always ask for a Jira ticket before creating a PR, and offer to create one if the user doesn't have one (Claude Code: use the Atlassian Jira MCP). Exception: this ticket requirement is optional for quick typo fixes and externally-submitted PRs.
- Full Jira URL - Use
https://sumologic.atlassian.net/browse/DOCS-1234not ticket number alone
(Claude Code: see .claude/skills/pr-template-guide/SKILL.md for examples and guidance.)
CRITICAL: Never commit, merge, or push changes without explicit user approval — even if auto-accept is enabled. Always ask first.
Branch naming: Branch names must always be the Jira ticket number only (e.g., DOCS-1697). No additional description.
Before merging any PR, provide the user with the commit description and wait for explicit approval.
Before pushing any commit that changes docs content:
- Run
yarn start(if not already running) - Tell the user to confirm the changes appear correctly on the site
- Wait for explicit approval before pushing
CRITICAL: All Jira operations MUST follow the patterns defined in .claude/commands/jira.md. This section applies to Sumo Logic employees only — external contributors don't have access to the internal Jira instance and should skip it.
- Assignee: Do not set manually — Jira Automation assigns based on Technical Area.
- Technical Area: REQUIRED field. Must be set from allowed values. Use file paths and content keywords to determine the correct area (see
.claude/commands/jira.mdfor mappings). - Existing Tech Docs Link (
customfield_10750):- REQUIRED when transitioning to Published status
- MUST be populated when creating or updating tickets that touch existing articles
- Use full production URL (e.g.,
https://www.sumologic.com/help/docs/get-started/training-certification-faq)
- GitHub PR link (
customfield_10466): After creating a PR, automatically update this field with the PR URL - Description: Use
contentFormat: markdownfor text-only fields. Switch tocontentFormat: adfwhen the field contains, or should keep, anything markdown cannot represent: attached images and other media nodes, panels, expand/collapse blocks, status lozenges,@mentions, date nodes, or column layouts. Jira Cloud stores rich text as ADF, and markdown is a lossy conversion layer over it, so rewriting a description as markdown silently deletes those nodes. On read, a media node comes back as aplaceholder that is not a usable image source; writing that back destroys the attachment. Fetch the field as ADF first when you are unsure what it contains.
- Creating tickets: Use one of three approaches — a user-provided description, analysis of the code changes being made, or the file paths touched. (Claude Code: see
.claude/commands/jira.mdfor the concrete pattern and Technical Area mappings.) - Titles: Sentence case, action verb, specific, under 10 words
- Descriptions: Benefit-driven, active voice, under 150 words unless complex, markdown format
- Comment attribution: Never append Claude attribution to a Jira comment. Do not add
— via Claude Codeor any similar marker. This is enforced by a PreToolUse hook (see GitHub Rules for details), and the same rule covers GitHub and Slack. - Comment format: Jira comments are stored as ADF, and
contentFormat: markdownis a lossy conversion layer over it. Markdown is fine for plain prose, which covers most comments. UsecontentFormat: adfwhen the comment needs something markdown cannot express: an@mention, an image, or a panel. This matters most for mentions, since a markdown@Nameposts as literal text and notifies nobody; a real mention is an ADF node carrying an account ID. - Status transitions: Use workflow states: Backlog → To Do → In Progress → Blocked → In Review → On Hold → Published → Closed
Before transitioning any ticket to Published:
- Verify "Existing Tech Docs Link" field is populated with production URL
- Verify "GitHub Pull Request" field has the merged PR URL
- Ensure PR has been merged to main branch
- Assignee: Assign any new PR to the current user unless otherwise specified
- Comment attribution: Never append Claude attribution to a comment. Do not add
— via Claude Codeor any similar marker. This covers GitHub PR review comments, GitHub PR issue comments, Jira ticket comments (see Jira Rules), and Slack messages. A PreToolUse hook (.claude/hooks/forbid-claude-attribution.sh, wired up in.claude/settings.json) blocks any call carrying the marker, so compliance does not depend on remembering the rule.
Three pieces work together and should be kept in sync when touching any of them:
src/plugins/markdown-mirror.jsmirrors every/docspage as raw Markdown at/help/llm/docs/{path}, for AI crawlers/agents to consume — not for Algolia site search. It also generates/help/llm/docs/index.txt(every mirrored path) and stamps the "Last updated" date instatic/llms.txt.static/robots.txt(in this repo, PR-editable) explicitly welcomes general AI/LLM crawlers and points them to/llms.txt, but disallows theAlgolia Crawleruser-agent from/llm/specifically, so the raw Markdown mirror doesn't get pulled into site search results.- Algolia Crawler Admin (external, NOT stored in this repo — no config file to edit via PR) runs the actual site-search crawl (index
sumodocs) and separately excludeshttps://www.sumologic.com/help/llm/**via its ownexclusionPatterns, redundant with the robots.txt rule above.
If you change the /help/llm/ URL structure or add new machine-readable mirror paths: update robots.txt in this repo, and tell the user that the Algolia Crawler Admin's exclusionPatterns need a matching external update since that config can't be reached via a PR.
static/llms.txt is a separate, hand-curated file distinct from the per-page Markdown mirror above — it's an index (product overview, primary audiences, prioritized doc links) aimed at AI answer engines/crawlers reading the published site, not at coding agents working in this repo. The markdown-mirror.js plugin only auto-stamps its "Last updated" date; the list of linked docs is maintained manually and is a curated subset, not exhaustive. When adding, moving, or removing a doc page that belongs in that curated index, check whether static/llms.txt needs a matching update.
The sections below apply only to Claude Code. Other agents can ignore them.
All Jira operations MUST follow the patterns defined in .claude/commands/jira.md, including the three-approach ticket-creation pattern and Technical Area mappings. Requires internal Atlassian access — not available to external contributors.
Primary commands for documentation work. Proactively suggest when context fits — don't wait for the user to ask.
Content: /doc, /doc-from-jira, /app-doc, /c2c-source-doc, /remove-doc
Release notes: /release-note-service, /release-note-collector, /release-note-cse, /release-note-csoar, /release-note-developer
Quality: /audit-doc, /seo-audit, /geo-optimize
Workflow: /jira, /docs-pr-reviewer
Staging: /stage-deploy, /stage-teardown, /review-deploy, /review-teardown
When to proactively suggest:
- User mentions a Jira ticket → suggest
/doc-from-jira - User is about to create a PR → suggest
/seo-auditfirst - Doc needs discoverability improvements → suggest
/geo-optimize - User asks about doc quality → suggest
/audit-docand/seo-audittogether - An SME/stakeholder without a local dev environment wants to apply their own edit to an existing PR (not just view or approve it — those happen directly on the PR's staging link and GitHub page) → suggest
/docs-pr-reviewer - A PR needs a live preview before merge → suggest
/stage-deployfor UX/UI or feature work,/review-deployfor quick article-level review
Creating docs
| Command | What it does |
|---|---|
/doc |
Create a new feature, how-to, concept, reference, or troubleshooting doc |
/doc-from-jira |
Fetch a DOCS Jira ticket and scaffold a complete doc from it |
/app-doc |
Create a new app integration doc |
/c2c-source-doc |
Create a new Cloud-to-Cloud source integration doc |
Release notes
| Command | What it does |
|---|---|
/release-note-service |
New service release note |
/release-note-collector |
New Collector release note |
/release-note-cse |
New Cloud SIEM release note |
/release-note-csoar |
New Cloud SOAR release note |
/release-note-developer |
New developer/API release note |
Editing and reviewing
| Command | What it does |
|---|---|
/audit-doc |
Full quality audit: structure, style, links, frontmatter, completeness |
/seo-audit |
Discoverability audit: SEO, AEO, and GEO signals — run this before a PR |
/geo-optimize |
Rewrite a doc to improve AI citation and generative engine visibility |
Jira
| Command | What it does |
|---|---|
/jira |
Create, update, search, or transition DOCS Jira tickets |
/doc-from-jira |
Start a new doc from a Jira ticket (use this instead of /jira when the goal is to write a doc) |
Removing docs
| Command | What it does |
|---|---|
/remove-doc |
Safely deprecate or move a doc with redirects |
PR review
| Command | What it does |
|---|---|
/docs-pr-reviewer |
Apply an SME's self-serve edit to an already-open PR (no local env needed) |
Staging
Run both for a thorough pre-PR check — they cover different things:
/audit-doc— structure, required sections, broken links, frontmatter completeness, style guide/seo-audit— SEO/AEO/GEO signals: title length, description quality, question headings, direct answers, GEO patterns
- Use
/jirato manage tickets: create, search, update fields, change status, view your queue - Use
/doc-from-jirawhen you have a ticket and want to start writing the doc it describes — it fetches the ticket and scaffolds the file