Prerequisites

Before you can create a defect, two things must already be in place:

  1. A project must exist. Defects live inside projects — they can’t float independently. The project defines which software modules, epics, phases, and custom fields are available when you create the defect. If your project is still in Draft status, you may be limited to viewing only.
  2. You need the Create privilege on the Defects module. Your role must include at minimum “Create” access under Defects. If you can see the Add Defect button, you have it. If the button is greyed out or missing, ask your project admin to update your role privileges.

Optionally — but recommended — having requirements and test cases already populated in the project gives you something to link the defect to. A defect that’s linked to a failing test case and the requirement it violates carries far more weight in a phase gate review than one floating in isolation.

Where Defects Fit

Defects exist inside a project under TESTING → Defects. They are distinct from Requirements (which describe what to build), Test Cases (which describe how to verify), and Action Items (which are lightweight to-dos). A defect is the formal record that something is wrong — it carries a status workflow, priority, severity, assignment, and optional links back to the test case and requirement that surfaced it.

Defects can also be created directly from the Test Execution page while a tester is running a test cycle. When a test step fails, the tester can click Create Defect right there — the defect automatically links to the test case, test cycle, and requirement being tested. That’s the fastest path and the one that preserves the most traceability.

The Defect Lifecycle

Every defect moves through a 14-status workflow. Understanding this before you create one prevents you from setting the wrong starting status:

Stage Status What It Means
1 New Just logged — not yet triaged or assigned. This is the default for imported defects and AI-generated defects.
2 Open Acknowledged and ready for assignment. This is the default when you create a defect manually.
3 Assigned Assigned to a specific developer or QA engineer. The system won’t let you move a defect to Assigned without selecting an assignee.
4 In Progress Someone is actively working on the fix.
5 QA In Progress The fix is being tested internally by the QA team.
6 SR In Progress A service request related to this defect is being worked. Specific to managed-services workflows.
7 Internal Review The fix is ready for peer review or team lead sign-off before going to the client.
8 Client Review The fix has been delivered to the client for their review and acceptance.
9 Needs Clarification Blocked — someone needs to provide more information before work can continue. Use this instead of leaving a defect in limbo.
10 Fixed The developer has resolved the issue. Awaiting verification.
11 Verified QA has confirmed the fix works. Ready for closure.
12 On Hold Intentionally paused — e.g. waiting on a third-party fix, a client decision, or a future phase. Not the same as “ignored.”
13 Rejected Determined to be not a defect — expected behavior, duplicate, or out of scope. Always add a resolution note explaining why.
14 Closed Final state. Depending on project configuration, a resolution summary may be required before closing.

You can jump between non-sequential statuses. A defect doesn’t have to go 1 → 2 → 3. You can move directly from Open to In Progress, or from Open to Needs Clarification. The only enforced rule is that you can’t move to Assigned without an assignee, and some projects require a resolution before closing.

Priority vs. Severity — Don’t Confuse Them

Both use the same scale (Low, Medium, High, Critical), but they measure different things. Getting this wrong causes miscommunication with your team and your client:

  • Priority answers: “How urgently does this need to be fixed?” It’s a business decision. A cosmetic typo on the login page might be Low severity but High priority because every user sees it. A data corruption bug in a report only three people use might be Critical severity but Medium priority.
  • Severity answers: “How badly is the system broken?” It’s a technical assessment. Data loss or system crash = Critical. Workflow works but a field label is wrong = Low. Severity should reflect the actual impact on system function, independent of who’s asking or when the demo is.

When to escalate: High Priority + High Severity = stop what you’re doing, this blocks go-live. High Severity + Low Priority = log it, flag it, but don’t derail the current sprint. Low Severity + High Priority = a stakeholder request — fix it quickly but don’t sound the fire alarm.

Creating a Defect — Step by Step

Step 1: Open the Create Panel

From the Defects tab, click Add Defect. A slide-in panel opens from the right side of the screen. This is the Quick Create panel — it has the most commonly needed fields. There’s also a full-page editor accessible via the expand button in the panel header if you need rich-text descriptions, attachments, or custom fields.

You’ll also see a toggle at the top of the panel: Manual (the form) and Create With AI. The AI tab lets you describe the defect in plain English — the system fills in title, description, priority, and severity based on your description. This is useful when you’re logging defects rapidly during a testing session and don’t want to fill every field manually.

