Skip to main content
pdd change reads a GitHub issue describing a feature request, researches it, identifies affected prompts, modifies them in an isolated git worktree, runs a self-review loop, and opens a draft pull request — all automatically.

​
Usage

pdd [GLOBAL OPTIONS] change [OPTIONS] GITHUB_ISSUE_URL

​
Arguments

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

​
Options

​
--timeout-adder
float
default:"0.0"
Additional seconds to add to each step’s timeout. Useful for large codebases that take longer to analyze.
​
--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 as an environment variable.

​
The 12-step workflow

1

Duplicate check

Search for existing issues describing the same request. Merges duplicate content if found.
2

Documentation check

Verify the feature is not already implemented by reviewing repository documentation.
3

Research

Web search to clarify the specification and identify best practices for the feature.
4

Clarification

Assess whether requirements are clear enough to proceed. If not, posts clarifying questions with answer options as a GitHub comment and pauses the workflow until you reply.
5

Documentation changes

Analyze which documentation files need updates as part of this feature.
6

Identify dev units

Find the prompt files, generated code, examples, and tests that are affected by the change.
7

Architecture review

Identify architectural decisions that need to be made. Posts decision questions as a GitHub comment and pauses the workflow if answers are needed.
8

Analyze changes

Design the specific prompt modifications required to implement the feature.
9

Implement changes

Apply prompt modifications inside an isolated git worktree on a new branch.
10

Identify issues

Review all changes for problems — part of the iterative review loop.
11

Fix issues

Fix any identified problems. The review loop repeats up to 5 iterations.
12

Create PR

Open a draft pull request that links back to the original issue.

​
Answering clarifying questions

Steps 4 and 7 may pause the workflow to ask questions. When this happens:
  1. Open the GitHub issue — PDD has posted a comment with questions and numbered answer options.
  2. Reply in the issue comments with your answers.
  3. Re-run pdd change with the same issue URL. The workflow resumes from where it stopped, skipping already-completed steps.
Cross-machine resume is enabled by default. State is stored in a hidden GitHub comment, so you can start on one machine and continue on another. Use --no-github-state to keep state local only.

​
After the PR is created

The generated pull request includes a sync_order.sh script. After the PR is merged, run it to regenerate code from the updated prompts in the correct dependency order: 
./sync_order.sh

​
Branching behavior

pdd change creates a new git worktree based on your current HEAD:
  • From main/master: The new branch is based on the latest main, creating an independent PR.
  • From a feature branch: The new branch inherits commits from that branch, enabling stacked/dependent PRs.
A warning is displayed when running from a non-main branch. For independent changes, run pdd change from your main branch.

​
User story validation

After implementing prompt modifications, pdd change automatically runs the user story validation suite (equivalent to pdd detect --stories). The workflow fails if any story fails, ensuring the change does not break existing requirements.

​
Examples

# Implement a feature request
pdd change https://github.com/myorg/myrepo/issues/239

# Resume after answering clarifying questions
pdd change https://github.com/myorg/myrepo/issues/239

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

​
Manual mode (legacy)

For direct prompt modification without a GitHub issue: 
pdd change --manual [OPTIONS] CHANGE_PROMPT_FILE INPUT_CODE_FILE INPUT_PROMPT_FILE
  • CHANGE_PROMPT_FILE — File containing instructions for how to modify the input prompt.
  • INPUT_CODE_FILE — Code file generated from the input prompt (or a directory when using --csv).
  • INPUT_PROMPT_FILE — The prompt file to be modified.
  • --budget FLOAT — Maximum cost allowed for the change process (default: 5.0).
  • --output LOCATION — Where to save the modified prompt file. Defaults to modified_<basename>.prompt. Also reads from PDD_CHANGE_OUTPUT_PATH.
  • --csv — Use a CSV file for batch processing. The CSV must have prompt_name and change_instructions columns. When set, INPUT_CODE must be a directory.
# Single prompt change
pdd change --manual \
  --output modified_factorial_calculator_python.prompt \
  changes_factorial.prompt \
  src/factorial_calculator.py \
  factorial_calculator_python.prompt

# Batch change via CSV
pdd change --manual --csv --output modified_prompts/ changes_batch.csv src/
  • pdd detect — Used internally to identify affected prompts; also runs user story validation.
  • pdd sync — Run after merging the PR to regenerate code from updated prompts.

Build docs developers (and LLMs) love

Get started for freeTalk to us