> 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-lifecycle/triaging.md).

# Triaging

Learn about the issue triage process and how it can be facilitated with the data  available in the issue tracker. Implement periodic issue review effectively.

Triaging is the systematic process of reviewing, categorizing, prioritizing, and actioning Issues. Without systematic triage, error management becomes chaotic and reactive.

## Why Triaging Matters

Without a triage process, teams fall into two failure modes—chasing every alert individually, or letting errors pile up unreviewed. Triaging solves both.

**The "Whack-a-Mole" Problem:**

* Developers context-switch constantly to investigate alerts
* No prioritization—every error treated as equally urgent
* High-impact Issues get lost among low-priority noise
* Same errors investigated multiple times by different people

**The "Unmanaged Backlog" Problem:**

* Hundreds of unreviewed errors accumulate
* No one owns the decision: "Should we fix this?"
* Critical problems hidden in the pile
* Team paralyzed by volume—doesn't know where to start

**What Triaging Provides:**

* **Systematic review:** Regular cadence ensures nothing falls through cracks
* **Data-driven prioritization:** Decisions based on impact metrics, not loudest voice
* **Clear ownership:** Every Issue gets a decision and next step
* **Trend visibility:** Track if system health is improving or degrading
* **Proactive stance:** Find and fix Issues before users report them

## Triage Goals

Every triage session works toward four outcomes:

1. **Assess Impact:** How many users? Which business processes? How critical?
2. **Assign Priority:** Highest, High, Medium, Low, or Lowest?
3. **Determine Action:** Fix now, backlog, won't fix, or needs more investigation?
4. **Track Progress:** Are we reducing error rates over time?

## Triage is Not Debugging

Triage and debugging are distinct activities with different goals, owners, and time investments:

| Triage                                                    | Debugging                                       |
| --------------------------------------------------------- | ----------------------------------------------- |
| **Goal:** Decide priority and next steps                  | **Goal:** Identify root cause and implement fix |
| **Who:** Admins, BAs, leads (non-developers can do this)  | **Who:** Developers with code knowledge         |
| **Time:** 5-10 minutes per Issue                          | **Time:** Hours or days per Issue               |
| **Output:** Priority assignment, ticket creation decision | **Output:** Code changes, configuration updates |

**Key Insight:** Effective triaging doesn't require deep technical knowledge. Impact metrics enable anyone to make informed priority decisions.

## The Pharos Triage Workflow

The Pharos triage workflow breaks into six repeatable steps, from setting a cadence through documenting each decision.

### Step 1: Establish a Regular Cadence

Consistency matters more than frequency—pick a schedule the team can sustain.

**Recommended Schedule:**

* **Weekly triage sessions:** 30-60 minutes
* **Rotating assignment:** Different team member each week
* **Consistent time:** Same day/time builds habit

**Benefits of Rotation:**

* Distributes system knowledge across team
* Prevents single-point-of-failure knowledge concentration
* Builds empathy between admins, developers, and support
* Fresh eyes spot patterns others might miss
* Prevents vacation/absence from blocking the triage process
* Spreads awareness of production issues across entire team

**Rotation Models:**

*Within Team (Recommended Starting Point):*

```
Team: Apex Support Pod (7 members)
Rotation: Weekly
Schedule:
  - Week 1: Team Member A
  - Week 2: Team Member B  
  - Week 3: Team Member C
  (Cycles through all 7 members over 7 weeks)
```

*Cross-Functional (For Platform-Level Issues):*

```
Team: Technical Leads from all pods
Rotation: Bi-weekly
Focus: Issues without clear functional area ownership
Examples: Governor limit exceptions, platform events, flex queue
```

{% hint style="warning" %}
**Maintaining Cadence is Critical**

If you break the cadence for 2 weeks, the volume accumulates and makes the next session much more daunting. Consistent rhythm prevents backlog buildup. If the primary person is unavailable, the rotation ensures someone else can step in seamlessly.
{% endhint %}

### Step 2: Filter to Active Issues

Narrow the queue to the Issues that actually warrant attention this session before you start reviewing.

**Triage Queue Criteria:**

