> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/issue-relationships.md).

# Issue Relationships

Understand the two different types of issue relationships: related issues and duplicates.

Issues rarely exist in isolation. Related errors often indicate shared root causes, code dependencies, or cascading failures. Pharos provides two mechanisms to help you identify and manage connected Issues: an **automatic relationship** driven by fingerprint matching, and a **manual relationship** you create yourself — both stored in the same `pharos__Related_Issue__c` lookup. Duplicate marking reuses that same lookup, with `Status__c` set to `Duplicate`.

Every log carries three **fingerprint** tiers of decreasing precision — Hash 1, Hash 2, and Hash 3 — computed during log processing. The most precise tier (Hash 1) groups identical errors into a single Issue; the looser tiers (Hash 2, Hash 3) are what drive the automatic relationships below. For how those fingerprints are built, see [Log Fingerprinting](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-processing/log-fingerprinting.md).

## Why Issue Relationships Matter

Understanding relationships between Issues helps you:

* **Avoid duplicate work** → Multiple Issues may represent the same problem
* **Identify systemic problems** → Related errors suggest architectural issues
* **Prioritize effectively** → Fixing the linked Issue may resolve others
* **Track refactoring impact** → Code changes produce a new hash for the same underlying error

## Types of Relationships

Pharos supports three ways an Issue's `pharos__Related_Issue__c` lookup gets set: automatically based on hash-tier matches, manually through a list-view action, and as part of marking an Issue a duplicate.

### 1. Automatic Relationships (Fingerprint-Based)

Pharos automatically points a new (or older, unresolved) Issue at another Issue with a similar — but not identical — fingerprint.

**How it works:**

