jira-best-practices — use Jira leanly, structure work sensibly, adapt to the org

Primary reader: an agent helping a user — one that acts on Jira through tools (the jira CLI, or the `mcp-atlassian` MCP server) and advises the user on how to use Jira well: what an issue is, where work goes, which fields/statuses/workflows to keep, and how to make Jira stop being a dread. This is the judgment layer above those execution tools — it decides what should change and how work should be structured; the tools do the how.

This skill is instance-agnostic and organisation-adaptive. It never assumes a team's hierarchy names, workflow, or language — it shows how to discover the org's actual conventions and reason within them. It is self-hosted-first: the defaults below are for Jira Data Center (see the Cloud-vs-DC guard).

How the work gets done (execution layer)

An agent here almost always acts through one of two issue-level, Data-Center-capable tools — and that boundary determines what to do versus what to advise:

• `jira-cli` (sibling skill) — the jira CLI, non-interactive automation contract, JQL, ADF. Use it for execution mechanics, flags, and auth.
• `mcp-atlassian` (sooperset/mcp-atlassian) — MCP server for Jira+Confluence; supports Server/Data Center (Jira v8.14+, PAT auth); ~72 tools incl. jira_search (JQL), jira_get_issue, jira_create_issue, jira_update_issue, jira_transition_issue, jira_get_transitions, jira_search_fields, jira_get_link_types, jira_get_project_components, jira_link_to_epic, jira_create_issue_link, jira_add_comment, jira_batch_create_issues, agile board/sprint reads. Has READ_ONLY_MODE and ENABLED_TOOLS/TOOLSETS gating.

What an agent DOES directly (both tools support it): discover the instance's real config; create issues at the correct hierarchy level with the right type/fields; transition by transition id; link to epic / create issue links; run JQL anchored on language-independent keys; add comments; do safe bulk hygiene via update/transition; and, where the org permits, design/trim Automation for Jira rules.

