Skill

Fail

Audit score 45

sf-debug

jaganpro/sf-skills

Analyze Salesforce debug logs to diagnose governor limits, stack traces, and performance issues with structured root-cause reporting.

Source View on skills.sh

What is sf-debug?

sf-debug helps you interpret Salesforce debug logs to find the root cause of failures, governor-limit violations, and performance problems. Use it when analyzing .log files, stack traces, SOQL/DML patterns, CPU/heap pressure, or slow queries—not for test execution, Apex code fixes, or Agentforce tracing.

Retrieve and parse Salesforce debug logs via CLI commands
Identify exceptions, fatal errors, and governor-limit violations
Detect SOQL/DML loops, non-selective queries, and repeated patterns
Analyze CPU and heap pressure hotspots
Classify issues by severity (Critical, Warning, Info) and recommend targeted fixes
Provide structured output with location, root cause, and verification steps

How to install sf-debug

npx skills add https://github.com/jaganpro/sf-skills --skill sf-debug

Prerequisites

Salesforce CLI (sf) installed and configured
Access to target Salesforce org with debug-log retrieval permissions
Debug logs enabled in the target org

Claude Code

Cursor

Windsurf

Cline

How to use sf-debug

1.Gather context: org alias, failing transaction name, timestamp, and user/record ID if available
2.Retrieve logs using sf apex list log and sf apex get log commands
3.Analyze logs in order: entry point, exceptions, governor limits, SOQL/DML patterns, CPU/heap hotspots, callout timing
4.Classify severity and identify the root cause using the high-signal issue patterns table
5.Report findings in the standard format: What failed, Where, Why, Severity, Recommended fix, Verification step
6.Delegate code implementation to sf-apex, test reproduction to sf-testing, or deployment to sf-deploy as needed

Use cases

Good for

Diagnose why a batch job hit governor limits and recommend bulk-safe refactoring
Analyze a stack trace from a failed transaction to pinpoint the failing class and method
Identify repeated SOQL queries in a loop and suggest collection-based alternatives
Investigate slow query performance by examining selectivity and indexed filters
Root-cause a null-pointer exception and guide the fix without implementing it

Who it's for

Salesforce developers troubleshooting production or sandbox failures
QA engineers analyzing test execution logs for performance bottlenecks
Platform architects reviewing debug logs for scalability issues
DevOps engineers diagnosing org health and transaction failures

sf-debug FAQ

When should I use sf-debug vs. sf-apex?

Use sf-debug for root-cause analysis and diagnosis of debug logs. Use sf-apex when you are ready to implement the code fix. sf-debug stops at the recommendation; sf-apex executes the change.

Can sf-debug help with Apex test failures?

No. For running, repairing, or analyzing Apex tests, use the sf-testing skill instead. sf-debug focuses on production/sandbox transaction logs.

What if the debug log doesn't show the issue?

Check that debug logs are enabled in the org, the timestamp window is correct, and the failing transaction actually executed. You may need to reproduce the issue with fresh logs or adjust the log level.

How do I know if an issue is Critical vs. Warning?

Critical issues cause runtime failures, hit hard limits, or risk data corruption. Warnings are near-limit conditions, non-selective queries, or slow paths. Info is optimization or hygiene.

Should I use sf-debug for Agentforce session tracing?

No. For Agentforce session traces and parquet telemetry, use the sf-ai-agentforce-observability skill instead.

Full instructions (SKILL.md)

Source of truth, from jaganpro/sf-skills.

name: sf-debug description: > Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use sf-testing), fixing Apex code (use sf-apex), or Agentforce session tracing (use sf-ai-agentforce-observability). license: MIT metadata: version: "1.1.0" author: "Jag Valaiyapathy" scoring: "100 points across 5 categories"

sf-debug: Salesforce Debug Log Analysis & Troubleshooting

Use this skill when the user needs root-cause analysis from debug logs: governor-limit diagnosis, stack-trace interpretation, slow-query investigation, heap / CPU pressure analysis, or a reproduction-to-fix loop based on log evidence.

When This Skill Owns the Task

Use sf-debug when the work involves:

.log files from Salesforce
stack traces and exception analysis
governor limits
SOQL / DML / CPU / heap troubleshooting
query-plan or performance evidence extracted from logs

Delegate elsewhere when the user is:

running or repairing Apex tests → sf-testing
implementing the code fix → sf-apex
debugging Agentforce session traces / parquet telemetry → sf-ai-agentforce-observability

Required Context to Gather First

Ask for or infer:

org alias
failing transaction / user flow / test name
approximate timestamp or transaction window
user / record / request ID if known
whether the goal is diagnosis only or diagnosis + fix loop

Recommended Workflow

1. Retrieve logs

sf apex list log --target-org <alias> --json
sf apex get log --log-id <id> --target-org <alias>
sf apex tail log --target-org <alias> --color

2. Analyze in this order

entry point and transaction type
exceptions / fatal errors
governor limits
repeated SOQL / DML patterns
CPU / heap hotspots
callout timing and external failures

3. Classify severity

Critical — runtime failure, hard limit, corruption risk
Warning — near-limit, non-selective query, slow path
Info — optimization opportunity or hygiene issue

4. Recommend the smallest correct fix

Prefer fixes that are:

root-cause oriented
bulk-safe
testable
easy to verify with a rerun

Expanded workflow: references/analysis-playbook.md

High-Signal Issue Patterns

Issue	Primary signal	Default fix direction
SOQL in loop	repeating `SOQL_EXECUTE_BEGIN` in a repeated call path	query once, use maps / grouped collections
DML in loop	repeated `DML_BEGIN` patterns	collect rows, bulk DML once
Non-selective query	high rows scanned / poor selectivity	add indexed filters, reduce scope
CPU pressure	CPU usage approaching sync limit	reduce algorithmic complexity, cache, async where valid
Heap pressure	heap usage approaching sync limit	stream with SOQL for-loops, reduce in-memory data
Null pointer / fatal error	`EXCEPTION_THROWN` / `FATAL_ERROR`	guard null assumptions, fix empty-query handling

Expanded examples: references/common-issues.md

Output Format

When finishing analysis, report in this order:

What failed
Where it failed (class / method / line / transaction stage)
Why it failed (root cause, not just symptom)
How severe it is
Recommended fix
Verification step

Suggested shape:

Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>

Cross-Skill Integration

Need	Delegate to	Reason
Implement Apex fix	sf-apex	code change generation / review
Reproduce via tests	sf-testing	test execution and coverage loop
Deploy fix	sf-deploy	deployment orchestration
Create debugging data	sf-data	targeted seed / repro data

Reference Map

Start here

Deep references

Rubric

references/scoring-rubric.md

Score Guide

Score	Meaning
90+	Expert analysis with strong fix guidance
80–89	Good analysis with minor gaps
70–79	Acceptable but may miss secondary issues
60–69	Partial diagnosis only
< 60	Incomplete analysis

Related skills

More from jaganpro/sf-skills and the wider catalog.

sf-deploy