title: "Bug Reporting & Defect Management Guide" owner: "head-of-assurance" status: "draft" last_updated: "2026-03-27" tags: ["qa", "strategy", "qa-playbook" "defect-management", "bugs"] source_of_truth: "this-repo" related: ["../spline-studio-qa-strategy/sections/09-defect-management.md"]

Bug Reporting & Defect Management Guide

1. Overview

Purpose of the Guide

The Bug Reporting & Defect Management Guide defines the standardized approach for identifying, documenting, classifying, tracking, and resolving defects across the product.

The purpose of this guide is to ensure:

consistent and high-quality bug reporting
clear communication between QA, Development, and Product teams
efficient defect resolution and prioritization
transparency of product quality throughout the development lifecycle

This guide serves as a practical reference for day-to-day QA activities and defect handling processes.

Scope

This guide applies to all team members involved in the software development process, including:

QA Engineers — responsible for defect identification, validation, reporting, and verification
Developers — responsible for defect analysis, resolution, and technical investigation
Product Managers / Delivery Managers — responsible for prioritization and release decisions

The guide covers defect management activities across all testing levels and environments, including:

requirements and design analysis (during documentation and feature design review)
feature testing
system testing
regression testing
exploratory testing
pre-production and production validation
Relation to QA Strategy

This guide is part of the QA Playbook and complements the high-level principles defined in the QA Strategy.

While the QA Strategy defines what defect management is and why it is important, this guide describes how defect-related processes are executed in practice.

All defect management activities described in this guide should be aligned with the QA Strategy:

defect lifecycle and workflow
classification principles (severity, priority)
triage and resolution processes
quality visibility and reporting

Refer to the QA Strategy for high-level definitions and governance: QA Strategy → Defect Management section

2. What is a Defect

Definition of a Defect

A defect (bug) is any deviation between the expected system behavior and the actual observed behavior.

A defect may occur when:

the implemented functionality does not match the defined requirements
the system behaves inconsistently or unpredictably
an error, failure, or unexpected result occurs
the user experience is negatively impacted due to incorrect behavior
integrations with external systems do not work as expected

A defect can be identified at any stage of the product lifecycle, including requirements analysis, design review, development, and testing.

What is NOT a Defect

Not every issue or observation should be considered a defect.

Defect Classification Decision Flow

flowchart TB
    A["Issue Observed"] --> B{"Matches requirements / design?"}
    B -- Yes --> C["Not a Defect"]
    B -- No --> D{"Requirement defined?"}
    D -- No --> E["Clarify with Product / Stakeholders"]
    E --> F{"After clarification"} & n1["Untitled Node"]
    F -- Expected behavior confirmed --> C
    F -- Incorrect behavior --> G["Defect"]
    D -- Yes --> H{"Impacts functionality or UX?"}
    H -- Yes --> G
    H -- No --> I{"Improvement or suggestion?"}
    I -- Yes --> J["Log as Improvement"]
    I -- No --> K{"Unclear case"}
    K --> L["Discuss during Triage"]
    L --> M{"Team decision"}
    M -- Defect --> G
    M -- Not a Defect --> C
    G --> N["Report Bug"]

    style A fill:#FFE082,color:#000000
    style B color:#000000
    style C fill:#C8E6C9,color:#000000
    style D color:#000000
    style E fill:#FFF9C4,color:#000000
    style F color:#000000
    style G fill:#FFCDD2,color:#000000
    style H color:#000000
    style I color:#000000
    style J fill:#BBDEFB,color:#000000
    style K color:#000000
    style L fill:#B2DFDB,color:#000000
    style M color:#000000
    style N fill:#D50000,color:#FFFFFF

The following cases are not classified as defects:

expected system behavior that matches requirements and design
intentional product decisions approved by Product or stakeholders
known limitations or accepted constraints of the system
configuration or environment-specific issues outside the system scope
user errors caused by incorrect usage of the system

Such cases should not be reported as defects but may be documented as:

product decisions
known issues
support or usability feedback
Edge Cases and Clarifications

Some scenarios may require additional evaluation before being classified as defects.

UX Issues

UX-related issues may be considered defects if they:

significantly impact usability or user flow
cause confusion or incorrect user actions
contradict defined UX guidelines or design specifications

Minor UX improvements or subjective preferences should be treated as improvement suggestions, not defects.

Missing or Unclear Requirements

If expected behavior is not clearly defined:

QA should first clarify the requirement with Product or stakeholders
if the implemented behavior contradicts business expectations, it may be treated as a defect
if behavior is undefined, it should be documented and clarified before classification
Improvements vs Defects

Enhancements or improvement ideas should not be reported as defects unless:

the current behavior violates requirements
the issue causes functional or usability problems

Otherwise, they should be logged as:

improvement tasks
product backlog items

Final Classification Rule

If there is uncertainty whether an issue is a defect:

the issue should be discussed during defect triage
the final decision is made collaboratively by QA, Development, and Product

3. Where to Create Defects in Jira

This section defines where defects should be created in Jira depending on their context and relation to current development activities.

Correct defect placement ensures:

proper ownership and visibility
alignment with sprint scope
accurate tracking and reporting

flowchart TB
    A["Defect Identified"] --> B{"Related to current feature in sprint?"}
    B -- Yes --> C["Create in Feature Epic"]
    C --> D["Epic: Feature"]
    D --> D1["User Story: Bug Fix - Feature"]
    B -- No --> E{"Related to existing functionality?"}
    E -- Yes --> F["Create in Current Sprint Bug Fix User Story"]
    F --> G["Epic: QA Release / Sprint"]
    G --> G1["User Story: Bug Fix - Release / Sprint"]
    E -- No --> H{"Low priority or deferred?"}
    H -- Yes --> I["Create in Bug Log"]
    I --> J["Epic: QA Artifacts"]
    J --> J1["User Story: Bug Log"]
    H -- No --> K["Discuss during Triage"]
    K --> L["Place based on decision"]

    style A fill:#FFE082,color:#000000
    style C fill:#C8E6C9,color:#000000
    style D color:#000000
    style D1 color:#000000
    style F fill:#BBDEFB,color:#000000
    style G1 color:#000000
    style I fill:#CFD8DC,color:#000000
    style K fill:#FFF59D,color:#000000

If a defect is identified during testing of a new feature within the current sprint, and there is an active User Story:

The defect must be created within the same Epic as the feature.

Structure:

Epic: Feature
User Story: Bug Fix – Feature

This ensures that:

all feature-related defects are grouped together
the development team can address them within the feature scope
visibility is maintained within the feature delivery process

If a defect is related to existing functionality and is not connected to any active User Story in the current sprint:

The defect must be created in the current sprint Bug Fix User Story.

Structure:

Epic: QA Release / Sprint
User Story: Bug Fix – Release / Sprint

This ensures that:

regression and legacy defects are tracked separately from new features
defects are still addressed within the current sprint
reporting reflects actual QA workload

3.3 Low Priority / Deferred Defects (Bug Log)

If a defect is:

low priority
known but not planned for immediate fix
related to functionality that will be improved later

The defect must be created in the Bug Log.

Structure:

Epic: QA Artifacts
User Story: Bug Log

This ensures that:

such issues are not lost
they do not impact current sprint scope
they remain visible for future prioritization

3.4 General Rule

Each defect must be placed in the appropriate Epic and User Story based on:

relation to current sprint scope
impact on delivery
urgency of resolution

Incorrect placement may lead to:

loss of visibility
incorrect prioritization
misleading reporting and metrics

4. Defect Classification

Defect Classification Flow

flowchart TD
    A[Defect Reported] --> B[Assess Severity]
    B --> C[Assign Priority]
    C --> D[Select Component]
    D --> E[Select Type]
    E --> F[Defect Classification Completed]

    B --> B1[Critical / Major / Middle / Minor / Trivial]
    C --> C1[Highest / High / Medium / Low / Lowest]
    D --> D1[Application Area / Backend / System Domain]
    E --> E1[Functional / UI / Usability / Integration / Performance / Security]

    style A fill:#FFE082,color:#000000
    style B fill:#FFCDD2,color:#000000
    style C fill:#BBDEFB,color:#000000
    style D fill:#C8E6C9,color:#000000
    style E fill:#FFF9C4,color:#000000
    style F fill:#B2DFDB,color:#000000

4.1 Severity Levels

Severity defines the impact of a defect on system functionality, stability, or user experience.

It reflects how serious the issue is from a technical and user perspective.

Severity Scale

🟥 Critical
🟧 Major
🟨 Middle
🟩 Minor
🟦 Trivial

Severity Definitions

🟥 Critical

system is not usable or key functionality is completely broken
causes system crash, data loss, or security issues
no workaround is available
blocks testing or release

🟧 Major

core functionality is significantly impacted
feature works incorrectly but system is still partially usable
workaround may exist but is not acceptable for normal use

