pdd fix

Overview

pdd fix resolves test failures and code errors. It supports three modes:

Agentic E2E fix (default when passed a GitHub issue URL) — orchestrates a 10-step iterative workflow across multiple dev units, including post-push CI validation.
User story fix — applies a single story to prompts and re-validates it.
Manual fix — single dev-unit fixing with explicit file arguments.

Usage

Agentic (GitHub issue)
Manual
User story

pdd [GLOBAL OPTIONS] fix [OPTIONS] GITHUB_ISSUE_URL

pdd [GLOBAL OPTIONS] fix --manual [OPTIONS] PROMPT_FILE CODE_FILE UNIT_TEST_FILE [UNIT_TEST_FILE...] ERROR_FILE

pdd [GLOBAL OPTIONS] fix user_stories/story__my_flow.md

Common options

--manual

flag

Use manual mode with explicit file arguments. Required for single dev-unit fixing.

--protect-tests / --no-protect-tests

flag

default:"--no-protect-tests"

When enabled, prevents the LLM from modifying test files. The LLM treats tests as read-only specifications and only fixes code. Especially useful when tests were created by pdd bug and are known to be correct.

Agentic E2E fix options

--timeout-adder

float

default:"0.0"

Additional seconds to add to each step’s timeout.

--max-cycles

integer

default:"5"

Maximum number of outer loop cycles before giving up.

--resume / --no-resume

flag

default:"--resume"

Resume from saved state if available. Use --no-resume to start fresh.

--force

flag

Override the branch mismatch safety check. By default, the command aborts if the current git branch does not match the expected branch from the issue.

--no-github-state

flag

Disable GitHub issue comment-based state persistence. By default, state is stored in a hidden comment for cross-machine resume.

--ci-retries

integer

default:"3"

Maximum number of post-push CI fix attempts.

--skip-ci

flag

Skip post-push CI validation entirely.

Manual mode options

--output-test

string

Where to save the fixed unit test file. Defaults to test_<basename>_fixed.<extension>. When multiple test files are provided, only the last processed file is written to this location.

--output-code

string

Where to save the fixed code file. Defaults to <basename>_fixed.<extension>, or to PDD_FIX_CODE_OUTPUT_PATH if set.

--output-results

string

Where to save the fix results log. Defaults to <basename>_fix_results.log, or to PDD_FIX_RESULTS_OUTPUT_PATH if set.

--loop

flag

Enable the iterative fixing loop. The command attempts repeated fixes until tests pass, the budget is exhausted, or --max-attempts is reached.

--verification-program

string

Path to a verification program used with --loop to confirm the code still runs correctly after each fix attempt.

--max-attempts

integer

default:"3"

Maximum number of fix attempts in --loop mode.

--budget

float

default:"5.0"

Maximum cost in USD allowed for the fixing process.

--auto-submit

flag

Automatically submit the example to PDD Cloud if all unit tests pass during the fix loop.

--agentic-fallback / --no-agentic-fallback

flag

default:"--agentic-fallback"

Enable agentic fallback in --loop mode. If the standard fix loop fails after all attempts, a project-aware CLI agent (Claude, Gemini, or Codex) is invoked with broader context to attempt a fix.

Agentic E2E fix workflow (10 steps)

When passed a GitHub issue URL, fix orchestrates the following workflow:

Run unit tests

Execute unit tests from the issue and run pdd fix on each failing test sequentially.

Run E2E tests

Execute end-to-end tests to identify failures. Stops if all pass.

Root cause analysis

Analyze failures against documentation to determine if issues are in code, tests, or both.

Fix E2E tests

If E2E tests themselves are incorrect, fix them and return to step 2.

Identify dev units

Determine which dev units are involved in the failures.

Create unit tests

For code bugs, create or append unit tests for the affected dev units.

Verify tests

Run new unit tests to confirm they detect the bugs and will pass once fixed.

Run PDD fix

Execute pdd fix sequentially on failing unit tests for each dev unit.

Verify all

