pdd-cli 0.0.90__py3-none-any.whl → 0.0.118__py3-none-any.whl

pdd/prompts/agentic_update_LLM.prompt

@@ -1,6 +1,7 @@
 % You are an expert PDD (Prompt-Driven Development) engineer. Your task is to update a prompt file to reflect code changes while making it as compact as possible.
 
 % Prompting Guide (follow these best practices):
+<pdd_prompting_guide>
 # Prompt‑Driven Development Prompting Guide
 
 This guide shows how to write effective prompts for Prompt‑Driven Development (PDD). It distills best practices from the PDD whitepaper, the PDD doctrine, and working patterns in this repo. It also contrasts PDD prompts with interactive agentic coding tools (e.g., Claude Code, Cursor) where prompts act as ad‑hoc patches instead of the source of truth.
@@ -15,19 +16,21 @@ If you are new to Prompt-Driven Development (PDD), follow this recipe:
 
 1.  **Think "One Prompt = One Module":** Don't try to generate the whole app at once. Focus on one file (e.g., `user_service.py`).
 2.  **Use a Template:** Start with a clear structure: Role, Requirements, Dependencies, Instructions.
-3.  **Explicitly Include Context:** Use `[File not found: path/to/file]` to give the model *only* what it needs (e.g., a shared preamble or a dependency interface). This is a **PDD directive**, not just XML.
+3.  **Explicitly Include Context:** Use `<include>path/to/file</include>` to give the model *only* what it needs (e.g., a shared preamble or a dependency interface). This is a **PDD directive**, not just XML.
 4.  **Regenerate, Don't Patch:** If the code is wrong, fix it using `pdd fix`. This updates the system's memory so the next `pdd generate` is grounded in the correct solution.
 5.  **Verify:** Run the generated code/tests.
 
 *Tip: Treat your prompt like source code. It is the single source of truth.*
 
