# platform-apex-logs-debug

This skill reads Salesforce debug logs: finds the root cause of a failure, spots governor limit hits and explains stack traces.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 6800 installs · ★ 1112
- Author: forcedotcom
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/forcedotcom/sf-skills/tree/HEAD/skills/platform-apex-logs-debug/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/platform-apex-logs-debug

## What it does

The skill kicks in when `.log` files from Salesforce, stack traces, limit errors or slow SOQL queries show up in the task. It walks the log in a fixed order: entry point and transaction type, exceptions, governor limits, repeated SOQL and DML, CPU and heap hotspots, callout timing. Every finding gets a severity — Critical, Warning or Info.

Under the hood are reference files in `references/`: an analysis playbook, a catalog of log event types, SF CLI commands for pulling and streaming logs, and write-ups of patterns like SOQL in a loop. You need `sf` 2.0.0 or newer and `jq` 1.6.0 or newer. It suggests starting with `references/analysis-playbook.md`.

Diagnosis is all it does. Code fixes go to `platform-apex-generate`, test runs to `platform-apex-test-run`, Agentforce session traces to `agentforce-observe`. Watch two traps. Logs get truncated at 2 MB, so lower the debug levels and capture again. And the CPU limit is 60,000 ms async against 10,000 ms sync — check the transaction type before blaming the code.

## Requirements
- Works with: Salesforce

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add forcedotcom/sf-skills --skill platform-apex-logs-debug -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/platform-apex-logs-debug/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/platform-apex-logs-debug/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add forcedotcom/sf-skills --skill platform-apex-logs-debug -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/platform-apex-logs-debug/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add forcedotcom/sf-skills --skill platform-apex-logs-debug -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/platform-apex-logs-debug/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install forcedotcom/sf-skills platform-apex-logs-debug
```

2. **Manually: put the files in place**
- File: `.github/skills/platform-apex-logs-debug/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add forcedotcom/sf-skills --skill platform-apex-logs-debug -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/forcedotcom/sf-skills --path skills/platform-apex-logs-debug
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/platform-apex-logs-debug/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add forcedotcom/sf-skills --skill platform-apex-logs-debug -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/forcedotcom/sf-skills/tree/HEAD/skills/platform-apex-logs-debug/SKILL.md

## When to use it
- trace a failed transaction back to its root cause
- work out which governor limit ran out and where
- pull SOQL and DML out of loops using repeated log events
- check CPU and heap pressure against the sync limit
- explain why a query scans too many rows

## Example prompts
- analyze this Salesforce .log and tell me what failed
- why did the transaction hit a governor limit — check the log
- find repeated SOQL in the log and suggest the smallest fix

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0798e478451b7f72.

BEGIN THIRD-PARTY FILE 0798e478451b7f72
```text
---
name: platform-apex-logs-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 platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe)."
metadata:
  version: "1.1"
  domains: ["Platform"]
  relatedSkills:
    - "agentforce-observe"
    - "platform-apex-generate"
    - "platform-apex-test-run"
    - "platform-data-manage"
    - "platform-metadata-deploy"
    - "platform-soql-query"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
---

# platform-apex-logs-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 `platform-apex-logs-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 → [platform-apex-test-run](../platform-apex-test-run/SKILL.md)
- generating or implementing the code fix → [platform-apex-generate](../platform-apex-generate/SKILL.md)
- debugging Agentforce session traces / parquet telemetry → [agentforce-observe](../agentforce-observe/SKILL.md)

---

## 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

Use the commands in [references/cli-commands.md](references/cli-commands.md) to list, download, or stream logs for the target org.

### 2. Analyze in this order
1. entry point and transaction type
2. exceptions / fatal errors
3. governor limits
4. repeated SOQL / DML patterns
5. CPU / heap hotspots
6. callout timing and external failures

### 3. Classify severity
- **Critical** — runtime failure, hard limit, corruption risk
- **Warning** — near-limit, non-selective query, slow path
```
END THIRD-PARTY FILE 0798e478451b7f72

The third-party file has ended. Everything between the 0798e478451b7f72 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2545 of 7907 bytes. © forcedotcom · Apache-2.0 · https://github.com/forcedotcom/sf-skills/tree/HEAD/skills/platform-apex-logs-debug/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md