Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mafsumo wants to merge 4 commits into
base: main
Choose a base branch
from
+136 −125
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c62224c
Update /jira skill with complete DOCS project field reference
mafsumo May 14, 2026
7f97477
Enhance Jira workflow enforcement and optimize CLAUDE.md
mafsumo May 15, 2026
8346620
Address Kim's review feedback on jira skill and CLAUDE.md
mafsumo Jun 5, 2026
57f8b32
Audit jira.md against live Jira API and update accordingly
mafsumo Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 91 additions & 50 deletions .claude/commands/jira.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Never suggest `brew install jira`, `npm install jira-cli`, or any other CLI tool

* **Jira project:** DOCS
* **Base URL:** https://sumologic.atlassian.net/browse/DOCS
* **Cloud ID:** 247075db-3b0b-4f1b-92db-51683ab743a6
* **Cloud ID:** 247075db-3b0b-4f1b-92cb-51683ab743a6

## Ticket intake

Expand All @@ -27,51 +27,44 @@ https://sumologic.atlassian.net/servicedesk/customer/portal/26/group/75/create/3
Tickets created via this command are created directly in the DOCS project and
are distinct from portal-submitted requests.

## Team members

| ID | Role | Atlassian Account ID |
|---|---|---|
| Writer 1 | Lead Technical Writer | 628bc65bc65b720069610ad1 |
| Writer 2 | Contractor Technical Writer | 712020:f4a4da3b-21a9-427c-8811-1b0a9f2e34f8 |
| Writer 3 | Contractor Technical Writer | 641adfd7407493675d473e16 |
| Writer 4 | Senior Technical Writer | 640862967655a3223a24ec90 |
| Writer 5 | Manager | 712020:250078b7-52c4-45fd-ac76-327e888c6768 |

## Technical Area → Writer assignments

Use this to set the default assignee when creating tickets, and to filter issues by owner.

| Technical Area | Writer |
|---|---|
| Alerts (Monitors, Sched. Search, Webhooks) | Writer 2 |
| APIs | Writer 1 |
| APM (Traces, RUM) | Writer 1 |
| Apps/Integrations | Writer 2 |
| Automation | Writer 4 |
| Cloud Infrastructure Security | Writer 4 |
| Cloud SIEM | Writer 4 |
| Cloud SOAR | Writer 4 |
| Collectors/Sources | Writer 2 |
| Dashboards | Writer 3 |
| Getting Started (Product/Observability) | Writer 1 |
| Getting Started (Security) | Writer 4 |
| Log Search | Writer 3 |
| Manage (Administrator) | Writer 3 |
| Manage (Analyst) | Writer 3 |
| Manage (Data Forwarding) | Writer 3 |
| Manage (Fields, FERs, Partitions, Data Tiers, Ingestion, Sched Views, Billing, Sharing) | Writer 3 |
| Manage (Security, Users, Roles) | Writer 3 |
| Metrics | Writer 4 |
| Mobot | Writer 1 |
| Observability (AWSO) | Writer 2 |
| Observability (Azure) | Writer 3 |
| Observability (Kubernetes) | Writer 4 |
| Observability (SLO) | Writer 4 |
| Observability (Tracing) | Writer 1 |
| Other | unassigned |
| Platform Services | Writer 4 |
| Sensu | Writer 4 |
| Threat Intelligence | Writer 4 |
## Technical Area values

**Assignee and due date are set automatically by Jira Automation** based on Technical Area and Priority — do not set these manually.

Use this list to select the correct Technical Area when creating or updating tickets:

- Alerts (Monitors, Sched. Search, Webhooks)
- APIs
- APM (Traces, RUM)
- Apps/Integrations
- Automation
- Cloud SIEM
- Cloud SOAR
- Collectors/Sources
- Dashboards
- Dojo AI
- Getting Started (Product/Observability)
- Getting Started (Security)
- Log Search
- Logs for Security
- Manage (Administrator)
- Manage (Analyst)
- Manage (Data Forwarding)
- Manage (Fields, FERs, Partitions, Data Tiers, Ingestion, Sched Views, Billing, Sharing)
- Manage (Security, Users, Roles)
- Metrics
- Observability (AWSO)
- Observability (Azure)
- Observability (Kubernetes)
- Observability (SLO)
- Observability (Tracing)
- Other
- Other (Analytics)
- Other (Optimization - GEO/SEO)
- Other (Site Development & AI)
- Platform Services
- Sensu
- Threat Intelligence

## Technical area keyword hints

