1. Identify the Type of Work

Begin by clarifying what kind of work you’re capturing. This frames expectations for scope, detail, and workflow. Ask yourself:

• Am I describing a feature or user need?
• Is this a technical task required to support or improve the system?
• Is this a bug, and do I understand the conditions in which it occurs?
• Is this a research or discovery effort where the outcome is still unclear?

Understanding the nature of the work and selecting the right issue category ensures that others can interpret and prioritize it correctly.

2. Gather the Context

Before writing the ticket, collect the information someone else would need to understand what’s happening and why it matters. Think about what you’d want if you were picking up this work for the first time. Consider:

• Which part of the system or workflow is affected?
• What background or domain knowledge would help someone understand the issue?
• Are there related discussions, designs, tests, data points, or recent changes connected to this work?
• Are there dependencies or sequencing constraints that impact when or how this can be done?
• For bugs: can you provide clear steps to reproduce and evidence of the problem?

The goal is to eliminate guesswork for the next person who touches the ticket. 

3. Clarify the Desired Outcome

Next, define what “done” looks like. This helps align expectations across people who think in different dimensions like requirements, quality, technical implementation, or end-user experience. Reflect on questions like:

• What should be true once the work is complete?
• What behavior should change—and what should stay the same?
• Are there edge cases or constraints that matter here?
• What would help someone confidently say, “Yes, this is done”?

For user stories, capturing the business goal behind the work—the why—helps sharpen what the outcome should achieve and ensures teams build toward the right objective. Pairing a clear outcome with a clear rationale creates stronger acceptance criteria and reduces ambiguity throughout the development process.

4. Confirm You’re Ready to Write the Ticket

Finally, take a quick moment to ensure you’re bringing the complete picture into Jira. Before you write, ask yourself:

• Can I explain the work clearly to someone unfamiliar with it?
• Do I have the evidence and examples needed to support the request?
• Have I checked whether this issue (or something similar) already exists?

Once these pieces are in place, you’re ready to create a ticket that communicates clearly and serves your entire team well.

1. Open the Create Issue Form

The create issue form is simple, but the choices you make inside it determine whether the ticket provides clarity or creates confusion. Once you click Create, you’ll see the fields that define the work ahead. Each selection shapes how others will understand, size, and execute the request.

2. Select the Correct Project

Before entering details, make sure the ticket is being created in the right Jira project. Many teams maintain separate boards for different systems, products, domains, or workflows. A ticket placed in the wrong project can easily get lost, misrouted, or blocked in the wrong workflow, slowing progress before work even begins. It can also mislead an AI agent that uses the project board to determine context. 

3. Choose the Appropriate Issue Type

Select the issue type that best reflects the work you’re capturing. Common categories areStory, Task, Bug, Epic, Subtask, or Spike. Each category sets different expectations around scope, required information, and review. Choosing the correct type helps teammates and AI agents understand how to interpret and prioritize the ticket.

4. Write a Clear and Descriptive Summary

The summary is the headline that will appear across backlogs, boards, reports, and standups. It should immediately communicate the purpose of the work to anyone scanning the list. Avoid vague or overly broad titles; a clear summary prevents misinterpretation later.

5. Craft a Meaningful Description

The description is where the ticket becomes genuinely actionable. A good description ensures that someone unfamiliar with the context can still understand the problem or need. For example, for bugs, describe what’s happening, where it occurs, and how to reproduce it. If you’re describing features or improvements, explain the intent behind the work, the expected behavior, and what is in or out of scope.

If you’ve ever inherited someone else’s ticket and found it bafflingly sparse, you’ll appreciate why this step is so important.

6. Define Acceptance Criteria

Clarify what must be true for the work to be considered complete. Acceptance criteria act as shared success measures for whoever builds, tests, or reviews the work. When criteria are specific and testable, they reduce ambiguity and support consistent validation across roles.

7. Set Supporting Fields

Depending on your workflow, additional fields—such as labels, components, priority, or estimates—may be necessary. These fields influence planning, filtering, reporting, and routing, so filling them out accurately helps the broader team understand how this work fits into the larger picture. When possible, configuring these fields as selectable options rather than open text helps reduce friction and often leads to more consistent, complete entries.

8. Attach Supporting Evidence

Add any artifacts that make the ticket easier to understand and act on. Logs, screenshots, payload samples, monitoring snapshots, design files, and links to relevant discussions or code all help others grasp the full context without chasing additional information. And remember: AI agents’ effectiveness is directly tied to the information they receive upfront. The more explicit and specific information you include with your Jira ticket, the more value they can provide.

9. Review the Ticket for Completeness

Before submitting, take a moment to read the ticket as if you were encountering it for the first time. Does it tell a coherent story? Is it clear what needs to be done and why? Are the details sufficient for someone else to pick it up without additional explanation? A quick review ensures the ticket stands on its own.

10. Click Create

Once everything is in place, click Create and the ticket enters your engineering workflow. A well-crafted ticket sets your team up for smoother development, cleaner reviews, and fewer surprises downstream.

1. Add New Information as You Learn It

As the work unfolds, new insights, edge cases, or unexpected details almost always surface. Capture these directly in the ticket—either through comments or by updating the description—so the full history stays visible in one place. This ongoing record helps anyone who reviews, tests, or revisits the work later understand how it evolved and why certain decisions were made.

2. Keep the Ticket Status Accurate

Teams keep track of progress, coordinate handoffs, and identify blockers with statuses. Jira provides default statuses like To Do, In Progress, and Done, and many organizations also add custom ones such as Waiting on Clarification or Dev Complete to better reflect their workflows. A status that’s out of sync can skew reporting, misrepresent progress, and create confusion, so keeping statuses up to date is essential for maintaining clear visibility across the team.

3. Link Related Work and Dependencies

During implementation, you may create follow-up tasks, find related issues, or open pull requests. Link these items to the original Jira ticket so the relationships between pieces of work are clear and the path from requirements to code changes remains easily traceable. Jira’s linking features make it easier to track dependencies, understand how work connects, and ensure nothing gets overlooked across code, tickets, or systems.

4. Confirm the Work Meets the Definition of Done

Before marking a ticket as “Done,” ensure that all completion criteria have been met. That often means more than simply writing code. Tests should be updated, documentation may need revisions, feature flags might require adjustments, and monitoring or alerting may need to be added. A ticket closed too early can create downstream issues and may need to be reopened or transitioned back to an earlier status in the workflow.