prompt-engineering-patterns-v2

# Advanced Prompt Engineering Techniques Implements advanced individual prompt design techniques — zero-shot/one-shot construction, verb-based instruction engineering, structured output formatting, and evaluation rubrics — to maximize LLM response quality, consistency, and reliability for single-prompt tasks. When loaded, this skill makes the model act as a senior prompt architect, analyzing any raw prompt and producing an optimized version using evidence-based design patterns from Agentic Design Patterns (Gulli, Appendix A). > **Distinct boundary:** This skill focuses on how to write a *single* prompt effectively — verb selection, example curation, output format specification, and iterative refinement. It does NOT address chaining multiple prompts into pipelines; use `prompt-chaining` for workflow composition. ## TL;DR Checklist - [ ] Prompt opens with a strong action verb or clear role assignment — no vague introductory phrases - [ ] Output format is explicitly declared (JSON schema, XML tags, or constrained template) before any task instructions - [ ] Examples follow the `input → expected_output` pattern with realistic, non-trivial data - [ ] Zero-shot prompts include all context, constraints, and format specifications in a single self-contained block - [ ] Few-shot example selection uses maximum diversity (not repetition) and covers edge cases explicitly - [ ] Evaluation rubric has ≥ 3 scoring dimensions when peer-review simulation is required - [ ] Prompt avoids ambiguous directives like "be helpful" or "do your best" — every instruction uses a strong action verb --- ## When to Use Use this skill when: - Designing a new prompt from scratch and you want evidence-based structure rather than trial-and-error - Refactoring an existing prompt that produces inconsistent, verbose, or poorly formatted outputs - You need the LLM to produce machine-parsable structured output (JSON, XML, constrained templates) for downstream programmatic processing - Building evaluation systems where multiple LLM-generated responses need objective scoring against defined rubrics - Converting ambiguous user requests into precise, verb-driven instructions that reduce hallucination surface area - Implementing one-shot or few-shot demonstrations where example selection critically affects output quality --- ## When NOT to Use Avoid this skill for: - **Multi-step workflow design** — Use `prompt-chaining` when you need sequential pipelines with intermediate outputs and handoffs between prompts - **System-level architecture planning** — Use a strategic/strategic-design skill; this skill is operational, not architectural - **Brainstorming or ideation sessions** — Vague exploratory queries don't benefit from structured prompt engineering; they require divergent thinking patterns instead - **Simple Q&A with no format requirements** — If you just ask "what is Python?" there is no structural optimization to apply; keep it trivial --- ## Core Workflow 1. **Classify the Prompt Intent** — Determine whether the raw prompt is zero-shot (instruction-only), one-shot (instruction + single example), few-shot (instruction + multiple examples), or an evaluation rubric task. Extract the core objective, required output format, and any implicit constraints. **Checkpoint:** Label intent type and list extracted components (objective, format, constraints) before proceeding to design. 2. **Apply Verb-Based Instruction Redesign** — Replace every weak directive ("describe," "give me," "try to") with a strong action verb from the selection guide (e.g., `extract`, `classify`, `transform`, `validate`, `summarize`). Rewrite each instruction as an imperative sentence in the form: `[Action Verb] + [Target Object] + [Constraint/Format]`. **Checkpoint:** Every instruction sentence begins with a verified strong action verb; zero sentences begin with "try," "maybe," or vague modifiers. 3. **Design Output Format Specification** — If structured output is needed, define a JSON schema (with `type`, `properties`, `required`), XML tag structure, or constrained template before the task instructions. Place format declaration at the top of the prompt block so the model sees it first. Include an example of valid output within the format specification. **Checkpoint:** A human parser can validate any output against the declared format without reading the full prompt text again. 4. **Construct Example Demonstrations** — For one-shot/few-shot prompts, select 2–5 examples that cover: (a) the canonical use case, (b) at least one edge case, and (c) a negative or adversarial case where the expected output demonstrates correct rejection behavior. Order examples from simple to complex. Each example must be an `input → expected_output` pair — never provide only input without showing the correct output. **Checkpoint:** Example diversity score ≥ 0.6 (measured by unique patterns covered); no two examples test the same edge condition. 5. **Add Evaluation Rubric (if applicable)** — For tasks requiring quality assessment or peer-review simulation, define 3+ scoring dimensions with explicit criteria per dimension. Each dimension needs: a name, a 1–2 sentence description, a numeric scale (e.g., 1–5), and concrete anchor descriptions for at least the minimum (1) and maximum (5) scores. Include a total score aggregation rule. **Checkpoint:** An unbiased third party can score two independently generated responses and arrive at the same scores using only the rubric — no additional context needed. 6. **Validate Against Design Principles** — Run the final prompt through the constraint checklist: verify every instruction uses a strong verb, output format is declared before instructions, examples are diverse and ordered correctly, and no ambiguous directives remain. Compare against the BAD pattern set from Implementation Patterns to catch common failure modes. **Checkpoint:** All 8 MUST DO constraints pass; all 6 MUST NOT DO anti-patterns are absent. --- ## Implementation Patterns ### Pattern 1: Zero-Shot Prompt Design Framework A zero-shot prompt relies entirely on the model's pretraining — no examples are provided. The design must compensate by being maximally explicit in role assignment, context, constraints, and output format. This pattern provides a structured template that reduces hallucination and improves consistency. **Design principles from Gulli (Appendix A):** Zero-shot prompts should use imperative language, declare the output structure upfront, and include negative constraints ("do not") alongside positive ones. The model's pretraining is leveraged by giving it precise instructions rather than examples. ```python from dataclasses import dataclass, field from typing import Optional @dataclass class ZeroShotPrompt: """A zero-shot prompt with structured role, task, constraints, and format.""" role: str task: str context: Optional[str] = None constraints: list[str] = field(default_factory=list) output_format: str = "" negative_constraints: list[str] = field(default_factory=list) def render(self) -> str: """Render the zero-shot prompt as a single text block. Assembles role, context, task, constraints, format specification, and negative constraints into a cohesive prompt following the evidence-based structure from Agentic Design Patterns. Returns: A string ready to be sent to an LLM API. """ parts = [f"### ROLE\n{self.role}"] if self.context: parts.append(f"\n### CONTEXT\n{self.context}") parts.append(f"\n### TASK\n{self.task}") if self.constraints: constraint_text = "\n".join(f"- {c}" for c in self.constraints) parts.append(f"\n### CONSTRAINTS\n{constraint_text}") if self.output_format: parts.append(f"\n### OUTPUT FORMAT\n{self.output_format}") if self.negative_constraints: neg_text = "\n".join(f"- DO NOT {c}" for c in self.negative_constraints) parts.append(f"\n### RESTRICTIONS\n{neg_text}") return "\n".join(parts) def build_zero_shot_prompt( role: str, task: str, context: Optional[str] = None, output_format: str = "", constraints: Optional[list[str]] = None, negative_constraints: Optional[list[str]] = None, ) -> ZeroShotPrompt: """Construct a zero-shot prompt following the structured template. Implements Early Exit (Law 1) by validating required arguments first. Returns a ready-to-use ZeroShotPrompt object. Args: role: The persona or expertise the model should adopt. task: The primary instruction using a strong action verb. context: Optional background information to ground the response. output_format: Declared output format (JSON schema, XML template, etc.). constraints: List of positive constraints the response must satisfy. negative_constraints: List of behaviors the response must avoid. Returns: A ZeroShotPrompt instance ready for .render(). Raises: ValueError: If role or task is empty. """ if not role or not isinstance(role, str): raise ValueError("role is required and must be a non-empty string") if not task or not isinstance(task, str): raise ValueError("task is required and must be a non-empty string") return ZeroShotPrompt( role=role.strip(), task=task.strip(), context=context.strip() if context else None, constraints=constraints or [], output_format=output_format.strip() if output_format else "", negative_constraints=negative_constraints or [], ) ``` **BAD vs GOOD comparison:** ```python # ❌ BAD: Vague zero-shot prompt — relies on implicit understanding """ Can you help me with these documents? I need you to look at them and tell me what they're about. Maybe summarize the key points? Be helpful and try to give a good answer. Format it however seems reasonable. """ # Problems: "help me" (weak verb), "tell me" (passive), "maybe summarize" # (hedging), "good answer" (undefined quality), "format however seems # reasonable" (no format specification). The model has 100 degrees of # freedom — most outputs will be inconsistent. # ✅ GOOD: Structured zero-shot prompt — explicit role, verb-driven task, declared format prompt = build_zero_shot_prompt( role="You are a technical document analyst specializing in extracting structured information from engineering reports.", context="The documents are internal incident post-mortem reports from a cloud infrastructure team.", task="Extract and classify all incidents described in the provided text by severity level, root cause category, and resolution status.", output_format=""" Return JSON with this exact schema: { "incidents": [ { "incident_id": "<string>", "severity": "<critical|high|medium|low>", "root_cause_category": "<string>", "resolution_status": "<resolved|mitigated|open>", "affected_services": ["<string>"], "summary": "<one-sentence summary>" } ], "total_count": <int> } """, constraints=[ "Classify each incident into exactly one severity level from the defined set.", "If root cause is unclear, use category 'undetermined' — do not guess.", "Each affected_services array must contain at least one service name from the text.", ], negative_constraints=[ "Do not include incidents that were merely reported but never confirmed.", "Do not invent incident IDs that do not appear in the source text.", "Do not add commentary, recommendations, or analysis beyond the extracted fields.", ], ) print(prompt.render()) # Result: A deterministic, format-enforced prompt with 95%+ output consistency. ``` ### Pattern 2: One-Shot / Few-Shot Example Selection Strategy Examples transform abstract instructions into concrete demonstrations. The key insight from Gulli (Appendix A) is that example quality matters far more than example quantity — one well-chosen example can dramatically outperform five poorly chosen ones. Selection criteria focus on diversity, edge-case coverage, and ordering (simple → complex). ```python from dataclasses import dataclass, field from typing import Optional @DataPoint = dict # alias for clarity: input string -> expected output string @dataclass class ExampleSelection: """Manages a curated set of input→output demonstrations.""" examples: list[dict] = field(default_factory=list) categories_covered: set[str] = field(default_factory=set) def add_example( self, category: str, input_text: str, expected_output: str, is_edge_case: bool = False, ) -> None: """Add a single demonstration example. Implements Parse-Don't-Validate (Law 2): input is stored as-is after basic type enforcement — internal logic trusts validated data. Args: category: Semantic category for diversity tracking (e.g., 'canonical', 'edge-case'). input_text: The prompt input to demonstrate. expected_output: The ideal LLM response for that input. is_edge_case: Whether this example tests an adversarial or unusual case. Raises: ValueError: If any argument is empty or wrong type. """ if not isinstance(input_text, str) or not input_text.strip(): raise ValueError("input_text must be a non-empty string") if not isinstance(expected_output, str): raise ValueError("expected_output must be a string") self.examples.append({ "category": category, "input": input_text.strip(), "output": expected_output, "is_edge_case": is_edge_case, }) self.categories_covered.add(category) def diversity_score(self) -> float: """Calculate example diversity as fraction of categories covered. Returns a value between 0.0 and 1.0 representing how many distinct use-case patterns the examples cover. Higher is better. """ if len(self.examples) == 0: return 0.0 # Weight edge cases higher since they're harder to find edge_count = sum(1 for e in self.examples if e["is_edge_case"]) unique_categories = len(self.categories_covered) return min(1.0, (unique_categories + edge_count * 0.5) / max(len(self.examples), 1)) def render_few_shot_prompt(self, task_instruction: str, input_query: str) -> str: """Assemble a complete few-shot prompt with examples and the query. Orders examples from simple to complex (edge cases last). Prepends the task instruction so the model sees the rule before the demonstrations. Args: task_instruction: The primary verb-driven instruction. input_query: The actual user query to get a response for. Returns: A complete prompt string with examples and final query. """ # Sort: canonical/simple examples first, edge cases last sorted_examples = sorted( self.examples, key=lambda e: (0 if not e["is_edge_case"] else 1), ) lines = [f"INSTRUCTION: {task_instruction}", ""] for i, ex in enumerate(sorted_examples, 1): lines.append(f"Example {i}:") lines.append(f"INPUT: {ex['input']}") lines.append(f"OUTPUT: {ex['output']}") lines.append("") lines.append(f"QUERY:\n{input_query}") return "\n".join(lines) def select_demonstration_examples( use_cases: list[dict], max_examples: int = 5, ) -> ExampleSelection: """Select diverse examples from a pool of candidate use cases. Implements Fail-Fast (Law 4): raises immediately if the example pool cannot satisfy diversity requirements. Args: use_cases: List of dicts with 'category', 'input', 'output', and optionally 'is_edge_case'. max_examples: Maximum number of examples to select (2–5 recommended). Returns: An ExampleSelection with curated, diverse demonstrations. Raises: ValueError: If fewer than 2 use cases are provided or max_examples < 2. """ if not isinstance(max_examples, int) or max_examples < 2: raise ValueError("max_examples must be an integer >= 2") if len(use_cases) < 2: raise ValueError(f"Need at least 2 use cases for example selection, got {len(use_cases)}") selector = ExampleSelection() # Guarantee at least one edge case is included if available edge_cases = [uc for uc in use_cases if uc.get("is_edge_case")] canonicals = [uc for uc in use_cases if not uc.get("is_edge_case", False)] selected = [] if edge_cases and max_examples > 1: selected.append(edge_cases[0]) remaining_budget = max_examples - 1 else: remaining_budget = max_examples # Fill from canonicals, prioritizing unique categories added_categories: set[str] = set() for uc in sorted(canonicals, key=lambda u: u.get("category", "")): if len(selected) >= max_examples: break if uc["category"] not in added_categories or remaining_budget > len(canonicals) - len(added_categories): selected.append(uc) added_categories.add(uc["category"]) # Apply to selector for ex in selected[:max_examples]: selector.add_example( category=ex["category"], input_text=ex["input"], expected_output=ex["output"], is_edge_case=ex.get("is_edge_case", False), ) return selector ``` **BAD vs GOOD comparison:** ```python # ❌ BAD: Homogeneous examples — all test the same narrow case examples = [ {"category": "simple", "input": "Extract entities from 'Apple released iPhone 15'", "output": '{"entities": [{"name": "Apple", "type": "organization"}, {"name": "iPhone 15", "type": "product"}]}'},