Step 2: Title (Required)

Enter a clear, specific title. This is what shows up in the defects list, in reports, and in any linked dashboards. A bad title — “Bug” or “Issue with screen” — tells nobody anything. A good title names the feature, the symptom, and the condition:

  • Bad: “Login broken”
  • Good: “Login page returns 500 error when user enters valid credentials with SSO disabled”
  • Bad: “Report wrong”
  • Good: “Monthly Benefits Summary report shows zero values when payroll data has mid-month effective dates”

The title is searchable. Make it findable.

Step 3: Description (Optional, but Don’t Skip It)

The description field in the Quick Create panel is a plain text area. Use it to capture:

  1. Steps to reproduce: What did the tester do? Be specific — “Clicked Save on the Benefits Enrollment form after selecting Plan Type = Medical with coverage level = Family” is actionable. “Tried to save” is not.
  2. Expected result: What should have happened?
  3. Actual result: What actually happened? Include error messages verbatim.
  4. Environment: Which browser, which tenant, which user role? This matters when a defect only reproduces under specific conditions.

If you need formatting, images, or code blocks, use the full-page editor (click the expand icon in the panel header). The full editor supports rich text via a Quill-based editor with image paste, code formatting, and file attachments.

Step 4: Priority

Defaults to Low. Change it to Medium, High, or Critical based on the urgency assessment described above. This field drives sorting in the defects list and is visible in every dashboard widget. A defect marked Critical will appear at the top of any filtered view — use it sparingly so it actually means something.

Step 5: Severity

Defaults to Low. Change it based on the technical impact. This field is used in analytics and trend reports — if every defect is Critical severity, your severity data becomes noise.

Step 6: Status

Defaults to Open for manually created defects. This is correct for most cases — the defect is acknowledged and ready for triage. If you’re importing defects from a spreadsheet, they may come in as New. Don’t set newly created defects to “In Progress” or “Assigned” unless you actually have someone working on them immediately — it pollutes the metrics and makes it harder to see what’s genuinely active.

Step 7: Assignee

Optional at creation time. You can leave it unassigned for the project lead to triage, or assign it immediately to a developer or QA engineer. Only users who are active members of this project appear in the dropdown. If the person you want isn’t listed, they need to be added to the project first via the Users page.

Step 8: Link a Test Case

If this defect was found during testing, link it to the test case that caught it. This creates a traceability chain: Requirement → Test Case → Defect. Click the Test Case dropdown and search by ID or title. The dropdown shows the test case ID, title, software module, and script status so you can confirm you’re linking to the right one.

Linked defects appear on the test case’s detail view and in traceability reports. During a phase gate review, being able to say “CRP2 has 14 open defects, all linked to their originating test cases and requirements” is the difference between an informed go/no-go decision and a guess.

Step 9: Custom Fields (Full Editor Only)

If your project has custom fields configured (e.g. “Root Cause Category”, “Client Impact Level”, “Found In Phase”), these appear in the full-page editor, not the Quick Create panel. Click the expand button to access them. Custom fields are project-specific — what you see in one project may not exist in another. Required custom fields are enforced on save.

Step 10: Save and Next Steps

Click Save. The panel closes and your defect appears in the defects list with a unique DEF ID (e.g. DEF0000068). From here you can:

  • Click the DEF ID to open the full detail page with activity stream, attachments, and the AI analysis tab
  • Inline edit the status, priority, severity, or assignee directly from the table without opening the detail view
  • Add comments — the detail page has a threaded comment system with @mentions
  • Attach files — screenshots, logs, and test data can be attached via the full-page editor
  • Use the AI tab — the detail page has an AI defect analysis tab that can suggest root causes, recommend related defects, and generate resolution notes

Resolving and Closing a Defect

When work is complete, move the defect to Fixed (if you’re the developer) or Verified (if you’re QA confirming the fix). From either state, you can move to Closed. Depending on your project settings, closing may require a resolution summary — a text field that captures what was done and why. This resolution is permanent and visible in the activity stream. If your project requires resolutions before closing and you don’t provide one, the close action will be blocked.

Don’t delete defects. Closed defects are an audit trail. They show what was found, when, by whom, and how it was resolved. That history is invaluable during retrospectives, phase reviews, and client conversations. If a defect was created by mistake, reject it with a note — don’t delete it.