doom-debug

name	doom-debug
description	Systematically debug a doom emacs issue — errors, broken packages, slow startup, keybinding conflicts
argument-hint	<description of the issue>
allowed-tools	Read, Grep, Bash

Systematically diagnose and fix a doom emacs issue.

Issue reported

$ARGUMENTS

Diagnostic Steps (run in order, stop when root cause found)

1. Reproduce in clean environment

Ask the user: does the issue appear with emacs --init-directory ~/.config/emacs -q?

• Yes → doom core issue, not user config
• No → user config (config.org) is the cause → proceed to step 3

2. Run doom doctor

~/.config/emacs/bin/doom doctor 2>&1 | grep -E "(✗|Warning|Error)" | head -40

Fix any reported issues first.

3. Check recent changes

git -C ~/.config/doom log --oneline -10
git -C ~/.config/doom diff HEAD~1 -- config.org packages.el init.el

Correlate the issue onset with recent commits.

4. Search config.org for the relevant config

Grep config.org for the package/feature name mentioned in the issue. Read surrounding context.

5. Check for byte-compile errors

~/.config/emacs/bin/doom sync --rebuild 2>&1 | grep -i "error\|warning" | head -30

6. Check Emacs messages / warnings

Ask user to run inside Emacs:

• M-x view-echo-area-messages — recent messages
• *Messages* buffer — startup output
• *Warnings* buffer — non-fatal issues

7. Locate the error source

If there's a backtrace or error message, grep config.org and installed package sources:

find ~/.config/emacs/.local/straight/repos -name "*.el" | xargs grep -l "SYMBOL" 2>/dev/null | head -10

8. Common fixes by symptom

Symptom	Likely cause	Fix
Symbol's function definition is void	package not loaded yet	Add :defer nil or (after! pkg ...)
Keybinding not working	wrong keymap or evil state	Check map! evil state flag (:n, :i, etc.)
Package not found after sync	typo or wrong :recipe	Check packages.el
Slow startup	too many :demand t or no :defer	Profile with M-x esup
Wrong type argument	config loaded before package	Wrap in (after! package ...)
Native comp warnings	stale eln cache	rm -rf ~/.config/emacs/eln-cache && doom sync

Reporting back

After diagnosis:

1. State the root cause clearly
2. Show the specific config.org location (heading path) where the fix goes
3. Make the minimal change needed — do not refactor surrounding code