```
Filter: "Active Issues for Triage"

WHERE:
  - Status IN ["New", "Triaged"]
  - Last Occurrence: Within last 7 days
  - Org Type: "Production"

SORT BY:
  - User Impact (Descending)
  
LIMIT: 50 (don't try to triage everything in one session)
```

**Using Split View for Efficient Triage:**

The split view layout is highly recommended for triage sessions as it allows you to:

* Click through issues quickly in the left panel
* View full details in the right panel without page navigation
* Add comments using the feed component in a dedicated tab
* Maintain context while moving between issues

{% hint style="info" %}
**Pro Tip:** Customize your lightning page to include a Chatter feed component in a tab. This provides a convenient space for documenting triage decisions without cluttering the main view.
{% endhint %}

### Step 3: Review Each Issue

For each Issue in the queue, answer four questions:

#### Question 1: Who is Affected?

**Check User Impact Metrics:**

```mermaid
graph TD
    A[Users Impacted: 47]
    A --> B[Profile Breakdown]
    B --> B1[Sales Rep: 32 users]
    B --> B2[Account Manager: 13 users]
    B --> B3[System Admin: 2 users]
    A --> C[Impact Type: User-facing - humans affected]
```

**Decision Signals:**

* **High user count (>20):** Likely Highest or High priority
* **Low user count (<5):** Possibly Medium or Low
* **System users only:** Backend processing issue, may not be user-visible
* **Increasing trend:** Growing problem requiring urgent attention

#### Question 2: What's the Business Impact?

**Check Data Impact Metrics:**

```mermaid
graph TD
    A[Records Impacted: 1,245]
    A --> B[Object Types]
    B --> B1[Opportunity: 823 records]
    B --> B2[Order: 412 records]
    B --> B3[Invoice__c: 10 records]
    A --> C[Functional Area: Flow]
```

**Business Context Questions:**

* Is this blocking a revenue-generating process?
* Does this affect customer satisfaction (SLAs)?
* Is there compliance/regulatory risk?
* Can users work around this issue?

#### Question 3: How Frequent/Persistent is This?

**Pattern Interpretations:**