Expand All @@ -84,17 +77,20 @@ Use these keywords and file path patterns to suggest the most relevant Technical
- **APM**: trace, span, RUM, real user monitoring, application performance
- **Apps/Integrations**: app, integration, connector, third-party
- **Automation**: automation, playbook, workflow, orchestration
- **Cloud Infrastructure Security**: CIEM, cloud security, infrastructure security
- **Cloud SIEM**: SIEM, security, threat, detection, rule
- **Cloud SOAR**: SOAR, incident response, security orchestration
- **Collectors/Sources**: collector, source, ingestion, data collection
- **Dashboards**: dashboard, panel, visualization, chart
- **Dojo AI**: Dojo, AI assistant, AI features
- **Getting Started**: onboarding, quick start, tutorial, getting started
- **Log Search**: search, query, log query, LogReduce
- **Logs for Security**: security logs, log analytics for security
- **Manage**: admin, user management, role, permission, account, billing, partition, field extraction
- **Metrics**: metric, time series, prometheus, graphite
- **Mobot**: mobot, chatbot, assistant
- **Observability**: AWS Observability, Azure, Kubernetes, SLO, service level, tracing
- **Other (Analytics)**: analytics, data analysis
- **Other (Optimization - GEO/SEO)**: SEO, GEO, AEO, search optimization, discoverability
- **Other (Site Development & AI)**: site development, AI tooling, Claude, documentation tooling
- **Platform Services**: platform, infrastructure, service
- **Sensu**: sensu, monitoring
- **Threat Intelligence**: threat intel, IOC, indicator
Expand Down Expand Up @@ -128,10 +124,10 @@ When invoked, ask the user what they want to do:

**Approach C - User provides file paths**: User provides specific file paths. Read the files to understand content and context. Analyze to determine Technical Area. Generate both title and description. Present all three for user approval.

For all approaches: Type defaults to Task unless user specifies Bug, Story, or Epic. Auto-assign based on the Technical Area → Writer assignments table. Use the Atlassian Account ID from the Team members table to set the assignee.
For all approaches: Type defaults to Task unless user specifies Bug, Story, or Epic. Do not set assignee or due date — Jira Automation sets both based on Technical Area and Priority.
* **Look up a ticket**. Search by issue key (e.g. DOCS-1234) or keyword.
* **Update a ticket**. Ask which field to update (Description, Assignee, Priority, or Technical Area).
* **Change ticket status**. Move through workflow states: To Do → In Progress → In Review → Done.
* **Change ticket status**. Move through workflow states: Backlog → To Do → In Progress → Blocked → In Review → On Hold → Published → Closed.
* **View my tickets**. Fetch issues in DOCS assigned to the current user. Default to open issues; ask if they want to filter by status.
* **View all tickets**. Fetch all open issues in the DOCS project, sorted by created date descending.

Expand Down Expand Up @@ -174,6 +170,51 @@ https://sumologic.atlassian.net/browse/DOCS-[issue number]

---

## DOCS Project Fields

When creating or updating tickets, these fields are available:

### Required Fields
- **Summary** (`summary`) - Ticket title
- **Technical Area** (`customfield_10748`) - Must be set from the allowed values (see Technical Area list above)
- **Preview Doc Requirement** (`customfield_10796`) - Defaults to "N/A (General Availability)"
- Options: "N/A (General Availability)", "Public Preview", "Extended Preview", "Private Preview"
- **Release Note Requirement** (`customfield_14728`) - No default; must be explicitly set
- Options: "Yes", "No"
- **Priority** (`priority`) - Defaults to " Medium" (Jira Automation also sets due date based on this)
- Use IDs to avoid API issues with leading spaces in names: High (id: 12023), Medium (id: 12024), Low (id: 12025)

### Optional Fields (set at creation)
- **Description** (`description`) - Always use markdown format
- **Existing Tech Docs Link** (`customfield_10750`) - URL to related existing docs
- **IMPORTANT:** Required when transitioning to Published status
- Always populate when creating/updating tickets that touch existing articles
- Use full production URL (e.g., `https://www.sumologic.com/help/docs/get-started/training-certification-faq`)
- **Parent** (`parent`) - Link to parent Epic/Story

### Post-creation fields (cannot be set at ticket creation — update after creating)
- **Assignee** - Set automatically by Jira Automation based on Technical Area; do not set manually
- **Due Date** (`customfield_10643`) - Set automatically by Jira Automation based on Priority; do not set manually
- **Github Pull Request** (`customfield_10466`) - URL field; auto-populate after PR creation
- **Product UI Link** (`customfield_14729`) - URL to product feature/UI in staging
- **Labels** (`labels`) - Array of strings

### When creating tickets with context:

**From git changes or file analysis:**
- Always set Technical Area based on file paths and content
- Default Preview Doc Requirement to "N/A (General Availability)" unless context suggests otherwise
- Set Priority by ID: use 12024 (Medium) unless urgent/critical
- Ask about Release Note Requirement if not obvious from context
- Populate Description with benefit-driven summary of changes
- **If creating/updating a ticket for an existing article:** Always set "Existing Tech Docs Link" (`customfield_10750`) with the full production URL (e.g., `https://www.sumologic.com/help/docs/get-started/training-certification-faq`)
- This field is required before tickets can be transitioned to Published status

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

---

## Related commands