🟨 Middle

non-critical functionality is affected
issue does not block main user flows
workaround is available

🟩 Minor

small functional or UI issue
does not significantly impact user experience
system behaves mostly as expected

🟦 Trivial

cosmetic issues (UI misalignment, text, spacing, typos)
no impact on functionality
does not affect user workflows

General Rule

Severity is determined by QA based on:

impact on functionality
impact on user experience
system stability

If there is uncertainty, severity should be confirmed during defect triage.

Responsibility Note

Severity is primarily determined by the QA engineer who identifies the defect.

If there is uncertainty, the QA engineer should consult with relevant team members (e.g., developers, product managers, or technical leads) to better understand the real impact of the issue on the system.

The final severity should reflect the actual impact on functionality, system stability, and user experience.

4.2 Priority Levels

Priority defines the urgency with which a defect should be resolved.

It reflects business impact, delivery timelines, and release importance rather than technical severity.

Priority Scale

⏫ Highest
🔼 High
🟰 Medium
🔽 Low
⏬Lowest

Priority Definitions

⏫ Highest

must be fixed immediately
blocks release or critical functionality
requires urgent attention

🔼 High

should be fixed within the current sprint
significantly impacts feature delivery or user experience

🟰 Medium

should preferably be fixed within the current sprint
does not block release but should not be delayed
may be postponed only if higher priority work exists

🔽 Low

minor impact on functionality or UX
can be scheduled when capacity allows

⏬Lowest

minimal impact
nice-to-have fixes or improvements
can be deferred without affecting delivery

General Rule

Priority is typically defined in collaboration with Product and Development based on:

business impact
release timelines
user impact

Severity and Priority are independent attributes:

Severity = how serious the issue is
Priority = how urgent it is to fix

Example:

Critical severity + Low priority (rare edge case)
Minor severity + High priority (visible issue for all users)

4.3 Other Attributes

In addition to severity and priority, defects must be classified using additional attributes to improve visibility, filtering, and analysis.

Component

The component defines which high-level area of the system is affected by the defect.

Components should represent major parts of the application, such as:

different applications or platforms (e.g., web, mobile, admin interfaces)
backend services or APIs
major system domains

The exact list of components may vary depending on the project and should be defined based on its architecture.

Component Selection Rules

Components should represent high-level areas of the system, not detailed functionality
If a defect is related to user-facing behavior, select the corresponding application-level component
If a defect is related to server-side logic or integrations, select the backend-related component
Components must reflect the primary area of impact

Type

The type defines the nature of the defect.

Common defect types include:

Functional — incorrect or missing functionality
UI — visual issues (layout, alignment, styles)
Usability — issues affecting user experience or flow
Integration — problems with external services or system components
Performance — slow response, timeouts, or system inefficiency
Security — vulnerabilities or access issues

Type Selection Rules

Select the primary type that best represents the defect
If a defect affects multiple aspects, choose the most critical one
Additional context can be provided in the defect description

Additional Classification

More detailed functional areas (e.g., profile, wallet, transfer, login) should be specified using labels or described in the defect details, rather than creating additional components.

General Rule

Each defect must have:

one clearly defined component
one primary defect type

These attributes must be selected during bug creation and should not be left empty.

Component structure and classification should remain consistent across the project.

5. Bug Reporting

5.1 Bug Report Structure

A well-structured bug report ensures clear communication between QA, Development, and Product teams and enables faster issue resolution.

Each bug report must include the following sections:

Summary

The summary should briefly describe the issue.

must be concise and clear
should reflect the core problem
should not be overly long

Prefixes may be used to improve clarity and context (e.g., [UI], [API], [Mobile], [Regression]).

Environment

Specify where the defect was identified.

Examples:

DEV
Pre-Production
Release Candidate
Production

Additional details may include:

browser and version
device (if applicable)
application version (if available)

Description

The description must contain all necessary information to reproduce and understand the issue.

Include:

link to the page or feature where the issue occurs
test credentials (login and password), if required

Actual Result

Describe how the system behaves currently.

must clearly reflect the issue
should be written in a clear and precise manner
recommended to highlight key parts (e.g., using formatting or emphasis)

Steps to Reproduce

Provide a step-by-step sequence to reproduce the issue:

Step one
Step two
Step three

Steps must be:

clear
reproducible
logically ordered

Expected Result

Describe how the system should behave.

must be based on requirements, design, or expected system logic
should clearly contrast with the actual result

Attachments

Attachments are mandatory for most defects.