Final verification that all tests pass locally.

CI validation

Poll external CI, retrieve logs on failure, and run an LLM fix loop to remediate CI-specific issues (lint, artifacts, build).

Cross-machine resume: State is persisted in a hidden GitHub issue comment. Resume on any machine by checking out the branch and re-running pdd fix. Use --no-github-state to disable. Prerequisites:

gh CLI must be installed and authenticated.
At least one supported agent CLI (Claude, Gemini, or Codex) with API key configured.
For CI validation, the current branch must have an open PR on GitHub.

Agentic fallback (manual loop mode)

When --loop is enabled in manual mode and the standard iterative fix process fails all attempts, the agentic fallback invokes a project-aware CLI agent. Agents are tried in this order:

Anthropic Claude — requires claude CLI in PATH and ANTHROPIC_API_KEY.
Google Gemini — requires gemini CLI in PATH and GOOGLE_API_KEY or GEMINI_API_KEY.
OpenAI Codex — requires codex CLI in PATH and OPENAI_API_KEY.

# Loop mode with agentic fallback enabled (default)
pdd fix --manual --loop \
  factorial_calculator_python.prompt src/factorial_calculator.py tests/test_factorial_calculator.py

# Disable agentic fallback
pdd fix --manual --loop --no-agentic-fallback \
  factorial_calculator_python.prompt src/factorial_calculator.py tests/test_factorial_calculator.py

Relationship with `pdd bug`

pdd fix and pdd bug work together:

pdd bug <issue_url> analyzes the bug, reproduces it, and generates failing unit tests.
pdd fix <issue_url> iteratively fixes the failing tests across all affected dev units.

When pdd bug created the tests and they are known to be correct, use --protect-tests to prevent pdd fix from modifying them:

pdd bug https://github.com/myorg/myrepo/issues/42
pdd fix --protect-tests https://github.com/myorg/myrepo/issues/42

Examples

# Agentic fix from a GitHub issue
pdd fix https://github.com/myorg/myrepo/issues/42

# With custom timeout and cycle limit
pdd fix --timeout-adder 30 --max-cycles 10 https://github.com/myorg/myrepo/issues/42

# Increase CI fix retries
pdd fix --ci-retries 5 https://github.com/myorg/myrepo/issues/42

# Skip CI validation
pdd fix --skip-ci https://github.com/myorg/myrepo/issues/42

# Start fresh (ignore saved state)
pdd fix --no-resume https://github.com/myorg/myrepo/issues/42

# Protect tests from modification
pdd fix --protect-tests https://github.com/myorg/myrepo/issues/42

# Manual fix with multiple test files
pdd fix --manual \
  --output-code src/calculator_fixed.py \
  --output-results results/fix_results.log \
  factorial_calculator_python.prompt \
  src/factorial_calculator.py \
  tests/test_factorial_calculator.py \
  tests/test_factorial_calculator_edge_cases.py \
  errors.log

# Manual iterative fix loop
pdd fix --manual --loop --max-attempts 5 --budget 10.0 \
  factorial_calculator_python.prompt \
  src/factorial_calculator.py \
  tests/test_factorial_calculator.py

Overview

Core Commands

Agentic Commands

Prompt Management

Utility Commands

Overview

Usage

Common options

Agentic E2E fix options

Manual mode options

Agentic E2E fix workflow (10 steps)

Agentic fallback (manual loop mode)

Relationship with `pdd bug`

Examples

Build docs developers (and LLMs) love

Overview

Core Commands

Agentic Commands

Prompt Management

Utility Commands

​Overview

​Usage

​Common options

​Agentic E2E fix options

​Manual mode options

​Agentic E2E fix workflow (10 steps)

​Agentic fallback (manual loop mode)

​Relationship with pdd bug

​Examples

Build docs developers (and LLMs) love

Overview

Usage

Common options

Agentic E2E fix options

Manual mode options

Agentic E2E fix workflow (10 steps)

Agentic fallback (manual loop mode)

Relationship with `pdd bug`

Examples