Skip to main content
pdd checkup explores your project, audits dependencies, build integrity, cross-module interfaces, and tests, then optionally applies fixes, writes regression and end-to-end tests, and opens a pull request — all driven by a GitHub issue.

​
Usage

pdd [GLOBAL OPTIONS] checkup [OPTIONS] GITHUB_ISSUE_URL

​
Arguments

​
GITHUB_ISSUE_URL
string
required
URL of the GitHub issue describing what to check (e.g., https://github.com/myorg/myrepo/issues/42). The issue body describes the scope of the health check — for example, “Check the entire CRM app.”

​
Options

​
--no-fix
boolean
default:"false"
Report-only mode. Discover and report all issues without applying any fixes. Runs steps 1–5 and 7 only.
​
--timeout-adder
float
default:"0.0"
Additional seconds to add to each step’s timeout. Increase this for large projects with slow build or test steps.
​
--no-github-state
boolean
default:"false"
Disable GitHub state persistence and use local-only state.

​
The 8-step workflow

1

Discover

Scan the project structure, tech stack, and module inventory to build a complete picture of the codebase.
2

Dependency audit

Check that all imports resolve, no packages are missing, and no circular dependencies exist.
3

Build check

Run build and compile commands, checking for syntax errors and type errors.
4

Interface check

Verify cross-module interfaces are consistent, frontend navigation is reachable, and API call patterns are uniform.
5

Test execution

Run the full test suite and identify all failures.
6

Fix issues

Apply fixes in three sub-steps:
  • 6a — Fix missing deps, import errors, interface mismatches, build errors, orphan pages, and inconsistent API patterns.
  • 6b — Write regression tests for every fix applied.
  • 6c — Write end-to-end and integration tests for cross-module interactions.
7

Verify

Re-run the build and tests to confirm all fixes are effective.
8

Create PR

Open a pull request containing all fixes and newly written tests.
Steps 3–7 run in an iterative loop (up to 3 iterations). If step 7 finds remaining issues, the workflow loops back to step 3 for another pass. The loop exits when step 7 reports “All Issues Fixed” or the maximum iteration count is reached.

​
Worktree isolation

All fix steps run inside an isolated git worktree on a checkup/issue-{N} branch. Your working directory is never modified during the process.

​
Cross-machine resume

Workflow state is stored as a hidden comment on the GitHub issue by default, allowing you to resume from any machine. Use --no-github-state to disable this behavior and keep state local.

​
Examples

# Full checkup with automatic fixes and a PR
pdd checkup https://github.com/myorg/myrepo/issues/42

# Report-only mode — no fixes applied
pdd checkup --no-fix https://github.com/myorg/myrepo/issues/42

# Allow extra time for large projects
pdd checkup --timeout-adder 120 https://github.com/myorg/myrepo/issues/42
  • pdd bug — Create failing tests for a specific known bug.
  • pdd fix — Fix failing tests for a specific issue.
  • pdd sync — Run the full prompt-to-code cycle for individual modules.

Build docs developers (and LLMs) love

Get started for freeTalk to us