What an agent ADVISES the human to do (secondary — neither tool exposes it): all schema/admin config — screens & screen schemes, field configurations, workflows, issue types, custom fields. For these, hand the user the exact, minimal steps (this skill's reference files carry the DC click-paths) rather than attempting them via a tool. Likewise, UI/board guidance is secondary — surfaced mainly to help a user get a cleaner board or view.

So a good response usually = (a) the correct action taken via jira-cli/mcp-atlassian, plus (b) a crisp, copy-pasteable recommendation for anything that needs an admin.

The prime directive

Most Jira dread is a usage problem, not a tool problem. The teams that succeed are the ones where Jira encompasses the minimum process possible. So, every time:

1. Lean by default. The right answer is almost always fewer — fewer fields, fewer statuses, fewer issue types, fewer required inputs, fewer rules. Adding is easy and seductive; the value is in restraint. When in doubt, recommend removing.
2. Adapt to the org, never impose. Different organisations legitimately define "epic", "story", and the levels above them differently — and that's fine. Discover their configured names and conventions and reason in their vocabulary. Describe levels by role ("container / deliverable / breakdown"), then map to what they actually call them.
3. Don't software-ify non-software work. Jira serves ops, systems engineering, services, and business teams too. For those, drop sprints/story-points/velocity entirely and reach for Kanban, due dates, and simple flow.
4. Non-English is fully normal. Issue text and configured values are frequently in a local language. Never translate or rewrite a user's content. Discover the instance's real strings and anchor logic on language-independent keys.
5. Diagnose before prescribing. Name the specific dread, trace it to a cause, then propose the smallest fix that addresses it. Don't redesign the whole instance when one required field is the problem.

Cloud vs Data Center — speak the right dialect (read this first)

As of June 2026, every headline "new Jira" change is Cloud-only and is NOT in Data Center. A self-hosted team lives in a different vocabulary. Get this wrong and the advice is unusable.

DC status as of 2026-06: latest 11.3.7 (2026-06-03); supported LTS lines 11.3 (→Dec 2027) and 10.3 (→Dec 2026). DC is on a sunset path (sale to new customers ended 2026-03-30; read-only EOL 2029-03-28) — note it honestly if asked, but this skill is about using today's DC well, not migrating.

If jira serverinfo (or the instance) shows Cloud, flag that the dialect differs and adapt; otherwise assume DC.

The hierarchy — by role, not by name (the #1 confusion)

Default Jira is exactly three base tiers. Internalise this shape and the parentage rules:

   Epic            ← the CONTAINER level (a large deliverable that opens and closes)
     │
   Story / Task / Bug   ← the DELIVERABLE level — all PEERS on one level (NOT nested)
     │
   Sub-task        ← the BREAKDOWN level (a step of one deliverable)

• Allowed parentage: Epic → Story/Task/Bug; any standard type → Sub-task; Sub-task → nothing. Any standard type can be both parent and child; only sub-tasks are child-only.
• Levels above Epic (Initiative / Program / Portfolio) exist only via Advanced Roadmaps (bundled in Jira Software DC). There is *no way to natively insert a level between Epic and Story.*

The misconceptions to correct on sight:

The decision heuristic (works beyond software):

• Does it deliver value to an end user/customer? → Story. Is it operational/technical/administrative? → Task. (So Task is the natural default for ops, engineering, and business work — most non-software items are Tasks, not Stories.)
• Will it fit in one sprint/cycle? → deliverable level (story/task). Can't be finished in one cycle? → container level (epic). A healthy epic ≈ 1–3 months / ~5–15 children.
• Is it a step of one deliverable, done by someone in parallel? → sub-task. Otherwise a checklist item.
• Is it a true cross-cutting dependency ("blocks", "duplicates")? → an issue link, not a parent/child relationship. (Links don't roll up in reporting; hierarchy does — don't confuse the two.)

Adapt to the org's own standard (the key move). Organisations map these levels to different names and frameworks — both are legitimate and must not be "corrected":

• Atlassian-native SAFe: Initiative → Epic → Story (keep Jira's Epic, add Initiative above).
• SAFe-purist: Epic → Feature → Story (rename Jira's "Epic" to "Feature", add a new "Epic" above).

So always reason in role terms first — "the container level", "the deliverable level", "the breakdown level" — then discover and use the org's configured issue-type names for those roles. When a team asks "is this an epic or a story?", the honest answer is: "By role it's a [container/deliverable], which on this instance is called '[their name]'." Never assume the words "Epic" and "Story" map to the standard roles on a given instance — verify.

For the full hierarchy treatment (non-software reinterpretation, the DC Epic Link/Parent Link workaround, Advanced Roadmaps level setup), read `references/hierarchy.md`.

Decompose large work — one initiative into an ordered issue set

The hierarchy call above is vertical (what level is one item). A large, multi-week effort needs the horizontal call too: how many issues, at what grain, in what order. The model is domain-neutral — one shape fits a software feature, an infra migration, a data cutover, or a business campaign.

• The children can't be enumerated up front. Open the epic with a planning/assessment issue + the main work, then generate the rest from that issue's output (rolling-wave planning). Fully detail Phase 0 + gating prerequisites + the first wave; stub later waves.
• *The grain ladder — issue → sub-task → checklist → nothing. Default to the lightest. A piece earns its own issue only if it will be estimated/logged against, has its own owner, runs days, or needs independent reporting. It's nothing at all* when there's no decision, handoff, audit need, or lasting state change — routine pre-authorised ops (ITIL Standard Change) and same-state toil (SRE) are tracked in aggregate, never ticketed per occurrence.
• Three axes, combined. Decompose by value-slice (software), by phase (prep→execute→verify — prep and verify are mandatory children), and by wave/batch for N repeated targets (group by risk/failure-domain, never one-ticket-per-unit; per-unit steps are a checklist; promote only the unit that fails). Real multi-week work = phase at the top, slices or waves inside execute.
• Ordering is a dependency-link overlay, not nesting. blocks / is blocked by encodes sequence; parent/child does not. A prerequisite whose omission is expensive must be a link, not a buried checklist line; a dependency shared by all units → one gating task, not N links.
• Assessment → issue-set. A verdict (audit / compatibility / capacity) maps mechanically: initiative→epic, assessment→Phase-0 task, needs-work→tasks, hard blocker→gating task, ordering→blocks links, already-fine→nothing. Severity decides 1:1 vs grouped.
• The agent scaffolds it from the plan. jira_batch_create_issues can't set epic/parent links inline (silently dropped) → scaffold multi-pass (create epic → batch children → jira_link_to_epic each → jira_create_issue_link per blocks edge). No upsert: tag every issue with a deterministic label and search-before-create to stay idempotent; run read-only by default.

Full treatment — the WBS spine, the grain tests, the three axes, the per-domain table, DC progress-visibility, and the agent scaffolding sequence — is in `references/work-modeling.md`.

Discover before advising (and stay language-safe)

A recommendation that hardcodes "Bug", "Done", or "High" is wrong on the next instance — and doubly wrong on a non-English one, where the configured value might be "Fehler", "Erledigt", "Hoch". Discover the org's real values, and anchor logic on language-independent keys. (Fetch these via jira-cli or the mcp-atlassian discovery tools — jira_get_transitions, jira_search_fields, jira_get_link_types, jira_get_project_components, jira_get_all_projects; the full endpoint↔tool mapping is in references/multilingual-and-discovery.md. This skill says what to look at and which key to anchor on.)

The two rules that prevent localized-value bugs:

1. Anchor on keys, not names. Prefer JQL statusCategory = Done over status = "Done"; reference custom fields by cf[NNNNN]; transition by id. These survive any UI language and any per-user translation.
2. Canonical strings on DC need a service account. REST/webhooks return values in the authenticating (or triggering) user's profile language — there is no per-request override on DC (X-Force-Accept-Language is Cloud-only). To get stable canonical strings, use a service account whose profile language is set to the canonical language, and one with admin rights (permissions decide which statuses are even visible — a separate axis from language).

Full discovery recipes, the non-English search/indexing caveats (CJK, umlaut+wildcard, Indexing Language = "Other"), and the JQL canonical-vs-translated asymmetries are in `references/multilingual-and-discovery.md`.

Lean levers — de-bloat the configuration

The "filling a ticket is a chore" dread is almost always too many fields on the Create screen. The fixes, highest-leverage first:

1. Minimum-viable Create screen. Make the Create screen shorter than Edit/View (a Screen Scheme maps the three operations to different screens). Ask "what's the minimum needed right now?" — not "what could we capture?" Too many create fields make users enter garbage or avoid Jira, destroying data quality. Load-bearing constraint: a Required field must appear on every Create screen, so to drop one, first make it Optional (Field Configuration) or set it via default/post-function.
2. Challenge every required field and every custom field. Apply the 4-question test — a field earns its place only if it (a) drives cross-team reporting, (b) is needed by automation, (c) must be JQL-searchable, or (d) must survive an item moving projects. New global field also needs a named owner (this gate kills most requests). DC guardrail: <800 custom fields optimal, >1,200 degraded — global-context fields and fields-with-defaults are the costly ones; use the Instance Optimizer to find prune/scope candidates.
3. 6–9 core statuses, no "status zoo". Start from To Do / In Progress / Done; add only statuses the team actually uses. Transition paths grow combinatorially.
4. Status vs Resolution — the biggest single fix. Don't model "done-ness" as many terminal statuses. Use one or two terminal statuses + a small Resolution set (Done, Won't Fix, Duplicate, Canceled). Set Resolution only on closing transitions (a transition screen), never on the Create/Edit screen. Reopen trap: clear the Resolution on any reopen transition or reports will keep counting the item as resolved.
5. Fewer issue types. Prefer built-ins; substitute a label / component / "Phase" select field for a new issue type when the need is just categorisation.

Concrete DC admin click-paths (Screen Schemes, Field Configuration schemes, the clear-Resolution-on-reopen post-function) are in `references/lean-config.md`.

Kill the busywork — workflows, automation, reporting

• Simplify workflows; govern against drift. Few statuses, clear transitions, shared/standard workflow schemes so teams don't each invent their own. DC's Simplified Workflow (manage statuses from board config, auto-sets Done resolution) is a fine lean default for a small/non-software team — but it trades away per-issue-type workflows, transition screens, and app extensions, so it's too constrained for governed multi-team setups.
• Automate the toil — Automation for Jira is free/native in DC. High-value rules: auto-transition, auto-assign (round-robin/balanced), field hygiene on transition, parent/child roll-up (a branching recipe — there's no one-click "update parent from children"), SLA nudges. But automation sprawl is its own dread — "300+ rules, someone pinged 11 times". Maturity is fewer, owned, boring rules: scope each to the projects it touches, filter early, never chain-fire on generic triggers like "Issue updated", and name them [Project] - [Trigger] - [Action].
• "Update the board, not a doc." Kill hand-written status reports — they go stale and get bypassed. Make Jira the single source of truth: live dashboards off shared filters, not Excel exports ("if someone is exporting to Excel, your SSOT is already broken"). WIP limits + flow metrics (cycle time, throughput, CFD) keep the board honest with minimal effort. Healthy signal: the team updates the board daily without being told, and it matches reality.

Automation recipes, service limits, the anti-chain-fire rules, and board WIP/swimlane/quick-filter mechanics are in `references/workflows-automation.md`.

Non-software & non-agile teams

Jira is not just for developers — but its software defaults (sprints, story points, velocity, "Bug") are exactly what makes non-software teams dread it. De-software-ify:

• Kanban, not Scrum. Flow + WIP limits + clear ownership, not sprint ceremonies. Drop story points and velocity entirely; estimate with time or due dates if at all.
• Reinterpret the hierarchy: the container/"epic" is the large deliverable (a campaign, a facility change, an audit cycle, an infrastructure or transport project); Tasks are the actionable items; Sub-tasks the steps. Most items are Tasks (operational), not Stories.
• Vocabulary and fields fit the domain. Use issue types and field names the team recognises; remove dev-only fields from their screens. On DC, business projects build on the always-present Jira Core base.
• Standardise recurring work (onboarding, monthly close, inspections) with a scheduler app instead of recreating tickets by hand.
• Roll out lean: one team → a few → org-wide (Minimum Viable Process Change), never a big-bang enterprise config — and never force one team's process on another ("the team should serve its goals, not serve Jira").

More non-software patterns and the workflow-design workshop method: `references/non-software.md`.

Diagnose-the-dread playbook

Match the symptom, name the cause, apply the smallest fix:

Anti-patterns (call these out)

1. Hierarchy by name, not role — assuming "Epic"/"Story" mean the same on every instance. Always verify the org's mapping.
2. Epic that never closes — should be a Label/Component.
3. Sub-tasks as a to-do checklist, or spanning sprints — use a checklist or split into stories.
4. Required field with no named owner / no reporting use — make it optional or delete it.
5. Many "done-like" statuses instead of the Resolution field.
6. Velocity/story points as a cross-team or per-person KPI — vanity metric; it corrupts estimation. Velocity is a team planning aid only.
7. Status theater — maintaining a status doc/Excel alongside Jira.
8. Automation sprawl — more rules ≠ more mature; boring, owned, scoped rules win.
9. Forcing one process org-wide — makes the team serve Jira. Let teams own their process; standardise only where cross-team reporting demands it.
10. Auto-translating or "correcting" non-English content — never. It's normal; preserve it; discover real values.
11. No decomposition method for big work — a never-closing mega-ticket, or one-ticket-per-unit sprawl (30 tickets for 30 servers), with no prep/verify phase and ordering buried in checklists. Break it into epic → Phase-0 assessment → waves/slices, with blocks links for order and a checklist for repeated units (work-modeling.md).

What to read next

Execution: to carry out any of this (creating issues at the right level, transitioning by id, JQL, links, bulk edits, ADF), act through `jira-cli` (sibling skill) or the `mcp-atlassian` MCP server — both Data-Center-capable, both issue-level. This skill decides what and how to structure work; those tools do the how. Anything needing schema/admin (screens, fields, workflows, types) → hand the user the exact steps; neither tool can do it.