Skip to main content
pdd trace implements bidirectional traceability. Given a line number in a generated code file, it finds the corresponding section in the prompt file that produced that code. This makes it easy to navigate from a buggy line of code back to the prompt instruction that caused it.

​
Usage

pdd [GLOBAL OPTIONS] trace [OPTIONS] PROMPT_FILE CODE_FILE LINE_NUMBER

​
Arguments

​
PROMPT_FILE
string
required
The prompt file that generated the code being analyzed.
​
CODE_FILE
string
required
The generated code file containing the line to trace.
​
LINE_NUMBER
integer
required
The line number in the code file to trace back to its prompt origin.

​
Options

​
--output
string
Where to save the trace analysis results. Default: <basename>_trace_results.log. Also reads from PDD_TRACE_OUTPUT_PATH.

​
What it outputs

pdd trace prints the corresponding line number in the prompt file for the specified code line. The command also writes a results log (at --output) containing the full trace analysis.

​
When to use

Use pdd trace as part of the Traceability debugging workflow:
  • Debugging prompt logic — When a code line is behaving unexpectedly and you want to locate the prompt instruction that drove that behavior.
  • Code review — To understand which requirement or specification produced a particular implementation.
  • Root cause analysis — To identify which part of a prompt to modify when fixing a bug in the generated code.

​
Example

pdd trace \
  --output trace_results.log \
  factorial_calculator_python.prompt \
  src/factorial_calculator.py \
  42
This traces line 42 of src/factorial_calculator.py back to its origin in factorial_calculator_python.prompt and saves the full analysis to trace_results.log.

​
Bidirectional traceability

PDD maintains traceability in both directions:
  • Prompt → Code: pdd generate and pdd sync produce code from prompts.
  • Code → Prompt: pdd trace navigates back from a code line to the prompt instruction that produced it.
This bidirectional relationship is a core PDD design pattern. It ensures that developers can always locate the authoritative source of any behavior — even after multiple code modifications.
  • pdd bug — Use trace to identify which prompt section contributed to a bug, then bug to create a failing test for it.
  • pdd update — After tracing a bug to a prompt line, use update to correct the prompt and propagate the fix.

Build docs developers (and LLMs) love

Get started for freeTalk to us