DOCS-1626 - Update /jira skill with DOCS project field reference

[mafsumo]

Purpose of this pull request

Updates the /jira Claude Code skill with comprehensive field documentation for the DOCS project. This ensures Claude can properly populate all relevant DOCS fields when creating tickets via the /jira command, reducing manual updates and improving ticket quality.

What changed

• Added complete field reference including all required and optional fields
• Documented field IDs for programmatic ticket creation
• Added guidance to auto-populate "Existing Tech Docs Link" with production URL when updating articles
• Listed all Technical Area options, Preview Doc Requirement options, and other field values
• Included field ID reference table for easy lookup

Fields documented:

• Technical Area (required, customfield_10748)
• Preview Doc Requirement (required, customfield_10796)
• Github Pull Request (customfield_10466)
• Existing Tech Docs Link (customfield_10750)
• Product UI Link (customfield_14729)
• Release Note Requirement (customfield_14728)
• Due Date (customfield_10643)
• Priority options with IDs

Ticket (if applicable)

https://sumologic.atlassian.net/browse/DOCS-1626

Related to DOCS-1611 (DOCS Jira Project Overhaul)

Select the type of change

• Minor Changes - Typos, formatting, slight revisions
• Update Content - Revisions, updating sections
• New Content - New features, sections, pages, tutorials
• Site and Tools - .clabot, version updates, maintenance, dependencies...

🤖 Generated with Claude Code

[mafsumo]