+*For the conceptual foundation of why this works, see [The Mold Paradigm](prompt-driven-development-doctrine.md#the-mold-paradigm) in the doctrine.*
+
 ---
 
 ## Glossary
 
 - **Context Engineering:** The art of curating exactly what information (code, docs, examples) fits into the LLM's limited "working memory" (context window) to get the best result.
 - **Shared Preamble:** A standard text file (e.g., `project_preamble.prompt`) included in every prompt to enforce common rules like coding style, forbidden libraries, and formatting.
-- **PDD Directive:** Special tags like `[Error processing include: ` or `Error: Command '` that the PDD tool processes *before* sending the text to the AI. The AI sees the *result* (the file content), not the tag.
+- **PDD Directive:** Special tags like `<include>` or `<shell>` that the PDD tool processes *before* sending the text to the AI. The AI sees the *result* (the file content), not the tag.
 - **Source of Truth:** The definitive record. In PDD, the **Prompt** is the source of truth; the code is just a temporary artifact generated from it.
 - **Grounding (Few-Shot History):** The process where the PDD system automatically uses successful past pairs of (Prompt, Code) as "few-shot" examples during generation. This ensures that regenerated code adheres to the established style and logic of the previous version, preventing the model from hallucinating a completely different implementation.
 - **Drift:** When the generated code slowly diverges from the prompt's intent over time, or when manual edits to code make it inconsistent with the prompt.
@@ -43,6 +46,8 @@ If you are new to Prompt-Driven Development (PDD), follow this recipe:
 
 Contrast with interactive patching (Claude Code, Cursor): prompts are ephemeral instructions for local diffs. They are great for short, local fixes, but tend to drift from original intent as context is implicit and often lost. In PDD, prompts are versioned, explicit, and designed for batch, reproducible generation.
 
+For a deeper exploration of why this paradigm shift matters—and an analogy to manufacturing's wood‑to‑plastic transition—see [The Mold Paradigm](prompt-driven-development-doctrine.md#the-mold-paradigm) in the doctrine.
+
 ---
 
 ## The PDD Mental Model
@@ -74,6 +79,7 @@ Notes:
 
 ---
 
+<a name="automated-grounding"></a>
 ## Automated Grounding (PDD Cloud)
 
 Unlike standard LLM interactions where every request is a blank slate, PDD Cloud uses **Automated Grounding** to prevent "implementation drift."
@@ -172,17 +178,16 @@ These patterns are used across prompts in this repo:
 
 - Preamble and role: start with a concise, authoritative description of the task and audience (e.g., “You are an expert Python engineer…”).
 - Includes for context: bring only what the model needs.
-  - Single include: `<include>path/to/file]`. **Note:** This is a PDD directive, not standard XML. The PDD tool replaces this tag with the actual file content *before* the LLM sees it. (Handles both text and images).
-  - Multiple: `[File not found: path1]
-[File not found: path2]
-[File not found: …]`
+  - Single include: `<include>path/to/file</include>`. **Note:** This is a PDD directive, not standard XML. The PDD tool replaces this tag with the actual file content *before* the LLM sees it. (Handles both text and images).
+  - Multiple: `<include-many>path1, path2, …</include-many>`
   - Grouping: wrap includes in a semantic tag to name the dependency or file they represent, for example:
     ```xml
     <render_js>
-      [File not found: src/render.js]
+      <include>src/render.js</include>
     </render_js>
     ```
   - When including larger files inline for clarity, wrap with opening/closing tags named after the file, e.g. `<render.js>…</render.js>`.
+  - Note: `<include>`, `<include-many>`, `<shell>`, and `<web>` inside fenced code blocks (``` or ~~~) or inline backticks are treated as literal text.
 - Inputs/outputs: state them explicitly (names, types, shapes). Prompts should define Inputs/Outputs and steps clearly.
 - Steps & Chain of Thought: Outline a short, deterministic plan. For complex logical tasks, explicitly instruct the model to "Analyze the requirements and think step-by-step before writing code." This improves accuracy on difficult reasoning problems.
 - Constraints: specify style, performance targets, security, and error handling.
@@ -192,360 +197,205 @@ Tip: Prefer small, named sections using XML‑style tags to make context scannab
 
 ### Special XML Tags: pdd, shell, web
 
-The PDD preprocessor supports additional XML‑style tags to keep prompts clean, reproducible, and self‑contained. Processing order (per spec) is: `pdd` → `include`/`include-many` → `shell` → `web`. When `recursive=True`, `<shell>` and `[Web scraping error: Unexpected error during scrape URL: Status code 400. Bad Request - [{'code': 'invalid_format', 'format': 'url', 'path': ['url'], 'message': 'Invalid URL'}, {'code': 'custom', 'path': ['url'], 'message': 'URL must have a valid top-level domain or be a valid path'}, {'code': 'custom', 'path': ['url'], 'message': 'Invalid URL'}]]`
-  - Purpose: fetch the page (via Firecrawl) and inline the markdown content.
-  - Behavior: executes during non‑recursive preprocessing; on failure, inserts a bracketed error note.
-  - Example: `[Skip to main content](https://docs.litellm.ai/docs/completion/json_mode#__docusaurus_skipToContent_fallback)
-
-On this page
-
-## Quick Start [​](https://docs.litellm.ai/docs/completion/json_mode\#quick-start "Direct link to Quick Start")
-
-- SDK
-- PROXY
-
-```python
-from litellm import completion
-import os
-
-os.environ["OPENAI_API_KEY"] = ""
-
-response = completion(
-  model="gpt-4o-mini",
-  response_format={ "type": "json_object" },
-  messages=[\
-    {"role": "system", "content": "You are a helpful assistant designed to output JSON."},\
-    {"role": "user", "content": "Who won the world series in 2020?"}\
-  ]
-)
-print(response.choices[0].message.content)
-```
-
-```bash
-curl http://0.0.0.0:4000/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $LITELLM_KEY" \
-  -d '{
-    "model": "gpt-4o-mini",
-    "response_format": { "type": "json_object" },
-    "messages": [\
-      {\
-        "role": "system",\
-        "content": "You are a helpful assistant designed to output JSON."\
-      },\
-      {\
-        "role": "user",\
-        "content": "Who won the world series in 2020?"\
-      }\
-    ]
-  }'
-```
-
-## Check Model Support [​](https://docs.litellm.ai/docs/completion/json_mode\#check-model-support "Direct link to Check Model Support")
-
-### 1\. Check if model supports `response_format` [​](https://docs.litellm.ai/docs/completion/json_mode\#1-check-if-model-supports-response_format "Direct link to 1-check-if-model-supports-response_format")
-
-Call `litellm.get_supported_openai_params` to check if a model/provider supports `response_format`.
-
-```python
-from litellm import get_supported_openai_params
-
-params = get_supported_openai_params(model="anthropic.claude-3", custom_llm_provider="bedrock")
-
-assert "response_format" in params
-```
-
-### 2\. Check if model supports `json_schema` [​](https://docs.litellm.ai/docs/completion/json_mode\#2-check-if-model-supports-json_schema "Direct link to 2-check-if-model-supports-json_schema")
-
-This is used to check if you can pass
-
-- `response_format={ "type": "json_schema", "json_schema": … , "strict": true }`
-- `response_format=<Pydantic Model>`
-
-```python
-from litellm import supports_response_schema
-
-assert supports_response_schema(model="gemini-1.5-pro-preview-0215", custom_llm_provider="bedrock")
-```
+The PDD preprocessor supports additional XML‑style tags to keep prompts clean, reproducible, and self‑contained. Processing order (per spec) is: `pdd` → `include`/`include-many` → `shell` → `web`. When `recursive=True`, `<shell>` and `<web>` are deferred until a non‑recursive pass.
 
-Check out [model\_prices\_and\_context\_window.json](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) for a full list of models and their support for `response_schema`.
-
-## Pass in 'json\_schema' [​](https://docs.litellm.ai/docs/completion/json_mode\#pass-in-json_schema "Direct link to Pass in 'json_schema'")
-
-To use Structured Outputs, simply specify
-
-```text
-response_format: { "type": "json_schema", "json_schema": … , "strict": true }
-```
+- `<pdd>…</pdd>`
+  - Purpose: human‑only comment. Removed entirely during preprocessing.
+  - Use: inline rationale or notes that should not reach the model.
+  - Example: `Before step X <pdd>explain why we do this here</pdd>`
 
-Works for:
+- `<shell>…</shell>`
+  - Purpose: run a shell command and inline stdout at that position.
+  - Behavior: executes during non‑recursive preprocessing; on non‑zero exit, inserts a bracketed error with the exit code instead of failing the pipeline.
+  - Example: `<shell>git config --get user.name</shell>`
 
-- OpenAI models
-- Azure OpenAI models
-- xAI models (Grok-2 or later)
-- Google AI Studio - Gemini models
-- Vertex AI models (Gemini + Anthropic)
-- Bedrock Models
-- Anthropic API Models
-- Groq Models
-- Ollama Models
-- Databricks Models
-
-- SDK
-- PROXY
-
-```python
-import os
-from litellm import completion
-from pydantic import BaseModel
+- `<web>URL</web>`
+  - Purpose: fetch the page (via Firecrawl) and inline the markdown content.
+  - Behavior: executes during non‑recursive preprocessing; on failure, inserts a bracketed error note.
+  - Example: `<web>https://docs.litellm.ai/docs/completion/json_mode</web>`
 
-# add to env var
-os.environ["OPENAI_API_KEY"] = ""
+> ⚠️ **Warning: Non-Deterministic Tags**
+>
+> `<shell>` and `<web>` introduce **non-determinism**:
+> - `<shell>` output varies by environment (different machines, different results)
+> - `<web>` content changes over time (same URL, different content)
+>
+> **Impact:** Same prompt file → different generations on different machines/times
+>
+> **Prefer instead:** Capture output to a static file, then `<include>` that file. This ensures reproducible regeneration.
 
-messages = [{"role": "user", "content": "List 5 important events in the XIX century"}]
+Use these tags sparingly. When you must use them, prefer stable commands with bounded output (e.g., `head -n 20` in `<shell>`).
 
-class CalendarEvent(BaseModel):
-  name: str
-  date: str
-  participants: list[str]
+---
 
-class EventsList(BaseModel):
-    events: list[CalendarEvent]
+## Architecture Metadata Tags
 
-resp = completion(
-    model="gpt-4o-2024-08-06",
-    messages=messages,
-    response_format=EventsList
-)
+PDD prompts can include optional XML metadata tags that sync with `architecture.json`. These tags enable bidirectional sync between prompt files and the architecture visualization, keeping your project's architecture documentation automatically up-to-date.
 
-print("Received={}".format(resp))
+### Tag Format
 
-events_list = EventsList.model_validate_json(resp.choices[0].message.content)
-```
+Place architecture metadata tags at the **top of your prompt file** (after any `<include>` directives but before the main content):
 
-1. Add openai model to config.yaml
+```xml
+<pdd-reason>Brief description of module's purpose (60-120 chars)</pdd-reason>
+
+<pdd-interface>
+{{
+  "type": "module",
+  "module": {{
+    "functions": [
+      {{"name": "function_name", "signature": "(...)", "returns": "Type"}}
+    ]
+  }}
+}}
+</pdd-interface>
 
-```yaml
-model_list:
-  - model_name: "gpt-4o"
-    litellm_params:
-      model: "gpt-4o-2024-08-06"
+<pdd-dependency>dependency_prompt_1.prompt</pdd-dependency>
+<pdd-dependency>dependency_prompt_2.prompt</pdd-dependency>
 ```
 
-2. Start proxy with config.yaml
-
-```bash
-litellm --config /path/to/config.yaml
+### Tag Reference
+
+**`<pdd-reason>`**
+- **Purpose**: One-line description of why this module exists
+- **Maps to**: `architecture.json["reason"]`
+- **Format**: Single line string (recommended 60-120 characters)
+- **Example**: `<pdd-reason>Provides unified LLM invocation across all PDD operations.</pdd-reason>`
+
+**`<pdd-interface>`**
+- **Purpose**: JSON describing the module's public API (functions, commands, pages)
+- **Maps to**: `architecture.json["interface"]`
+- **Format**: Valid JSON matching one of four interface types (see below)
+- **Example**:
+  ```xml
+  <pdd-interface>
+  {{
+    "type": "module",
+    "module": {{
+      "functions": [
+        {{"name": "llm_invoke", "signature": "(prompt, strength, ...)", "returns": "Dict"}}
+      ]
+    }}
+  }}
+  </pdd-interface>
+  ```
+
+**`<pdd-dependency>`**
+- **Purpose**: References other prompt files this module depends on
+- **Maps to**: `architecture.json["dependencies"]` array
+- **Format**: Prompt filename (e.g., `llm_invoke_python.prompt`)
+- **Multiple tags**: Use one `<pdd-dependency>` tag per dependency
+- **Example**:
+  ```xml
+  <pdd-dependency>llm_invoke_python.prompt</pdd-dependency>
+  <pdd-dependency>path_resolution_python.prompt</pdd-dependency>
+  ```
+
+### Interface Types
+
+The `<pdd-interface>` tag supports four interface types, matching the architecture.json schema:
+
+**Module Interface** (Python modules with functions):
+```json
+{{
+  "type": "module",
+  "module": {{
+    "functions": [
+      {{"name": "func_name", "signature": "(arg1, arg2)", "returns": "Type"}}
+    ]
+  }}
+}}
 ```
 
-3. Call with OpenAI SDK / Curl!
-
-Just replace the 'base\_url' in the openai sdk, to call the proxy with 'json\_schema' for openai models
-
-**OpenAI SDK**
-
-```python
-from pydantic import BaseModel
-from openai import OpenAI
-
-client = OpenAI(
-    api_key="anything", # 👈 PROXY KEY (can be anything, if master_key not set)
-    base_url="http://0.0.0.0:4000" # 👈 PROXY BASE URL
-)
-
-class Step(BaseModel):
-    explanation: str
-    output: str
-
-class MathReasoning(BaseModel):
-    steps: list[Step]
-    final_answer: str
-
-completion = client.beta.chat.completions.parse(
-    model="gpt-4o",
-    messages=[\
-        {"role": "system", "content": "You are a helpful math tutor. Guide the user through the solution step by step."},\
-        {"role": "user", "content": "how can I solve 8x + 7 = -23"}\
-    ],
-    response_format=MathReasoning,
-)
-
-math_reasoning = completion.choices[0].message.parsed
+**CLI Interface** (Command-line interfaces):
+```json
+{{
+  "type": "cli",
+  "cli": {{
+    "commands": [
+      {{"name": "cmd_name", "description": "What it does"}}
+    ]
+  }}
+}}
 ```
 
-**Curl**
-
-```bash
-curl -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer sk-1234' \
--d '{
-    "model": "gpt-4o",
-    "messages": [\
-      {\
-        "role": "system",\
-        "content": "You are a helpful math tutor. Guide the user through the solution step by step."\
-      },\
-      {\
-        "role": "user",\
-        "content": "how can I solve 8x + 7 = -23"\
-      }\
-    ],
-    "response_format": {
-      "type": "json_schema",
-      "json_schema": {
-        "name": "math_reasoning",
-        "schema": {
-          "type": "object",
-          "properties": {
-            "steps": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "explanation": { "type": "string" },
-                  "output": { "type": "string" }
-                },
-                "required": ["explanation", "output"],
-                "additionalProperties": false
-              }
-            },
-            "final_answer": { "type": "string" }
-          },
-          "required": ["steps", "final_answer"],
-          "additionalProperties": false
-        },
-        "strict": true
-      }
-    }
-  }'
+**Command Interface** (PDD commands):
+```json
+{{
+  "type": "command",
+  "command": {{
+    "commands": [
+      {{"name": "cmd_name", "description": "What it does"}}
+    ]
+  }}
+}}
 ```
 
-## Validate JSON Schema [​](https://docs.litellm.ai/docs/completion/json_mode\#validate-json-schema "Direct link to Validate JSON Schema")
-
-Not all vertex models support passing the json\_schema to them (e.g. `gemini-1.5-flash`). To solve this, LiteLLM supports client-side validation of the json schema.
-
-```text
-litellm.enable_json_schema_validation=True
+**Frontend Interface** (UI pages):
+```json
+{{
+  "type": "frontend",
+  "frontend": {{
+    "pages": [
+      {{"name": "page_name", "route": "/path"}}
+    ]
+  }}
+}}
 ```
 
-If `litellm.enable_json_schema_validation=True` is set, LiteLLM will validate the json response using `jsonvalidator`.
-
-[**See Code**](https://github.com/BerriAI/litellm/blob/671d8ac496b6229970c7f2a3bdedd6cb84f0746b/litellm/litellm_core_utils/json_validation_rule.py#L4)
-
-- SDK
-- PROXY
-
-```python
-# !gcloud auth application-default login - run this to add vertex credentials to your env
-import litellm, os
-from litellm import completion
-from pydantic import BaseModel
+### Sync Workflow
 
-messages=[\
-        {"role": "system", "content": "Extract the event information."},\
-        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},\
-    ]
+1. **Add/edit tags** in your prompt files using the format above
+2. **Click "Sync from Prompt"** in the PDD Connect Architecture page (or call the API endpoint)
+3. **Tags automatically update** `architecture.json` with your changes
+4. **Architecture visualization** reflects the updated dependencies and interfaces
 
-litellm.enable_json_schema_validation = True
-litellm.set_verbose = True # see the raw request made by litellm
+Prompts are the **source of truth** - tags in prompt files override what's in `architecture.json`. This aligns with PDD's core philosophy that prompts, not code or documentation, are authoritative.
 
-class CalendarEvent(BaseModel):
-  name: str
-  date: str
-  participants: list[str]
+### Validation
 
-resp = completion(
-    model="gemini/gemini-1.5-pro",
-    messages=messages,
-    response_format=CalendarEvent,
-)
+Validation is **lenient**:
+- Missing tags are OK - only fields with tags get updated
+- Malformed XML/JSON is skipped without blocking sync
+- Circular dependencies are detected and prevent invalid updates
+- Missing dependency files generate warnings but don't block sync
 
-print("Received={}".format(resp))
-```
+### Best Practices
 
-1. Create config.yaml
+**Keep `<pdd-reason>` concise** (60-120 chars)
+- Good: "Provides unified LLM invocation across all PDD operations."
+- Too long: "This module exists because we needed a way to call different LLM providers through a unified interface that supports both streaming and non-streaming modes while also handling rate limiting and retry logic..."
 
-```yaml
-model_list:
-  - model_name: "gemini-1.5-flash"
-    litellm_params:
-      model: "gemini/gemini-1.5-flash"
-      api_key: os.environ/GEMINI_API_KEY
+**Use prompt filenames for dependencies**, not module names
+- Correct: `<pdd-dependency>llm_invoke_python.prompt</pdd-dependency>`
+- Wrong: `<pdd-dependency>pdd.llm_invoke</pdd-dependency>`
+- Wrong: `<pdd-dependency>context/example.py</pdd-dependency>`
 
-litellm_settings:
-  enable_json_schema_validation: True
-```
+**Validate interface JSON before committing**
+- Use a JSON validator to check syntax
+- Ensure `type` field matches one of: `module`, `cli`, `command`, `frontend`
+- Include required nested keys (`functions`, `commands`, or `pages`)
 
-2. Start proxy
-
-```bash
-litellm --config /path/to/config.yaml
-```
+**Run "Sync All" after bulk prompt updates**
+- If you've edited multiple prompts, sync all at once
+- Review the validation results for circular dependencies
+- Fix any warnings before committing changes
 
-3. Test it!
-
-```bash
-curl http://0.0.0.0:4000/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $LITELLM_API_KEY" \
-  -d '{
-    "model": "gemini-1.5-flash",
-    "messages": [\
-        {"role": "system", "content": "Extract the event information."},\
-        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},\
-    ],
-    "response_format": {
-        "type": "json_schema",
-        "json_schema": {
-          "name": "math_reasoning",
-          "schema": {
-            "type": "object",
-            "properties": {
-              "steps": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "properties": {
-                    "explanation": { "type": "string" },
-                    "output": { "type": "string" }
-                  },
-                  "required": ["explanation", "output"],
-                  "additionalProperties": false
-                }
-              },
-              "final_answer": { "type": "string" }
-            },
-            "required": ["steps", "final_answer"],
-            "additionalProperties": false
-          },
-          "strict": true
-        }
-    },
-  }'
-```
+### Relationship to Other Tags
 
-- [Quick Start](https://docs.litellm.ai/docs/completion/json_mode#quick-start)
-- [Check Model Support](https://docs.litellm.ai/docs/completion/json_mode#check-model-support)
-  - [1\. Check if model supports `response_format`](https://docs.litellm.ai/docs/completion/json_mode#1-check-if-model-supports-response_format)
-  - [2\. Check if model supports `json_schema`](https://docs.litellm.ai/docs/completion/json_mode#2-check-if-model-supports-json_schema)
-- [Pass in 'json\_schema'](https://docs.litellm.ai/docs/completion/json_mode#pass-in-json_schema)
-- [Validate JSON Schema](https://docs.litellm.ai/docs/completion/json_mode#validate-json-schema)
+**`<pdd-dependency>` vs `<include>`**:
+- `<pdd-dependency>`: Declares architectural dependency (updates `architecture.json`)
+- `<include>`: Injects content into prompt for LLM context (does NOT affect architecture)
+- Use both when appropriate - they serve different purposes
 
-Ask AI
-![Chat avatar](https://docs.litellm.ai/img/favicon.ico)`
+**`<pdd-*>` tags vs `<pdd>` comments**:
+- `<pdd-reason>`, `<pdd-interface>`, `<pdd-dependency>`: Metadata tags (processed by sync tool)
+- `<pdd>...</pdd>`: Human-only comments (removed by preprocessor, never reach LLM)
+- Both are valid PDD directives with different purposes
 
-> ⚠️ **Warning: Non-Deterministic Tags**
->
-> `<shell>` and `<web>` introduce **non-determinism**:
-> - `<shell>` output varies by environment (different machines, different results)
-> - `<web>` content changes over time (same URL, different content)
->
-> **Impact:** Same prompt file → different generations on different machines/times
->
-> **Prefer instead:** Capture output to a static file, then `[Error processing include: ` that file. This ensures reproducible regeneration.
+### Example: Complete Prompt with Metadata Tags
 
-Use these tags sparingly. When you must use them, prefer stable commands with bounded output (e.g., `head -n 20` in `<shell>`).
+See `docs/examples/prompt_with_metadata.prompt` for a full example showing all three metadata tags in context.
 
 ---
 
@@ -553,11 +403,11 @@ Use these tags sparingly. When you must use them, prefer stable commands with bo
 
 ### Shared Preamble for Consistency
 
-Use a shared include (e.g., `<include>context/project_preamble.prompt]`) at the top of every prompt. You should create this file in your project's `context/` directory to define your "Constitution": consistent coding style (e.g., indentation, naming conventions), preferred linting rules, and forbidden libraries. This ensures all generated code speaks the same language without cluttering individual prompts.
+Use a shared include (e.g., `<include>context/project_preamble.prompt</include>`) at the top of every prompt. You should create this file in your project's `context/` directory to define your "Constitution": consistent coding style (e.g., indentation, naming conventions), preferred linting rules, and forbidden libraries. This ensures all generated code speaks the same language without cluttering individual prompts.
 
 ### Automatic Update Propagation via Includes
 
-A key benefit of `[Error processing include: ` directives is **automatic propagation**: when the included file changes, all prompts that reference it automatically reflect those changes on the next generation—without editing the prompts themselves.
+A key benefit of `<include>` directives is **automatic propagation**: when the included file changes, all prompts that reference it automatically reflect those changes on the next generation—without editing the prompts themselves.
 
 Use this pattern when:
 - **Authoritative documentation exists elsewhere** (e.g., a README that defines environment variables, API contracts, or configuration options). Include it rather than duplicating the content.
@@ -687,7 +537,7 @@ This simplified example illustrates a minimal functional prompt:
 ```text
 % You are an expert Python engineer. Your goal is to write a function `get_extension` that returns the file extension for a given language.
 
-<include>context/python_preamble.prompt]
+<include>context/python_preamble.prompt</include>
 
 % Inputs/Outputs
   Input: language (str), like "Python" or "Makefile".
@@ -706,7 +556,7 @@ This simplified example illustrates a minimal functional prompt:
 This style:
 - Declares role and outcome
 - Specifies IO, data sources, and steps
-- Uses an `[Error processing include: ` to pull a shared preamble
+- Uses an `<include>` to pull a shared preamble
 
 ---
 
@@ -809,7 +659,7 @@ Include dependencies explicitly when:
 
 ```xml
 <billing_service>
-  <include>context/billing_service_example.py]
+  <include>context/billing_service_example.py</include>
 </billing_service>
 ```
 
@@ -817,7 +667,7 @@ Include dependencies explicitly when:
 
 If you've successfully generated code that uses a dependency before, grounding often suffices—the usage pattern is already in the cloud database.
 
-**Prefer explicit `[Error processing include: ` for:** External APIs, critical contracts, cross-team interfaces
+**Prefer explicit `<include>` for:** External APIs, critical contracts, cross-team interfaces
 **Rely on grounding for:** Internal modules with established patterns
 
 ### Token Efficiency
@@ -932,9 +782,9 @@ Constraints:
 - Output a unified diff only
 
 Snippet:
-  export function parseUserId(input: string) {
+  export function parseUserId(input: string) {{
     return input.trim().split(":")[1];
-  }
+  }}
 ```
 
 PDD‑style prompt (source of truth):
@@ -956,7 +806,7 @@ PDD‑style prompt (source of truth):
 
 % Dependencies
   <logger>
-    <include>context/logger_example.ts]
+    <include>context/logger_example.ts</include>
   </logger>
 
 % Instructions
@@ -1007,7 +857,7 @@ Key differences:
 
 ## Naming & Conventions (This Repo)
 
-- One prompt per module/file, named like `${BASENAME}_${LanguageOrFramework}.prompt` (see templates under `pdd/pdd/templates`).
+- One prompt per module/file, named like `${{BASENAME}}_${{LanguageOrFramework}}.prompt` (see templates under `pdd/pdd/templates`).
 - Follow codebase conventions from README.md for Python and TypeScript style.
 - Use curated examples under `context/` to encode interfaces and behaviors.
 
@@ -1017,6 +867,7 @@ Key differences:
 
 Think of prompts as your programming language. Keep them concise, explicit, and modular. Regenerate instead of patching, verify behavior with accumulating tests, and continuously back‑propagate implementation learnings into your prompts. That discipline is what converts maintenance from an endless patchwork into a compounding system of leverage.
 
+</pdd_prompting_guide>
 
 % Files to Read
 
@@ -1026,8 +877,11 @@ Think of prompts as your programming language. Keep them concise, explicit, and
 2. **Code file (modified)**: {code_path}
    - This contains the user's modifications that the prompt needs to capture
 
-3. **Test files** (if any exist): {test_paths}
-   - Read ALL test files listed above
+3. **Test files**: {test_paths}
+   - If tests are listed above, read ALL of them
+   - If "No tests were found", search for test files yourself:
+     - Look for files named `test_<module>*.py` in sibling `tests/` directory (../tests/)
+     - Check common locations: `tests/`, `__tests__/`, `test/`
    - Behaviors verified by tests DON'T need to be explicitly specified in the prompt
    - Tests accumulate across numbered files (test_module.py, test_module_1.py, etc.)
 
@@ -1066,6 +920,6 @@ Think of prompts as your programming language. Keep them concise, explicit, and
 
 Write the updated prompt directly to: {prompt_path}
 
-If you create new shared include files, write them to the `context/` directory.
+If you create new shared include files, write them to the `context/` or equivalent directory. It may be different for different projects so you might need to explore the project to find the correct directory.
 
 If the prompt is already optimal, you may leave it unchanged.