* Every Log carries a primary fingerprint, stored as **Hash 1** (`pharos__Hash_1__c`). This is the exact-match key used to decide whether a log belongs to an existing Issue or should start a new one.
* Each Log also carries two progressively looser fingerprints: **Hash 2** (`pharos__Hash_2__c`) and **Hash 3** (`pharos__Hash_3__c`).
* When a new Issue is created, Pharos checks other open Issues (and, in some cases, older Completed or Duplicate Issues that don't yet have a related Issue) for a Log sharing the same Hash 2 value, or — for Flow and Process Builder logs only — the same Hash 3 value.
* If a match is found, the Issue's `pharos__Related_Issue__c` lookup is set to point at the matching Issue. A Hash 2 match takes priority over a Hash 3 match.

**What you'll see:**

* The matched Issue appears in the **Related Issues** related list on the Issue page.
* There is no color-coded badge, label, or confidence score — the list simply reflects whichever Issue `pharos__Related_Issue__c` currently points to, plus any other Issues pointing at that same target.

**Common scenarios:**

| Scenario                | Why They're Related                       | Hash Tier                          |
| ----------------------- | ----------------------------------------- | ---------------------------------- |
| **Code refactoring**    | Stack trace changed but error is the same | Hash 2                             |
| **Flow version bump**   | Flow logic similar, version different     | Hash 2                             |
| **Similar error types** | Same exception type, different classes    | Hash 3 (Flow/Process Builder only) |
| **Parallel failures**   | Related functionality failing together    | Hash 3 (Flow/Process Builder only) |

**Example:**

```
Issue A: DML Exception in OpportunityTriggerHandler.afterInsert (v1.0) — created first
Issue B: DML Exception in OpportunityTriggerHandler.afterUpdate (v1.0) — shares Hash 3 with A
Issue C: DML Exception in OpportunityTriggerHandler.afterInsert (v2.0) — shares Hash 2 with A

Result:
- B.Related_Issue__c → A  (Hash 3 match: same trigger, different method)
- C.Related_Issue__c → A  (Hash 2 match: same method, code refactored)
```

`pharos__Related_Issue__c` is a single lookup, not a web of scored connections — each Issue points at, at most, one other Issue.

### 2. Manual Relationships (User-Linked)

You can manually link Issues you know are related even when their hashes don't match.

**How to link:**

1. From an Issue list view, select two or more Issues you want to relate
2. Run the **Link Issue** action
3. Pharos treats the oldest selected Issue as the anchor and sets `pharos__Related_Issue__c` on the other selected Issues to point at it — `Status__c` is left unchanged
4. The link now appears in the **Related Issues** list on every linked Issue

**When to use:**

* You know two Issues stem from the same root cause but their hashes never matched
* Errors appear unrelated but share business logic
* Cross-category relationships (an Apex error causes a Flow error)
* Documenting upstream/downstream dependencies

**Removing a manual link:** open the Issue, use **Unlink** on the related Issue's row in the Related Issues list — this clears `pharos__Related_Issue__c`.

### 3. Duplicate Relationships

When multiple Issues represent the **exact same problem**, mark them as duplicates.

**How duplication works:**

1. From an Issue list view, select two or more Issues to mark as duplicates
2. Run the **Mark Issue Duplicate** action
3. Pharos treats the oldest selected Issue as the parent; the other selected Issues get `Status__c = Duplicate` and `pharos__Related_Issue__c` set to point at the parent
4. Work continues on the parent; duplicates are excluded from active triage views

Duplicate marking uses the same `pharos__Related_Issue__c` lookup as an automatic or manual relationship — what makes it a duplicate rather than just "related" is the `Duplicate` status.

**Common reasons Issues end up as separate records instead of merging automatically:**

| Reason                       | Example                                      | Why Not Merged Automatically?                                            |
| ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
| **Hash 1 changed mid-issue** | Code deployed while the Issue was still open | A changed Hash 1 starts a new Issue, even if the root cause is identical |
| **Edge case variations**     | Same error, slightly different stack trace   | Hash 1 differs even though Hash 2/3 may not catch the overlap            |
| **Manual log creation**      | Logs created via API with slight variations  | The hash calculation treats them as distinct                             |

## Viewing Related Issues

### On the Issue Record

Navigate to the **Related Issues** related list.

**What you'll see:**

* The Issue this one points to via `pharos__Related_Issue__c` (whether that link was set automatically by a hash-tier match or manually), and any other Issues pointing at that same target
* Issue Name, Category, Status, and Summary by default (the component's column set is configurable)
* A **View** action to open each related Issue, and an **Unlink** action on rows that have a related Issue to remove

Pharos does not score or color-code these relationships. The list is a direct reflection of the `pharos__Related_Issue__c` lookup values — there's no separate "match strength" concept to sort or filter by.

## Using Relationships for Investigation

Relationships guide several common investigation workflows, from tracing a root cause to spotting a systemic problem across many Issues.

### Workflow 1: Tracing Root Cause

Follow a related Issue to find the underlying cause behind a symptom:

```
1. Start with Issue A (Flow error)
2. View the Related Issues list
3. See Issue B (Apex error) linked via a hash-tier match
4. Open Issue B's debug view
5. Discover: Flow calls Apex, Apex fails, Flow error is a symptom
6. Mark Issue A as a duplicate of Issue B
7. Fix Issue B (Apex); both Issues stop recurring
```

### Workflow 2: Refactoring Impact

Spot when a refactor reintroduces a bug you already fixed:

```
1. Deploy a code refactor on Friday
2. Monday: New Issue C appears (new Hash 1 — code changed)
3. View the Related Issues list on Issue C
4. See Issue D (Hash 2 match, created two months ago, now Completed)
5. Realize: the refactor reintroduced an old bug
6. Review Issue D's resolution notes
7. Re-apply the fix from Issue D to the new code structure
```

### Workflow 3: Systemic Problem Detection

Recognize when several Issues share one systemic cause:

```
1. Triage new Issues
2. Notice several Issues all pointing at each other via Hash 3 matches
3. All involve the Account object
4. Investigate: a recent validation rule change affects multiple processes
5. Fix the validation rule
6. All of the Issues stop recurring
7. Mark the newer ones as duplicates of the oldest (the parent Issue)
```

## Managing Duplicates

### When to Mark as Duplicate

Mark Issues as duplicate when:

* They represent the **identical underlying problem**
* Fixing one will fix all
* You want to consolidate discussion and resolution in one place

**Don't mark as duplicate if:**

* Issues are related but have different root causes
* Fixing one won't necessarily fix the other
* You want to track them separately for reporting

### Duplication Process

**Step-by-step:**

1. Identify duplicate Issues (via the Related Issues list or manual review)
2. Select the Issues to mark duplicate (2 or more) from a list view
3. Run the **Mark Issue Duplicate** action
4. Pharos sets the oldest selected Issue as the parent automatically
5. Other Issues: `Status__c` → `Duplicate`, `pharos__Related_Issue__c` → the parent

**What happens after:**

* Duplicate Issues are removed from active triaging views
* The parent Issue shows its duplicates (and any other linked Issues) in the Related Issues list
* Metrics remain separate — log counts don't merge onto the parent automatically
* Resolving the parent doesn't auto-resolve the duplicates

### Undoing Duplication

If you accidentally mark an Issue as duplicate:

1. Open the duplicate Issue
2. Use **Unlink** on the Related Issues list (clears `pharos__Related_Issue__c`), or clear the field directly
3. Change **Status** back to the appropriate value (e.g., `Triaged`)
4. Save

### Duplicate vs. Related

The two concepts are easy to confuse, so it helps to compare them side by side.

| Aspect         | Duplicate                      | Related                           |
| -------------- | ------------------------------ | --------------------------------- |
| **Meaning**    | Same problem                   | Connected problems                |
| **Action**     | Work on the parent only        | May need to fix both              |
| **Status**     | `Status__c` set to `Duplicate` | Status independent                |
| **Lookup**     | `Related_Issue__c` → parent    | `Related_Issue__c` → linked Issue |
| **Resolution** | Parent resolution applies      | Resolve independently             |

## How Fingerprint Tiers Drive Auto-Relating

### Hash 1, 2, and 3

Each Log carries three fingerprint tiers of decreasing precision, stored as Hash 1, 2, and 3. See [Log Fingerprinting](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-processing/log-fingerprinting.md) for how each fingerprint is built from the underlying error.

**Hash 1** (`pharos__Hash_1__c`, exact match):

* Used to decide whether an incoming log belongs to an existing Issue or starts a new one
* Stored on the Issue as `Key__c` for lookup

**Hash 2** (`pharos__Hash_2__c`, looser match):

* Computed alongside Hash 1
* A match here is checked against every open Issue category and takes priority over a Hash 3 match

**Hash 3** (`pharos__Hash_3__c`, loosest match):

* Currently only evaluated for **Flow** and **Process Builder** category logs
* Used as a fallback when no Hash 2 match exists

Hash 1 groups logs into Issues. Hash 2 and Hash 3 don't group logs — they drive the automatic `pharos__Related_Issue__c` link between separate Issues once those Issues already exist.

{% hint style="info" %}
Pharos does not publish a numeric confidence score for hash-tier matches. Treat a Hash 2 match as a closer resemblance than a Hash 3 match, and use the Related Issues list as a starting point for investigation rather than a definitive verdict.
{% endhint %}

## Best Practices

A few habits make relationships more useful throughout the Issue lifecycle.

### During Triage

When triaging, check relationships before you set a priority:

1. **Check Related Issues first** before prioritizing
   * Related Issue already Actioned? Lower priority (work on that one first)
   * Related Issue Completed? May have relevant fix notes
2. **Look for duplication patterns** in new Issues
   * Multiple Issues created the same day and pointing at each other via a hash-tier match? Likely duplicates
   * Mark duplicates early to avoid redundant work
3. **Use relationships for context**
   * Related Issues show you broader problem scope
   * Help identify if this is isolated or systemic

### During Resolution

While fixing an Issue, use its relatives to avoid redundant work and to record context:

1. **Review related Issues before starting work**
   * Check if a related Issue already has a solution
   * See if fixing one will address multiple
2. **Document relationships in comments**
   * "This Issue related to #12345, appears to be same root cause"
   * "Fixed the linked Issue, monitoring this for recurrence"
3. **Update duplicates when resolving the parent**
   * Add a comment on duplicates pointing to the parent's resolution
   * Close duplicates with a reference to the parent fix

### After Resolution

Once the fix is in, confirm it propagated and capture what you learned:

1. **Check if related Issues also resolved**
   * If the linked Issue is fixed, related ones may stop occurring
   * Mark as complete if confirmed
2. **Document lessons learned**
   * If multiple Issues stemmed from one root cause, document it on the parent
   * Helps future troubleshooting

## Reporting on Relationships

Pharos ships packaged reports that break volume down by hash tier — for example, **System Chart Log Occurrence by Hash 1/2/3** and **Summary by Date Filtered** — which are useful starting points for spotting fingerprint drift or a spike in duplicate-prone Issues. Beyond those, `Status__c` and `pharos__Related_Issue__c` are standard reportable fields, so you can build your own views such as:

* **Issues with an open related Issue** — filter `Related_Issue__c` not null and `Related_Issue__r.Status__c` not in `Completed`/`Duplicate`, to prioritize a parent that will resolve several children at once
* **Duplicate rate** — % of Issues with `Status__c = Duplicate`, filtering `Status != Duplicate` elsewhere to avoid double-counting

{% hint style="success" %}
**Next Steps:**

* [Duplication](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle/duplication.md) – Full duplication workflow and management
* [Creation](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle/creation.md) – How fingerprinting creates and groups Issues
* [Issue Details Overview](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details.md) – See full Issue details page structure
  {% endhint %}