| Pattern                     | Meaning                            | Priority Influence             |
| --------------------------- | ---------------------------------- | ------------------------------ |
| Daily, consistent for weeks | Entrenched problem                 | ↑ High (won't resolve itself)  |
| Single spike, then stopped  | Transient data issue               | ↓ Low (possibly self-resolved) |
| Increasing frequency        | Growing problem                    | ↑ Highest (getting worse)      |
| Decreasing frequency        | Resolving naturally or partial fix | → Medium (monitor)             |
| Sporadic, unpredictable     | Hard to reproduce                  | → Medium (needs investigation) |

#### Question 4: What's the Technical Severity?

**Even without code knowledge, you can assess:**

* `Required field missing` → Likely config issue (admin fix)
* `CPU time limit exceeded` → Performance problem (developer fix)
* `Callout timeout` → Integration issue (external system)
* `Duplicate value` → Data quality issue (operations/data team)

### Step 4: Assign Priority

Use a standardized priority matrix for consistency:

| Priority    | Criteria                                                                                                                         | SLA                                            |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Highest** | <p>• User-facing production failure<br>• Revenue-impacting<br>• >50 users affected<br>• No workaround exists</p>                 | Fix within 24 hours                            |
| **High**    | <p>• Daily occurrence<br>• Data integrity risk<br>• >10 users affected<br>• Workaround exists but painful</p>                    | Fix within 1 week                              |
| **Medium**  | <p>• Persistent but low user impact<br>• Backend processing issue<br>• <10 users affected<br>• Business can operate normally</p> | <p>Fix within 1 month<br>or add to backlog</p> |
| **Low**     | <p>• Sporadic occurrence<br>• No user reports<br>• Minimal business impact<br>• Edge case scenario</p>                           | Backlog only                                   |
| **Lowest**  | <p>• One-time or test-data occurrence<br>• Non-production<br>• No business impact</p>                                            | Monitor only, close proactively                |

### Step 5: Take Action

Based on priority, execute next steps:

**Highest:**

1. Create Jira ticket immediately
2. Notify on-call team via Slack/PagerDuty
3. Add detailed triage notes to Issue
4. Assign to specific developer
5. Monitor for escalation (check in after 4 hours)

**High:**

1. Create Jira ticket
2. Add to sprint backlog
3. Tag with "high-priority" label
4. Include in weekly planning discussion
5. Track in status updates

**Medium:**

1. Create Jira ticket OR add to backlog
2. Document findings in Issue comments
3. Link related Issues if pattern exists
4. Re-evaluate monthly for priority changes

**Low:**

1. Do NOT create ticket (not worth sprint time)
2. Add detailed notes explaining why Low priority
3. Mark status as "Triaged"
4. Set review date (3-6 months)

### Step 6: Document Decisions

Capture the reasoning behind each decision so future reviewers don't have to re-investigate.

**What to Document:**

```mermaid
graph TD
    A[TRIAGE OUTCOME]
    A --> B[Priority: High]
    A --> C[Rationale]
    C --> C1[23 users impacted - Sales team]
    C --> C2[Daily occurrence - 47 times in last week]
    C --> C3[Opportunity object - revenue risk]
    C --> C4[Recent validation rule change identified as likely cause]
    A --> D[Action Taken]
    D --> D1[Created Jira ticket: PROJ-1234]
    D --> D2[Assigned to: Sarah - Admin]
    D --> D3[Likely fix: Adjust validation rule criteria]
    A --> E[Next Review: Sprint Planning - Tuesday]
```

## Real-World Triage Walkthrough

Here's a practical example of triaging different types of issues:

### Example 1: New Issue with Limited Data

**Initial Assessment:**

```
Issue: Flow Failed - Case Processing
Status: New
Created: Yesterday
Occurrences: 2
Users Impacted: 1 (System User)
Records: 8 (Case, Email Message, Contact)
```

**Triage Decision:** Skip for now - insufficient data to make a priority decision. This is a brand new issue with minimal occurrences. Mark it to review in the next triage session when more occurrence data has accumulated.

**Reasoning:** Not every issue requires immediate action. For newly created issues with sparse data, it's acceptable to wait for more information rather than making premature priority assignments.

### Example 2: Old Issue with Sporadic Occurrence

**Initial Assessment:**

```
Issue: Marketo User Contact Error
Status: New
Created: June 2023 (18 months ago)
Total Occurrences: 766
Users Impacted: 3
Last Occurred: Today (after 6+ month gap)
Frequency: Very sparse (large gaps between occurrences)
```

**Triage Decision:** Priority: Low. Last occurrence was over 6 months ago before today. Not user-impacting, minimal business effect.

**Action Taken:**

* Changed status to "Triaged"
* Added comment: "Does not seem to be user impacting. Last occurrence over 6 months ago. Low priority."
* No Jira ticket created

### Example 3: Platform-Level Issue (Flex Queue)

**Initial Assessment:**

```
Issue: Too Many Jobs in Flex Queue
Status: New
Created: June 2024
Occurrences: 76 times
Pattern: Happens every ~4 days
Impact: Job Request Trigger unable to fire
Users: System processing (not user-facing)
```

**Triage Decision:** Priority: High. This indicates a larger system capacity issue affecting background processing.

**Rationale:**

* Persistent problem (happening for months)
* Hints at deeper org-wide issue with batch job scheduling
* While not directly user-facing, could impact business-critical automation
* Not a data issue—jobs aren't starting at all

**Action Taken:**

* Changed status to "Triaged"
* Added comment: "This is likely a larger issue with regards to our Flex Queue being bogged down. Job Request on job isn't firing at all times. Could be a deeper issue here with the flex queue. Support."
* Marked for Jira ticket creation

### Example 4: User-Facing Validation Error

**Initial Assessment:**

```
Issue: Field Custom Validation Exception
Status: New
Created: September 2023 (last year)
Occurrences: 147 times over 15 months
Pattern: Roughly weekly occurrence
Users Impacted: 13 users
Records: Primarily Case objects
Frequency: ~7 days between occurrences
```

**Triage Decision:** Priority: High (due to user-facing nature and history)

**Rationale:**

* User-impacting: Real users seeing error messages
* Has history: Been occurring for over a year
* Regular pattern: Happens consistently every week
* Should be easy to fix: Validation rule failures are typically configuration issues

**Action Taken:**

* Changed status to "Triaged"
* Added comment: "Looks like it's user impacting and has a bit of history to it. The error should be easy enough to fix as it's related to a validation rule failure."
* Marked for Jira ticket creation

### Example 5: Duplicate Issues (Same Root Cause)

When you identify multiple issues that appear to be the same problem:

1. Select all related issues
2. Use "Mark Duplicate" action
3. System automatically sets the oldest issue as the parent
4. Other issues are marked as duplicates and linked

This prevents:

* Multiple people investigating the same problem
* Duplicate tickets in your backlog
* Confusion about which issue to track

## Time Investment and Efficiency

Triage is fast once the process is familiar, and spreading it across a team keeps the per-person load low.

**Expected Time Per Issue:** 1-2 minutes once familiar with the process

**Sample Session Metrics:**

* Session Duration: 15-20 minutes
* Issues Reviewed: 5-10 issues
* With team rotation: 60+ issues triaged per week across functional areas

**Parallelization Strategy:** When divided by functional area across multiple team members:

* 18 functional areas × 3-4 issues each = 54-72 issues per session
* Total team time investment: \~2 hours distributed across team
* Result: Comprehensive coverage without overwhelming any single person

## How Pharos Enables Effective Triage

Three capabilities make this workflow practical: aggregation, impact metrics, and preserved history.

### 1. Aggregation Eliminates Noise

Grouping logs into Issues collapses hundreds of records into a handful of decisions.

**Without Pharos (Raw Logs):**

* Reviewing 500 log records from last week
* Manually group by similarity
* Time Required: 4-6 hours
* Result: Incomplete, error-prone

**With Pharos (Issues):**

* Reviewing 15 Issues (grouped from 500 logs)
* Automatic grouping via fingerprinting
* Time Required: 30-45 minutes
* Result: Complete, accurate, actionable

### 2. Impact Metrics Enable Non-Developer Triage

Because priority decisions rest on impact data rather than code knowledge, anyone can triage effectively.

**Admin Perspective:**

```
Issue: "Apex Exception in OpportunityTriggerHandler"

I don't know what OpportunityTriggerHandler.afterInsert line 156 does.

But I CAN see:
✓ 47 users affected (that's a lot)
✓ 823 Opportunities impacted (revenue object!)
✓ Happening every day for 2 weeks (persistent)
✓ Apex functional area (execution context confirmed)

Decision: HIGH PRIORITY
Rationale: Large user impact on revenue-critical object
Action: Create Jira ticket for developer investigation
```

This is **impact-based triage** and it works without technical knowledge.

### 3. Historical Context Prevents Re-Investigation

Comments left on an Issue carry forward, so each triager builds on prior findings instead of starting over.

**With Pharos Comments:**

```
Week 1 Comment:
"Investigated. Root cause: Validation rule added May 15. 
 Workaround: Sales can leave Industry field blank. 
 Decision: Low priority - won't fix, workaround acceptable."

Week 2: New triager reads comment, skips re-investigation
Week 3: Issue closed, no wasted time
```

## Measuring Triage Effectiveness

Track a few key metrics to confirm your triage process is keeping pace and to know when to adjust:

| Metric                   | Target            | Action If Not Meeting           |
| ------------------------ | ----------------- | ------------------------------- |
| **Triage Latency**       | <7 days           | Increase triage frequency       |
| **Ticket Creation Rate** | >80% High/Highest | Improve prioritization training |
| **Resolution Rate**      | Improving monthly | Allocate more sprint capacity   |
| **Average Age**          | Decreasing        | Triage more aggressively        |

{% hint style="success" %}
**Next Steps to Establish Your Triage Process**

1. Schedule recurring weekly triage session (30-60 min)
2. Assign rotating team member each week
3. Use the triage workflow outlined above
4. Document decisions in Issue comments
5. After 4 weeks, review: Are you reducing the backlog? Adjust cadence if needed.
   {% endhint %}
