Skip to main content

Working with Defects

Defects represent bugs, issues, or problems discovered in your product. Like stories, defects are backlog items that can be estimated, broken down into tasks and tests, and tracked through sprints or iterations. Agility includes tools to create, prioritize, track, and report on defects throughout the development lifecycle.

Who works with defects: Team members create defects when discovering bugs, investigate root causes, implement fixes, and verify resolutions. Scrum masters prioritize defects alongside stories and facilitate defect triage sessions. Product owners decide which defects to fix versus defer based on business impact and customer needs. QA engineers verify fixes and create regression tests.

Permission requirement: Viewing defects requires project member access. Creating and editing defects requires Team Member role or higher. Closing defects typically requires Team Member role. Deleting defects requires elevated permissions (typically Project Admin role). Converting between defects and stories requires edit permissions on both asset types. Specific permissions depend on your organization's role configuration.

What Are Defects?​

Defects are specialized backlog items with attributes tailored for tracking bugs and issues. They share common fields with stories (Title, Description, Estimate, Status, Owner, Priority) but include defect-specific attributes:

  • Defect Type: Categorize defects (e.g., Code Issue, Documentation, Configuration, Performance)
  • Resolution: Track how the defect was resolved (Fixed, Duplicate, Won't Fix, Cannot Reproduce)
  • Verified By: Record who verified the fix works as expected
  • Found In: Link to the release, build, or version where the defect was discovered
  • Fixed In: Link to the release, build, or version where the defect was fixed

Like stories, defects can have acceptance tests, tasks, dependencies, attachments, and links to other work items.

Defect Components​

Defects support the same breakdown and verification mechanisms as stories:

Acceptance Tests​

Define verification criteria to ensure the defect is fixed and prevent regression:

  • Manual tests: Step-by-step instructions for QA or team members to verify the fix
  • Automated tests: Link to automated test scripts or CI/CD pipeline runs
  • Pass/fail tracking: Record test results and who verified the fix

Tasks​

Break down complex defects into actionable work items:

  • Investigation tasks: Reproduce the issue, identify root cause
  • Fix tasks: Implement the code change or configuration update
  • Verification tasks: Test the fix in different environments or scenarios
  • Documentation tasks: Update user docs, release notes, or knowledge base

Filter and Find Defects​

Quickly locate relevant defects using Agility's filtering capabilities:

Filter by Defect Type​

Narrow your view to specific categories of issues:

  1. Click the hamburger icon Hamburger icon > Product > Backlog.
  2. Click the Filter icon (funnel) above the grid.
  3. Select Defect Type from the filter menu.
  4. Choose one or more defect types (e.g., Code Issue, Performance, Documentation).
  5. Click Apply to filter the grid. Only defects matching the selected types are displayed.

Filter by Resolution​

Track how defects are being resolved across your product:

  1. Click the hamburger icon Hamburger icon > Product > Backlog.
  2. Click the Filter icon (funnel) above the grid.
  3. Select Resolution from the filter menu.
  4. Choose one or more resolutions (e.g., Fixed, Duplicate, Won't Fix).
  5. Click Apply to see defects with the selected resolutions.

Use case: Identify patterns like high duplicate rates (communication gaps) or frequent "Won't Fix" decisions (scope creep or misaligned priorities).

Filter by Verified By​

Find defects verified by specific team members:

  1. Click the hamburger icon Hamburger icon > Product > Backlog.
  2. Click the Filter icon (funnel) above the grid.
  3. Select Verified By from the filter menu.
  4. Choose one or more team members who verified defect fixes.
  5. Click Apply to filter the view.

Use case: Track verification workload distribution or audit who confirmed critical fixes.

Core Defect Management Operations​

Agility provides comprehensive tools to manage defects throughout their lifecycle. Below are the primary operations and where to find detailed guidance.

Create, View, Edit, and Delete Defects​

Manage defects through their complete lifecycle with multiple creation methods, detailed viewing, flexible editing, and recovery options.

What you can do:

  • Create defects using inline grids, detail pages, sidebar, spreadsheet import, or templates
  • View comprehensive defect details, history, and relationships on the Defect Details page
  • Edit defects inline in grids or on the details page with full field access
  • Delete defects that are duplicates or created in error
  • Recover deleted defects using Recent Changes, Advanced Search, or API

Learn more: Create, View, Edit, and Delete Defects

Convert Story to Defect​

Transform backlog items (stories) into defects when work reveals bugs or issues rather than new features, or convert defects back to stories when feature development is required.

What you can do:

  • Convert stories to defects when development uncovers bugs
  • Convert defects to stories when fixes require new features
  • Preserve tasks, tests, relationships, and history during conversion
  • Troubleshoot Type field errors during conversion

Learn more: Convert Story to Defect

Split Defects​

Split partially completed defects at sprint end to retain credit for completed work while moving incomplete work to a new defect in the next sprint.

What you can do:

  • Split defects from grids or the Team Scheduling page
  • Automatically divide tasks and tests based on completion status
  • Allocate estimates accurately across split defects
  • Track split defects for retrospective analysis

Learn more: Split Defects

Track and Report on Defects​

Choose between two tracking approaches (planned sprints or work queue) and leverage built-in reports to analyze defect trends and team performance.

What you can do:

  • Track defects in sprints with velocity and burndown charts
  • Manage defects in a continuous work queue for high-volume scenarios
  • Generate reports by defect type, resolution, priority, and age
  • Monitor team and member defect workload

Learn more: Defect Tracking and Reporting

Defect Management Best Practices​

  1. Use descriptive titles: Include the feature or component affected (e.g., "Login button fails on Safari" instead of "Button broken").
  2. Document reproduction steps: In the Description field, provide clear steps to reproduce, expected behavior, and actual behavior.
  3. Categorize consistently: Use Defect Type to enable meaningful reporting and trend analysis.
  4. Set priorities based on impact: Align priority with business impact, not just technical severity. Consider user impact and urgency.
  5. Link to builds and releases: Use Found In and Fixed In fields to track defect lifecycle across releases.
  6. Close defects when resolved: Mark defects as Fixed or Closed to remove them from active tracking. Avoid deleting defects unless they're duplicates or errors.
  7. Choose a tracking method: Decide whether to plan defects in sprints (for large defects) or use a work queue (for high volumes). Be consistent.
  8. Break down complex defects: Use tasks to distribute investigation, fix, and verification work across team members.
  9. Verify fixes thoroughly: Add acceptance tests to ensure the defect is fixed and prevent regression.
  10. Review defect trends regularly: Use reports to identify patterns (common defect types, resolution trends, aging issues) and improve quality processes.

Troubleshooting​

Why don't I see defect-specific fields like Defect Type or Resolution?​

Defect-specific fields may be hidden in your project's workspace configuration. Project Admins control field visibility through Admin > Project Workspace Assets > Defect. Some fields are optional and may not be enabled for your project. If you need access to defect-specific fields, contact your Project Admin to enable them in the workspace configuration. Also verify you're viewing a defect (not a story) - these fields only appear on defect assets.

Why can't I filter defects by Resolution if the field exists?​

Resolution values only populate after a defect is closed or resolved. If all your defects are still open, the Resolution filter shows no values to select. Additionally, Resolution may not be a required field, so some closed defects might not have Resolution values assigned. To make Resolution filtering more useful, establish a team practice of assigning Resolution when closing defects (Fixed, Duplicate, Won't Fix, Cannot Reproduce).

Why does my defect disappear from the backlog after I close it?​

Closed defects are hidden from default backlog views to reduce clutter and focus on active work. This is expected behavior. To view closed defects, apply a Status filter that includes closed statuses, or navigate to Product > Closed Items. Closed defects remain in the system and contribute to historical reports and metrics - they're not deleted, just filtered from active views.

Why do defects not appear in my Sprint Burndown report?​

Defects only appear in Sprint Burndown if they're scheduled in a sprint with estimates. If you're using the work queue approach (defects assigned directly to team members without sprint scheduling), they won't appear in sprint reports because they're not part of sprint capacity. To include defects in sprint tracking, schedule them into sprints like stories and assign estimate values. Alternatively, use the Defect Age report and custom backlog views to track work queue defects.