Skip to main content
pdd bug takes a GitHub issue URL, walks through a 10-step agentic workflow to reproduce the bug and understand its root cause, then creates a failing unit test and a draft PR. Use pdd fix with the same issue URL afterward to resolve the failing tests.

​
Usage

pdd [GLOBAL OPTIONS] bug [OPTIONS] GITHUB_ISSUE_URL

​
Arguments

​
GITHUB_ISSUE_URL
string
required
URL of the GitHub issue describing the bug (e.g., https://github.com/owner/repo/issues/42).

​
Options

​
--output
string
Where to save the generated unit test. Default: test_<module>_bug.py. Also reads from PDD_BUG_OUTPUT_PATH.
​
--language
string
default:"Python"
Programming language for the generated unit test. Used in manual mode only.
​
--timeout-adder
float
default:"0.0"
Additional seconds to add to each step’s timeout.
​
--no-github-state
boolean
default:"false"
Disable GitHub issue comment-based state persistence and use local-only state. You can also set PDD_NO_GITHUB_STATE=1.
​
--manual
boolean
default:"false"
Use legacy manual mode with explicit file arguments instead of the agentic workflow.

​
The 10-step workflow

1

Duplicate check

Search for existing issues describing the same problem. If a duplicate is found, its content is merged and the duplicate is closed.
2

Documentation check

Review repository documentation to determine whether this is a genuine bug or a user error.
3

Triage

Assess whether enough information exists to proceed. If the issue already contains a detailed root cause analysis (file paths, line numbers, causal explanation), the workflow fast-tracks to root cause analysis, skipping reproduction.
4

Reproduce

Attempt to reproduce the issue locally. Posts a confirmation comment. Skipped when Step 3 fast-tracks.
5

Root cause analysis

Run experiments to identify the root cause. Performs a variable reference audit to find sibling bugs in parallel code paths, and a state symmetry check to detect save/restore asymmetries. Assesses whether the fix is localized or cross-cutting.
6

Prompt classification

Determine whether the bug is in the code implementation or in the prompt specification. If the prompt is defective, auto-fixes the prompt file and posts the changes as a comment.
7

Test plan

Design a plan for creating tests to detect the problem. Enumerates all affected output channels and all distinct code paths (first-run, resume, retry, error recovery). Prefers appending to existing test files over creating new ones.
8

Generate test

Create the failing unit test and post it as a GitHub comment.
9

Verify detection

Confirm the unit test successfully detects the bug. Classifies whether an end-to-end test is also needed.
10

Create draft PR

Open a draft pull request containing the failing tests and link it to the issue.
Cross-machine resume is enabled by default. Workflow state is stored in a hidden GitHub comment, so you can start on one machine and continue from another. Use --no-github-state to keep state local only.

​
Pairing with pdd fix

pdd bug is designed to be followed by pdd fix: 
# Step 1: Analyze the bug and create a failing test
pdd bug https://github.com/myorg/myrepo/issues/42

# Step 2: Fix the failing tests automatically
pdd fix https://github.com/myorg/myrepo/issues/42
If pdd bug correctly identified the bug and created valid failing tests, use --protect-tests with pdd fix to prevent the LLM from modifying the tests. This ensures only the production code is fixed to make the tests pass:
pdd fix --protect-tests https://github.com/myorg/myrepo/issues/42

​
Branching behavior

pdd bug creates a new git worktree based on your current HEAD, the same as pdd change:
  • From main/master: Independent PR based on latest main.
  • From a feature branch: Branch inherits commits, enabling stacked PRs.

​
Examples

# Agentic mode (recommended)
pdd bug https://github.com/myorg/myrepo/issues/42

# Resume after addressing questions or providing more info
pdd bug https://github.com/myorg/myrepo/issues/42

# Disable cloud state persistence
pdd bug --no-github-state https://github.com/myorg/myrepo/issues/42

​
Manual mode (legacy)

pdd bug --manual \
  prompt.prompt \
  code.py \
  main.py \
  current_output.txt \
  desired_output.txt
Manual mode requires exactly 5 positional arguments:
​
PROMPT_FILE
string
required
The prompt file that generated the code containing the bug.
​
CODE_FILE
string
required
The code file that contains the buggy implementation.
​
PROGRAM_FILE
string
required
The program file that exercises the buggy code.
​
CURRENT_OUTPUT
string
required
File containing the actual (incorrect) output from the program.
​
DESIRED_OUTPUT
string
required
File containing the expected (correct) output.
  • pdd fix — Resolves the failing tests created by pdd bug.
  • pdd checkup — Full project health check that can surface bugs across the entire codebase.

Build docs developers (and LLMs) love

Get started for freeTalk to us