Should not be merged until IT have completed all tasks, further commits pending (https://sumologic.atlassian.net/browse/DOCS-1611)

[mafsumo]

Also update Jira instructions in line 43 of main CLAUDE.md:

https://github.com/SumoLogic/sumologic-documentation/blob/main/CLAUDE.md?plain=1

[mafsumo]

Session Improvements Summary

After closing DOCS-1625 (which required the "Existing Tech Docs Link" field for publishing), identified workflow gaps and made the following enhancements:

🎯 Jira Workflow Improvements

Problem identified: The "Existing Tech Docs Link" field (customfield_10750) was not documented as:

• Required for Published transition (blocks publishing without it)
• Needed when creating tickets for existing articles (not just updates)

Fix applied:

• Added explicit requirement documentation in .claude/commands/jira.md
• Updated guidance to populate field at ticket creation when touching existing articles
• Prevents future publishing workflow blocks

📋 PR Template Enforcement

Problem identified: PR #6700 used incorrect checkbox categories:

• Used: "Documentation content", "Website configuration", "Release notes", "GitHub repository updates"
• Actual template has: "Minor Changes", "Update Content", "New Content", "Site and Tools"

Root cause: CLAUDE.md referenced the template but didn't enforce reading it or using exact labels

Fix applied:

• Added mandatory step: MUST read .github/PULL_REQUEST_TEMPLATE.md before creating PRs
• Added anti-pattern list of labels that DO NOT EXIST in template
• Prevents future PR template violations

⚡ CLAUDE.md Optimization

Problem identified: File had redundancy and was harder to scan (180 lines, 1,342 words)

Fix applied:

• Reduced to 102 lines, 700 words (43% reduction)
• Removed duplicate instructions and embedded template content
• Consolidated 44-line slash command table to 5-line summary
• Improved delegation: rules here, details in skill files
• Better enforces single source of truth principle

📊 Impact

✅ Prevents PR template violations via mandatory verification
✅ Prevents Jira publishing blocks via field requirement documentation
✅ Makes CLAUDE.md more maintainable and scannable
✅ Better enforces workflow consistency across the project

— via Claude Code

[mafsumo]

@kimsauce FYI ^ made some adjustments and optimizations to claude.md to hopefully ensure our PR template is properly followed. Also some further improvements to the jira section.

[kimsauce]

Two things worth flagging at the PR level:

1. This PR uses the wrong checkbox labels — the exact problem it's trying to fix.

The actual current template (.github/PULL_REQUEST_TEMPLATE.md) has:

- [ ] Minor Changes - Typos, formatting, slight revisions
- [ ] Update Content - Revisions, updating sections
- [ ] New Content - New features, sections, pages, tutorials
- [ ] Site and Tools - .clabot, version updates, maintenance, dependencies...

This PR selected Website configuration, which doesn't exist in that list. It's a live demonstration of the behavior the CLAUDE.md change is trying to prevent.

2. Proactive suggestion guidance was removed without a replacement.

The old ## Capability Responses section explicitly told Claude: "Proactively suggest /doc-from-jira when a user mentions a Jira ticket, /seo-audit before a PR, or /geo-optimize when a doc needs discoverability improvements." The new compact slash commands section says (proactively suggest when relevant) but gives no guidance on when or which commands to suggest. That behavioral guidance is worth preserving somewhere, even in compact form.

[kimsauce]

Was removing this intentional? Previously Claude would always ask for a Jira ticket number before creating a PR. Without this rule, Claude will create PRs without prompting — which may be the desired behavior, but worth confirming.

[mafsumo]

Restored and extended. Claude will now always ask for a ticket before creating a PR. If the user doesn't have one yet, Claude will offer to create it via the Atlassian Jira MCP. Typo fixes remain exempt.

[kimsauce]

Leading spaces before each priority label: " High", " Medium", " Low". If Claude passes these values to the Jira API, the request will fail or return a field validation error. Remove the leading spaces.

[mafsumo]

This one's actually a Jira API quirk — the live API returns " High", " Medium", " Low" with leading spaces as their real names. Stripping them would break name-based API calls. Updated the docs to keep the names as-is and added a note to set priority by ID (12023/12024/12025) to avoid the issue entirely.

[kimsauce]

Field IDs are already documented inline with each field above (e.g., customfield_10748 next to Technical Area). This reference table duplicates all of them. Pick one place — inline is more useful since it's right next to the field description.

[mafsumo]

Removed the reference table. Field IDs are already documented inline next to each field description, which is more useful in context.

[kimsauce]

legacy URL

Suggested change

	- Use full production URL (e.g., `https://help.sumologic.com/docs/get-started/training-certification-faq`)
	- Use full production URL (e.g., `https://www.sumologic.com/help/docs/get-started/training-certification-faq`)

[mafsumo]

Fixed — updated to www.sumologic.com/help/....

[kimsauce]

This parenthetical is too cryptic to be actionable. Saying these labels "DO NOT EXIST" tells Claude what's wrong but not what's right — and a future reader won't be able to infer the correct labels from this alone. Replace with the actual current labels:

Suggested change

	2. **Use exact text** - Copy checkbox labels verbatim (never paraphrase: "Documentation content", "Website configuration", etc. DO NOT EXIST)
	2. **Use exact text** - Copy checkbox labels verbatim. Current labels are: "Minor Changes", "Update Content", "New Content", "Site and Tools".

[mafsumo]

Fixed — replaced with your suggestion. Actual current labels now listed explicitly: "Minor Changes", "Update Content", "New Content", "Site and Tools".

[kimsauce]

The workflow states listed here don't match the actual DOCS Jira project. The real states are:

Backlog → To Do → In Progress → Blocked → In Review → On Hold → Published → Closed

The documented version is missing Backlog, Blocked, and On Hold, and uses "Done" instead of "Closed".

[mafsumo]

Fixed — updated to match the actual DOCS project workflow: Backlog → To Do → In Progress → Blocked → In Review → On Hold → Published → Closed.

[mafsumo]

Re: review-level feedback

Both fixed.

PR description now checks "Site and Tools" — fair catch, it was a live demonstration of the exact problem this PR was trying to prevent.

Proactive suggestion guidance restored with specific trigger examples: suggest /doc-from-jira when a user mentions a ticket, /seo-audit before a PR, /geo-optimize when discoverability is the concern. The compact version had stripped the specifics down too far.

[mafsumo]

Additional changes: Jira project field audit

I pulled the live field metadata from the DOCS project Jira API to validate accuracy with the latest DOCS project changes carried out by IT. Several things had drifted from what was documented in this PR:

Cloud ID typo — The Cloud ID in jira.md had a one-character typo (92db instead of 92cb). Would have caused all MCP API calls to fail silently.

Release Note Requirement is now required — The Jira API marks customfield_14728 as required: true with no default. It was documented as optional in this PR, which would have caused ticket creation to fail. Also confirmed as a mandatory submission field in the Documentation Process Confluence page. Moved to required fields.

Jira Automation owns assignment and due date — The Confluence process doc confirms that Automation sets both assignee (based on Technical Area) and due date (based on Priority). Removed the manual assignee logic, Team members table, and Atlassian Account ID references entirely. Claude no longer touches these fields.

Technical Area list was stale — Cloud Infrastructure Security and Mobot are no longer valid options in the DOCS project (using either would cause a field validation error). Five new areas were missing: Dojo AI, Logs for Security, Other (Analytics), Other (Optimization - GEO/SEO), Other (Site Development & AI). All updated.

Post-creation fields clarified — Due Date, Github Pull Request, Product UI Link, and Labels don't appear in the Jira creation metadata API, meaning they can't be set on initial ticket creation. Moved to a separate "post-creation fields" section so Claude knows to update them after the ticket is created.

Priority label spaces — Noted in the inline reply above, but worth flagging here too: the leading spaces in " High" etc. are real Jira API values, not a formatting error. Updated docs to use priority IDs instead of names to avoid the issue.

[kimsauce]

Approving with one caveat — although the Technical Area values match JSM, JSM doesn't match our internal Docs Team Responsibilities spreadsheet. So those would need to be aligned separately.