video recording is preferred
screenshots are acceptable if they clearly demonstrate the issue
screenshots must include sufficient context for understanding the problem

If the issue is related to UI, screenshots should clearly indicate what needs to be fixed.

API / Technical Details (if applicable)

If the defect is related to API or backend behavior:

include request/response details
include endpoint information
include relevant logs if available

Additional Fields in Jira

When creating a bug, ensure all required fields are properly filled:

Severity
Priority
Component
Type
Environment (if available as a field)

Assignment

The bug must be assigned to the responsible person:

assign to the developer who worked on the feature, if known
if the responsible person is unavailable, assign based on area:
frontend issues → frontend developer
backend issues → backend developer

General Rule

A bug report must be:

clear and understandable without additional clarification
reproducible
complete

Poorly described bugs may delay resolution and require additional clarification.

flowchart TD

A[Bug Found] --> B[QA: Bug Validation]

B -->|Not a bug| Z[Stop]
B -->|Valid bug| C[QA: Duplicate Check]

C -->|Duplicate found| Z
C -->|No duplicate| D[QA: Define Bug Location]

D --> E[QA: Create Issue - Bug]

E --> F[QA: Fill Summary]
F --> G[QA: Fill Environment]

G --> H[QA: Write Description]

H --> H1[Actual Result]
H --> H2[Link]
H --> H3[Credentials]
H --> H4[Steps to Reproduce]
H --> H5[Expected Result]
H --> H6[Attachments]

H1 --> I[QA: Fill Sidebar Fields]
H2 --> I
H3 --> I
H4 --> I
H5 --> I
H6 --> I

I --> I1[Component]
I --> I2[Environment Found]
I --> I3[Severity]
I --> I4[Priority]
I --> I5[Assignee]

I1 --> J{QA: Final Check}
I2 --> J
I3 --> J
I4 --> J
I5 --> J

J -->|Missing info| H
J -->|Complete| K[Bug Created]

K --> L[PM: Review Priority - optional]
L --> M[Dev: Start Investigation]

style A fill:#4CAF50,color:#ffffff,stroke:#2E7D32,stroke-width:2px
style Z fill:#9E9E9E,color:#ffffff,stroke:#616161,stroke-width:2px
style B fill:#2196F3,color:#ffffff,stroke:#1565C0,stroke-width:2px
style C fill:#2196F3,color:#ffffff,stroke:#1565C0,stroke-width:2px
style D fill:#2196F3,color:#ffffff,stroke:#1565C0,stroke-width:2px
style E fill:#673AB7,color:#ffffff,stroke:#4527A0,stroke-width:2px
style F fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style G fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style H fill:#2196F3,color:#ffffff,stroke:#1565C0,stroke-width:2px
style H1 fill:#F44336,color:#ffffff,stroke:#B71C1C,stroke-width:2px
style H2 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style H3 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style H4 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style H5 fill:#4CAF50,color:#ffffff,stroke:#1B5E20,stroke-width:2px
style H6 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style I fill:#2196F3,color:#ffffff,stroke:#1565C0,stroke-width:2px
style I1 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style I2 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style I3 fill:#FF9800,color:#000000,stroke:#E65100,stroke-width:2px
style I4 fill:#FFC107,color:#000000,stroke:#FF8F00,stroke-width:2px
style I5 fill:#00BCD4,color:#ffffff,stroke:#00838F,stroke-width:2px
style J fill:#607D8B,color:#ffffff,stroke:#263238,stroke-width:2px
style K fill:#2E7D32,color:#ffffff,stroke:#1B5E20,stroke-width:2px
style L fill:#9C27B0,color:#ffffff,stroke:#4A148C,stroke-width:2px
style M fill:#FF5722,color:#ffffff,stroke:#BF360C,stroke-width:2px

Bug Reporting & Defect Management Guide

1. Overview

2. What is a Defect

Definition of a Defect

What is NOT a Defect

3. Where to Create Defects in Jira

3.1 Defects Related to Current Feature Development

3.2 Defects Related to Existing / Previously Delivered Functionality

3.3 Low Priority / Deferred Defects (Bug Log)

3.4 General Rule

4. Defect Classification

Defect Classification Flow

4.1 Severity Levels

4.2 Priority Levels

4.3 Other Attributes

5. Bug Reporting

5.1 Bug Report Structure

Summary

Environment

Description

Actual Result

Steps to Reproduce

Expected Result

Attachments

API / Technical Details (if applicable)

Additional Fields in Jira

Assignment

General Rule