An issue description should comprehensively detail the work required. It should clearly convey the value of the work while providing sufficient detail to make informed technical decisions aligned with the request’s objectives. Descriptions should focus on outcomes, not just technical implementation. Keeping work items outcome-focused makes it easier for people unfamiliar with a specific domain to understand what we are trying to achieve.
The key to an impactful description is to make it customer-focused. The “customer” could be an end user, a leader, other engineers, or any stakeholder who will benefit from the work. Build compassion for the end user of the deliverable by clearly articulating their challenges and how the proposed work will improve their experience.
Effective issue descriptions follow a clear narrative arc:
This flow creates a compelling case while setting realistic expectations. The depth of detail may vary depending on your audience, but these core concepts remain the same.
These guidelines apply to all types of work items including:
While not every section applies to every issue type, following this structure ensures clarity and completeness.
The following sections should be considered when writing an issue description. Sections marked as (Required) should always be included. Other sections are recommended based on the type and complexity of the work.
For high-visibility work or when presenting to leadership, consider adding an executive summary at the very top of the description. This provides a concise overview that allows busy stakeholders to quickly understand the work without reading the full details.
An executive summary should include:
Important: Write the executive summary after completing all other sections. It is much easier to distill the key points once you have fully articulated the details. The summary should only synthesize information already present in the detailed sections below - do not include new content that appears nowhere else in the description. Readers should not feel obligated to read the executive summary; it exists purely for convenience.
Place the executive summary above all other sections, clearly labeled. The detailed sections that follow provide the supporting evidence and context.
Begin by outlining the problem or challenge that this work aims to address. Where applicable, this problem should align with broader project objectives or strategic goals.
The problem should be described from the viewpoint of the user or customer, not the viewpoint of those implementing the solution. Describe the current pain points or inefficiencies experienced by users and the impact of these challenges on their workflow or experience.
Feel free to mention specific tools, workflows, or experiences, but avoid prescribing a solution at this stage. Screenshots and visual artifacts are helpful to provide additional context.
For bugs: Focus on unexpected behaviors or errors. Include what was expected versus what actually happened.
For features: Focus on the current challenge a user faces and why the current state is insufficient.
Present a hypothesis or proposed solution to the identified problem. Explain how the proposed change is expected to alleviate the pain points and improve the user experience.
The proposed solution should directly address the problem identified in the problem statement. Consider this like a scientific experiment: what change are you going to make, and what impact do you expect it to have?
Important: Only include elements in the hypothesis that you established in the problem statement. Introducing new concepts or requirements here that were not set up earlier can feel like scope creep to readers. Every aspect of your proposed solution should tie back to a pain point or challenge you already described.
Remember, this is a hypothesis - you might be wrong. However, make your case strong enough that stakeholders are willing to place that bet during the prioritization process. Acknowledge uncertainty through the risks and assumptions sections while demonstrating confidence in your reasoning.
Articulate the value proposition for users. Highlight the benefits and advantages that users can expect from the implementation, emphasizing how it will address their needs.
Can the improvement be quantified in terms valuable to the business, such as:
Define specific criteria or conditions that must be met for the work to be considered successfully completed. This should be concrete and testable.
Examples:
Use a checklist format when possible to make verification straightforward.
For bugs or unexpected behaviors, describe events leading up to and shortly after the issue occurred. Include:
Technical artifacts like error messages and logs should be included in code blocks or as attachments.
List assumptions being made about:
This is also a good place to note areas of low confidence, such as:
For bug reports: Include assumptions about the user’s environment or state if the issue cannot be directly reproduced.
Acknowledge potential risks or challenges associated with the work and briefly outline mitigation strategies. This demonstrates a realistic understanding of potential obstacles while showing that challenges are being proactively addressed.
Examples:
Define how success will be measured after implementation. This goes beyond acceptance criteria to include behavioral and outcome metrics. These are your goal posts - the measurable indicators that tell you whether the hypothesis was correct and the work achieved its intended impact.
Important: Success metrics should tie directly back to the problems identified in the problem statement. Do not measure metrics that are unrelated to the work being done. If a metric like performance or uptime is important enough to track but is not directly attributable to solving the stated problem, that factor should instead be included as a constraint in the problem statement (e.g., “must maintain 99.9% uptime” or “must not degrade page load times”).
Examples:
Clear success metrics allow you to validate your hypothesis and learn from the outcome, whether the results meet, exceed, or fall short of expectations.
Specify what is explicitly included in this work to maintain focus on the primary objectives. This helps prevent scope creep and sets clear boundaries.
Think of scope as defining the playing field. You are giving stakeholders clear goal posts for what success looks like and what will be delivered. This protects both those doing the work (from expanding requirements) and stakeholders (from unclear expectations).
List what should specifically not be done as part of this work. This helps defend against scope creep, maintains focus, and sets expectations with stakeholders about what will not be delivered.
In combination with the Scope section, Out-of-Scope helps avoid poor assumptions and misunderstandings about what the work includes. It can also be used to avoid known risks by explicitly stating that risky areas should be avoided. For example, if a particular system is unstable or a specific approach has known issues, calling it out as out-of-scope sets clear boundaries and protects the work from being pulled into problematic territory.
Identify any known or potential dependencies that may impact implementation or timeline. Focus on dependencies that are risky enough to derail the plans technically or schedule-wise - things that are not fully trusted or reliable.
This section should also include work agreements with other teams: agreed-upon collaborations on collective efforts that need coordination.
This does not mean listing every third-party library, every access request, or every instance where you need a teammate to do their usual work. Instead, focus on dependencies that carry meaningful risk or require coordination:
When possible, incorporate visuals such as:
Visual aids simplify complex information and enhance understanding, especially for stakeholders unfamiliar with technical details.
Acronyms and domain-specific terms should always be defined at first use so that readers know the correct definition for this context. Assume your audience may not share your domain knowledge.
Example: “The CDN (Content Delivery Network) caching strategy needs updating.”
When applicable, reference:
This provides context and helps others understand how this work fits into the broader project.
As work progresses, update the issue description to reflect:
Important: If the description changes after work has started or commitments have been made, document the change in a comment on the ticket. The comment should include:
This creates a valuable historical record and helps future contributors understand the full context of decisions made, including when and why changes occurred.
Well-written issues accelerate development by:
The level of detail in each section should match your audience. A description for leadership might emphasize business value and success metrics, while one for engineers might include more technical depth. However, the core narrative arc remains the same: establish the problem, propose a solution that addresses that problem, acknowledge uncertainty, and set clear boundaries.
Invest time in writing clear, comprehensive issue descriptions. The clarity you provide upfront will save significant time and prevent misunderstandings during implementation. Most importantly, focus on building compassion for the end user - help readers understand not just what needs to be done, but why it matters to the people who will benefit from the work.