DOCS-1626 - Update /jira skill with DOCS project field reference by mafsumo · Pull Request #6701 · SumoLogic/sumologic-documentation

mafsumo · 2026-05-14T15:25:29Z

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

Documentation content
Website configuration
Release notes
GitHub repository updates (README, templates, CODEOWNERS, etc.)

🤖 Generated with Claude Code

Added comprehensive field documentation to the /jira skill including: - All required and optional fields with field IDs - Preview Doc Requirement options - Release Note Requirement field - Product UI Link and Existing Tech Docs Link fields - Guidance to populate Existing Tech Docs Link with production URL when updating articles - Field ID reference for programmatic ticket creation This ensures Claude Code can properly populate all relevant DOCS project fields when creating tickets, improving ticket quality and reducing manual updates. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

mafsumo · 2026-05-14T15:32:26Z

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

mafsumo · 2026-05-14T17:33:17Z

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

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

**Jira Skill Improvements:** - Added explicit requirement that "Existing Tech Docs Link" field is mandatory for Published transition - Clarified field must be populated when creating OR updating tickets for existing articles - Emphasized this prevents publishing workflow blocks **CLAUDE.md Optimizations:** - Reduced file from 180 lines to 102 lines (43% reduction) - Enhanced PR template enforcement with mandatory template read step - Added explicit anti-pattern list (never use "Documentation content", "Website configuration", etc.) - Expanded Jira Rules section with field requirements, workflow patterns, and publishing checklist - Consolidated slash command reference from 44-line table to 5-line summary - Improved delegation pattern: directive rules in CLAUDE.md, details in skill files **Workflow Impact:** - Prevents PR template violations by enforcing exact checkbox labels from source file - Ensures Jira tickets have required fields before publishing - Makes CLAUDE.md more scannable and maintainable - Better enforces consistency across all documentation workflows Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

mafsumo · 2026-05-15T13:56:05Z

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 · 2026-05-15T13:58:27Z

@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 · 2026-05-19T03:20:43Z

+2. **Use exact text** - Copy checkbox labels verbatim (never paraphrase: "Documentation content", "Website configuration", etc. DO NOT EXIST)
+3. **Keep all checkboxes** - Pre-check one box, leave all four in the list
 4. **PR title format**: `TICKET - Description` (e.g., `DOCS-1234 - Add PostgreSQL app`)
-5. **Ask for ticket number** - Always ask before creating PRs (optional only for quick typo fixes)


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.

kimsauce · 2026-05-19T03:20:43Z

+- **Assignee** (`assignee`) - Auto-assign based on Technical Area unless user specifies
+- **Description** (`description`) - Always use markdown format
+- **Priority** (`priority`) - Defaults to "Medium"
+  - Options: " High" (id: 12023), " Medium" (id: 12024), " Low" (id: 12025)


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.

kimsauce · 2026-05-19T03:20:43Z

+**After PR creation:**
+- Always update the Github Pull Request field with the PR URL using `customfield_10466`
+
+**Field IDs reference:**


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.

kimsauce · 2026-05-19T03:20:45Z

+- **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://help.sumologic.com/docs/get-started/training-certification-faq`)


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`)

kimsauce · 2026-05-19T03:26:09Z

-3. **Pre-check the appropriate checkbox** - Check the correct box but leave ALL four checkboxes in the list. Never remove unchecked items from the "Select the type of change" section
+**Non-negotiable rules:**
+1. **Read template first** - Get current checkbox labels from `.github/PULL_REQUEST_TEMPLATE.md` (never guess or use old labels)
+2. **Use exact text** - Copy checkbox labels verbatim (never paraphrase: "Documentation content", "Website configuration", etc. DO NOT EXIST)


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".

kimsauce · 2026-05-19T03:30:01Z

+- **Titles**: Sentence case, action verb, specific, under 10 words
+- **Descriptions**: Benefit-driven, active voice, under 150 words unless complex, markdown format
 - **Comment attribution**: Always append `— via Claude Code` to any comment posted to a Jira ticket
+- **Status transitions**: Use workflow states: To Do → In Progress → In Review → Published/Done


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 requested review from kimsauce and vfalconisumo as code owners May 14, 2026 15:25

mafsumo self-assigned this May 14, 2026

cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label May 14, 2026

mafsumo added the do-not-merge Pull requests that should not be merged label May 14, 2026

mafsumo requested review from JV0812 and amee-sumo as code owners May 15, 2026 13:55

kimsauce reviewed May 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

DOCS-1626 - Update /jira skill with DOCS project field reference#6701
mafsumo wants to merge 2 commits into
mainfrom
docs-update-jira-skill-fields

mafsumo commented May 14, 2026

Uh oh!

mafsumo commented May 14, 2026

Uh oh!

mafsumo commented May 14, 2026

Uh oh!

mafsumo commented May 15, 2026

Uh oh!

mafsumo commented May 15, 2026

Uh oh!

kimsauce left a comment

Uh oh!

kimsauce May 19, 2026 •

edited

Loading

Uh oh!

kimsauce May 19, 2026

Uh oh!

kimsauce May 19, 2026

Uh oh!

kimsauce May 19, 2026

Uh oh!

kimsauce May 19, 2026

Uh oh!

kimsauce May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- 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`)

	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".

Conversation

mafsumo commented May 14, 2026

Purpose of this pull request

What changed

Fields documented:

Ticket (if applicable)

Select the type of change

Uh oh!

mafsumo commented May 14, 2026

Uh oh!

mafsumo commented May 14, 2026

Uh oh!

mafsumo commented May 15, 2026

Session Improvements Summary

🎯 Jira Workflow Improvements

📋 PR Template Enforcement

⚡ CLAUDE.md Optimization

📊 Impact

Uh oh!

mafsumo commented May 15, 2026

Uh oh!

kimsauce left a comment

Choose a reason for hiding this comment

Uh oh!

kimsauce May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kimsauce May 19, 2026

Choose a reason for hiding this comment

Uh oh!

kimsauce May 19, 2026

Choose a reason for hiding this comment

Uh oh!

kimsauce May 19, 2026

Choose a reason for hiding this comment

Uh oh!

kimsauce May 19, 2026

Choose a reason for hiding this comment

Uh oh!

kimsauce May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kimsauce May 19, 2026 •

edited

Loading