Skip to main content
pdd detect has two modes: change detection mode and user story validation mode. Change detection identifies which prompts are impacted by a described change. User story validation (--stories) checks that all user stories continue to pass against your current set of prompts. pdd change uses pdd detect internally after modifying prompts.

​
Usage

# Change detection mode
pdd [GLOBAL OPTIONS] detect [OPTIONS] PROMPT_FILE... CHANGE_FILE

# User story validation mode
pdd [GLOBAL OPTIONS] detect --stories [OPTIONS]

​
Arguments

​
PROMPT_FILE...
string
required
One or more prompt files to analyze. The last positional argument is always treated as the CHANGE_FILE. Not allowed in --stories mode.
​
CHANGE_FILE
string
required
A file whose content describes the change to be analyzed. PDD uses this description to determine which prompts need modifications. Not allowed in --stories mode.

​
Options

​
--output
string
Where to save the CSV analysis results. Default: <change_file_basename>_detect.csv. Also reads from PDD_DETECT_OUTPUT_PATH. Not supported in --stories mode.
​
--stories
boolean
default:"false"
Run user story validation mode. Positional PROMPT_FILES and CHANGE_FILE arguments are not allowed when this flag is set.
​
--stories-dir
string
Directory containing story__*.md files. Default: user_stories. Used in --stories mode only.
​
--prompts-dir
string
Directory containing .prompt files. Default: prompts. Used in --stories mode only.
​
--include-llm
boolean
default:"false"
Include *_llm.prompt files in user story validation. Used in --stories mode only.
​
--fail-fast / --no-fail-fast
boolean
default:"true"
Stop on the first failing story in --stories mode. Use --no-fail-fast to run all stories and collect all failures before reporting.

​
Output format

In change detection mode, the output CSV has two columns:
ColumnDescription
prompt_nameThe name of the prompt file that needs changes
change_instructionsDescription of what changes are needed in that prompt
This CSV format is compatible with pdd change --csv, allowing you to chain the commands: detect which prompts need changes, then batch-apply them.

​
User story validation mode

In --stories mode, pdd detect validates each story__*.md file against the current set of prompts. A story passes when detect returns no required prompt changes for that story’s scope. Stories may include optional metadata to scope validation to a subset of prompts: 
<!-- pdd-story-prompts: prompts/a_python.prompt, prompts/b_python.prompt -->
If metadata is missing, validation runs against the full prompt set and auto-caches detected prompt links into the story file for future deterministic runs. Environment variable overrides:
VariableDefaultDescription
PDD_USER_STORIES_DIRuser_storiesStories directory
PDD_PROMPTS_DIRpromptsPrompts directory

​
Examples

# Detect which prompts are affected by a change description
pdd detect \
  --output detect_results.csv \
  factorial_calculator_python.prompt \
  data_processing_python.prompt \
  web_scraper_python.prompt \
  changes_description.prompt

# Pipe results into pdd change for batch application
pdd change --manual --csv detect_results.csv src/

# Run all user story validations
pdd detect --stories

# Run stories from a custom directory
pdd detect --stories --stories-dir tests/stories --prompts-dir src/prompts

# Run all stories even if one fails
pdd detect --stories --no-fail-fast

​
Relationship with pdd change

pdd change calls pdd detect --stories automatically after modifying prompts to verify that no existing user stories are broken by the changes. If any story fails, pdd change will fail and report which stories need attention.
  • pdd change — Uses detect internally and can consume the CSV output via --csv.
  • pdd conflicts — Produces the same CSV format for a different analysis (prompt-vs-prompt conflicts).

Build docs developers (and LLMs) love

Get started for freeTalk to us