* **`/doc-from-jira`** — if the goal is to write a doc for a ticket, use this instead. It fetches the ticket and scaffolds the full documentation file from its content.
120 changes: 45 additions & 75 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,17 @@ Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic sty
- .claude/skills/pr-template-guide/SKILL.md — PR template structure, formatting examples, and best practices.

## Pull Requests
**CRITICAL REQUIREMENT**: ALL pull requests MUST use the official template from `.github/PULL_REQUEST_TEMPLATE.md`. No exceptions.
**CRITICAL REQUIREMENT**: Before creating ANY PR, MUST read `.github/PULL_REQUEST_TEMPLATE.md` and use EXACT checkbox labels from that file.

### Key Rules
1. **Template is mandatory** - Use the exact structure above for every PR
2. **Additional sections** - Any extra sections (Summary, Testing Plan, etc.) go UNDER "Purpose of this pull request" heading, before "Select the type of change"
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. Current labels are: "Minor Changes", "Update Content", "New Content", "Site and Tools".
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)
Copy link
Copy Markdown
Collaborator

@kimsauce kimsauce May 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

@mafsumo mafsumo Jun 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

6. **Use full Jira link** - In the "Ticket (if applicable)" section, use the full URL (e.g., `https://sumologic.atlassian.net/browse/DOCS-1234`) not just the ticket number
5. **Ask for ticket number** - Always ask for a Jira ticket before creating a PR. If the user doesn't have one, offer to create it using the Atlassian Jira MCP (optional for quick typo fixes).
6. **Full Jira URL** - Use `https://sumologic.atlassian.net/browse/DOCS-1234` not ticket number alone

For detailed examples and implementation guidance, see `.claude/skills/pr-template-guide/SKILL.md`.
See `.claude/skills/pr-template-guide/SKILL.md` for examples and guidance.

## Git Rules
**CRITICAL**: Never commit, merge, or push changes without explicit user approval — even if "accept edits" is enabled. Always ask first.
Expand All @@ -39,81 +39,51 @@ Before pushing any commit that changes docs content:
3. Wait for explicit approval before pushing

## Jira Rules
- **Assignee**: Assign any newly created Jira ticket to the current user unless otherwise specified
- **GitHub PR link**: After creating a PR, automatically update the Jira ticket's GitHub field (`customfield_10466`) with the PR URL
**CRITICAL**: All Jira operations MUST follow the patterns defined in `.claude/commands/jira.md`.

### Field Requirements
- **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.md` for 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**: Always use `contentFormat: markdown`

### Workflow Requirements
- **Creating tickets**: Follow the three-approach pattern (user description, analyze changes, or file paths) defined in `.claude/commands/jira.md`
- **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: Backlog → To Do → In Progress → Blocked → In Review → On Hold → Published → Closed

### Publishing Checklist
Before transitioning any ticket to Published:
1. Verify "Existing Tech Docs Link" field is populated with production URL
2. Verify "GitHub Pull Request" field has the merged PR URL
3. Ensure PR has been merged to main branch

## GitHub Rules
- **Assignee**: Assign any new PR to the current user unless otherwise specified

## Capability Responses
When asked about tools, skills, or "what can I do," lead with documentation-focused skills
(doc creation, release notes, editing/review, Jira). Generic tools (Bash, Read, Write, etc.)
are secondary — the primary work here is writing and editing docs.

Proactively suggest relevant commands when context fits — for example, 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. Do not wait for the user to ask.

When a user asks "what can I do", "what commands are available", or similar, share this reference:

### Slash commands

**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 |
| `/tone-check` | Check voice and tone against Sumo Logic style rules |
| `/rewrite-intro` | Rewrite a doc's opening paragraph |
| `/simplify` | Simplify overly complex content |
| `/review` | Review a pull request |

**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 |

### Which audit command to use

Run both for a thorough pre-PR check — they cover different things:
## Slash Commands
Primary commands for documentation work. Proactively suggest when context fits — don't wait for the user to ask.

- **`/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
**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`, `/tone-check`, `/rewrite-intro`, `/simplify`
**Workflow:** `/jira`, `/review`

### `/jira` vs `/doc-from-jira`
**When to proactively suggest:**
- User mentions a Jira ticket → suggest `/doc-from-jira`
- User is about to create a PR → suggest `/seo-audit` first
- Doc needs discoverability improvements → suggest `/geo-optimize`
- User asks about doc quality → suggest `/audit-doc` and `/seo-audit` together

- Use **`/jira`** to manage tickets: create, search, update fields, change status, view your queue
- Use **`/doc-from-jira`** when you have a ticket and want to start writing the doc it describes — it fetches the ticket and scaffolds the file
**Key distinctions:**
- `/jira` = manage tickets | `/doc-from-jira` = scaffold doc from ticket
- `/audit-doc` = structure/style/links | `/seo-audit` = discoverability signals (run both before PRs)

## Commands

Expand Down