@ckelsoe/prompt-architect 3.3.1 → 3.5.0

package/skills/prompt-architect/references/frameworks/react.md

@@ -6,15 +6,17 @@ ReAct (Reasoning + Acting) is an agentic prompting framework that interleaves re
 
 ReAct is the framework of choice when the task requires using tools, querying external sources, writing and executing code, or navigating a multi-step process where each step's result informs the next.
 
-**Research basis:** Introduced in "ReAct: Synergizing Reasoning and Acting in Language Models" (Yao et al., arXiv 2210.03629, 2022; ICLR 2023).
+**Research basis:** Introduced in "ReAct: Synergizing Reasoning and Acting in Language Models" (Yao et al., arXiv 2210.03629, 2022; ICLR 2023), where grounding a reasoning trace in executed tool calls beat action-only baselines and reduced the fabrication that reasoning-only prompting produced. Those results come from *executed* trajectories — a live tool backend (Wikipedia search and lookup, among others) returned every Observation, and a controller dispatched each Action and fed the real result back into the next step. What this framework ships is a prompt that *specifies* that protocol: it does not implement the tool dispatch, the Observation source, or the loop that carries results forward, and all three must already exist in the environment where the prompt is pasted. Where they do not, there is nothing to act on and the cycle degrades to formatted reasoning — the case the "Avoid ReAct when" guidance below routes away from.
 
 ## Components
 
 ### Goal
 **Purpose:** Define what needs to be achieved — the end state the agent should reach.
 
-### Tools / Resources Available
-**Purpose:** List what the agent can use to accomplish the goal. This tells the model what actions are possible.
+### Available Tools
+**Purpose:** List what the agent can use to accomplish the goal. This tells the model what actions are possible, and — because the template forbids calling anything not on the list — what it may not do.
+
+Describe each tool only from what the user actually told you. Do not invent inputs or return values they did not state; a tool described with a return value it does not have produces a plan that fails at the first call.
 
 **Common tool types:**
 - Search / web lookup
@@ -24,83 +26,147 @@ ReAct is the framework of choice when the task requires using tools, querying ex
 - Calculator / computation
 - Database queries
 
+### Constraints
+**Purpose:** Bound every action with requirements and prohibitions, and — mandatory in this template — name the stop condition.
+
+The `CONSTRAINTS:` block always carries a "Stop and deliver your Final Answer when …" line naming the observable situation that means the goal is reached or cannot be. Without it an agent loop has no terminating condition. An optional hard ceiling on tool calls can be added; delete that line when there is no limit.
+
 ### ReAct Cycle
 **Purpose:** The repeating Thought → Action → Observation loop.
 
 - **Thought:** Reason about the current state and what to do next
 - **Action:** Take a specific, concrete action using an available tool
-- **Observation:** Record the result of the action
+- **Observation:** The result the tool actually returned — the one component the emitted prompt never authors (see below)
 - *(Repeat until goal is reached)*
 
+**The model filling this template must never write an Observation.** An Observation is the output of an executed tool call, produced by the environment at run time. It is not a slot to fill. Writing one produces a fabricated investigation that reads as though it happened — a plausible trace, a confident Final Answer, and no execution behind either.
+
+This overrides the "fill missing elements with reasonable defaults" instruction in SKILL.md step 5. An unfilled Observation is not a missing element awaiting a sensible default; it is a result that cannot exist until something runs. `react_template.txt` carries this ban explicitly. Emit the `Observation:` label with the template's description of what the tool will return, and leave the value to the run.
+
 ### Final Answer
 **Purpose:** Once the goal is achieved, provide the answer or deliverable.
 
 ## Template Structure
 
+Two rules govern this template's labels, and they point in opposite directions:
+
+Section headers (`GOAL:`, `AVAILABLE TOOLS:`, `CONSTRAINTS:`, `APPROACH:`) are stripped at emission, so every header's meaning is carried by the unbracketed prose that ships beneath it. Do not reintroduce header-only structure.
+
+The cycle labels (`Thought:`, `Action:`, `Observation:`, `Final Answer:`) are the exception — they are literal tokens of the ReAct protocol, not headings, and they survive into the emitted prompt exactly as written. Stripping them breaks the loop.
+
+This is the template as shipped in `assets/templates/react_template.txt`:
+
 ```
+You are an agent that reaches a goal by calling tools, not by answering in one pass from what
+you already know. Work in a Thought → Action → Observation loop, letting each real tool result
+decide your next step. If the tools below are not actually callable here, stop and say so —
+without live tools this protocol is only formatted guesswork, and plain step-by-step reasoning
+fits better.
+
 GOAL:
-[What needs to be achieved — the end state]
+The end state you must reach before you stop:
+[A full sentence naming what must be produced or determined. Write it as an outcome, not an
+activity.]
 
 AVAILABLE TOOLS:
-- [Tool 1]: [What it does]
-- [Tool 2]: [What it does]
-- [Tool 3]: [What it does]
+Do not call any tool that is not named here:
+- [tool_name]: [Full sentence on what this tool does and what input it takes, drawn only from
+  what the user actually told you — do not invent inputs or return values they did not state.]
+- [tool_name]: [Same form, one line per tool the user named. Delete any unused line rather
+  than inventing a tool to fill it.]
 
 CONSTRAINTS:
-- [Any rules, limits, or guardrails on actions]
+Every action is bound by these rules — each is a requirement or a prohibition, not a
+suggestion:
+- [A self-contained imperative, e.g. "Base every conclusion on data you actually retrieved."
+  Phrase restrictions as "Do not…" or "Never…" so each prohibition stands on its own line.]
+- Stop and deliver your Final Answer when [full clause naming the observable situation that
+  means the goal is reached, or that it cannot be].
+- [Optional — a hard ceiling as a full sentence, e.g. "Make no more than 8 tool calls in
+  total." Delete this line if there is no limit.]
 
 APPROACH:
-Use the Thought → Action → Observation cycle:
+Repeat this cycle until the goal is reached, each step on its own line starting with its
+label. Replace each description below with your actual content:
+
+Thought: your reasoning about where things stand and what to do next
+Action: the tool name, then an em dash, then the exact input you are passing to that tool
+Observation: the exact result that tool returned
+
+When the cycle has stopped, write this one line, one time only:
+
+Final Answer: the deliverable the goal asked for, supported by what your Observations showed
+
+Rules for the cycle:
+- Every Action must name one tool from the list above, never prose — e.g. Action:
+  search_docs — "token refresh policy"
+- Take ONE action at a time, then wait for its real Observation before continuing; each
+  Thought must respond to the Observation directly before it.
+- Never write an Observation yourself. An Observation is the actual output of an actual tool
+  call. Inventing one produces a fabricated investigation that reads as though it happened.
+- "Thought:", "Action:", "Observation:" and "Final Answer:" are literal labels in this
+  protocol, not headings — keep them exactly as written.
+```
 
-Thought: [Reason about current state and next step]
-Action: [Tool name] — [specific query or operation]
-Observation: [Result of the action]
+Note what the emitted prompt ends with: the cycle *instructions*. It does not contain a filled-in cycle. The three lines under `APPROACH:` are descriptions of what each label should carry once the agent runs — they are not a first turn to be completed on the user's behalf.
 
-Thought: [Reason about observation and what to do next]
-Action: [Tool name] — [next operation]
-Observation: [Result]
+## Complete Examples
 
-[Continue until goal is reached]
+**Read these as two separate things.** Each example shows the prompt that gets emitted, and then — separately — a transcript of a run that already happened in an environment with live tools. The transcripts are illustrations of a completed run, not part of the deliverable. Every `Observation:` in them is a value a real tool returned; none was written by the model that composed the prompt.
 
-Final Answer: [Deliver the result]
-```
+When you emit a ReAct prompt, you emit the first block only. The trace is what the run produces afterward. Writing a trace into the prompt is the failure mode the template's Observation ban exists to prevent.
 
-## Complete Examples
+The `APPROACH:` bodies below are abbreviated for readability — the real emitted prompt carries the full cycle instructions and "Rules for the cycle" block verbatim from Template Structure above.
 
 ### Example 1: Research Task (Agentic)
 
 **Before ReAct:**
 "Find out which JavaScript framework is most popular right now."
 
-**After ReAct:**
+**After ReAct — the emitted prompt:**
 ```
+You are an agent that reaches a goal by calling tools, not by answering in one pass from
+what you already know. [...framing paragraph as in Template Structure...]
+
 GOAL:
-Determine which JavaScript frontend framework has the highest current adoption
-and provide a brief evidence-based recommendation for a new project.
+The end state you must reach before you stop:
+Determine which JavaScript frontend framework has the highest current adoption, and
+produce a brief evidence-based recommendation for a new project.
 
 AVAILABLE TOOLS:
-- web_search: Search for current information
-- fetch_page: Retrieve content from a specific URL
+Do not call any tool that is not named here:
+- web_search: Searches the web for a query string and returns result snippets with their
+  source URLs.
+- fetch_page: Retrieves the full text content of a single URL you pass to it.
 
 CONSTRAINTS:
-- Use at least 2 independent sources
-- Prioritize data from the last 12 months
-- Do not rely on a single survey
+Every action is bound by these rules — each is a requirement or a prohibition, not a
+suggestion:
+- Base every conclusion on data you actually retrieved.
+- Prioritize data published within the last 12 months.
+- Never rely on a single survey.
+- Stop and deliver your Final Answer when at least two independent sources agree on a
+  ranking, or when you have established that they disagree irreconcilably.
 
 APPROACH:
-Thought: I need current data on JS framework popularity. I'll start with
-the Stack Overflow Developer Survey and npm download stats.
-
-Action: web_search — "JavaScript framework popularity 2024 Stack Overflow survey"
-Observation: [Search results]
+[...cycle instructions and "Rules for the cycle" block, verbatim from the template...]
+```
 
-Thought: Found Stack Overflow survey data. Let me also check npm trends for
-download numbers to corroborate.
+**The run that followed** — transcript, tools live; each Observation is what the tool returned:
+```
+Thought: I need current data on JS framework popularity. I'll start with the Stack
+Overflow Developer Survey and corroborate against npm download stats.
+Action: web_search — "JavaScript framework popularity Stack Overflow developer survey"
+Observation: Snippets from the survey's web-frameworks section, with React ahead of
+Angular and Vue among all respondents, plus the survey methodology page.
 
-Action: web_search — "React vs Vue vs Angular npm downloads 2024"
-Observation: [Search results]
+Thought: That is one source, and the constraint forbids relying on a single survey.
+Download volume is an independent signal, so I will check npm next.
+Action: web_search — "React vs Vue vs Angular npm downloads"
+Observation: npm trends comparison showing weekly download counts for the three
+packages over the trailing year.
 
-Thought: I have data from two sources. Let me synthesize the findings.
+Thought: Two independent sources now agree on the ordering. The stop condition is met.
 
 Final Answer: Based on [sources], React leads in adoption at X%, followed by...
 ```
@@ -110,52 +176,64 @@ Final Answer: Based on [sources], React leads in adoption at X%, followed by...
 **Before ReAct:**
 "Debug why the tests are failing."
 
-**After ReAct:**
+**After ReAct — the emitted prompt:**
 ```
+You are an agent that reaches a goal by calling tools, not by answering in one pass from
+what you already know. [...framing paragraph as in Template Structure...]
+
 GOAL:
-Identify and fix the root cause of the failing unit tests in the auth module.
-All 3 tests in auth.test.js are failing after the refactor.
+The end state you must reach before you stop:
+Identify and fix the root cause of the 3 failing unit tests in auth.test.js, which began
+failing after the auth module refactor.
 
 AVAILABLE TOOLS:
-- read_file: Read any file in the codebase
-- run_tests: Execute test suite and return output
-- search_code: Search codebase for patterns
+Do not call any tool that is not named here:
+- read_file: Takes a path and returns the full contents of that file from the codebase.
+- run_tests: Takes a test file path, executes that suite, and returns the pass/fail
+  output with error text.
+- search_code: Takes a string and returns every location in the codebase where it appears.
 
 CONSTRAINTS:
-- Fix the root cause, not the symptoms
-- Do not change test code unless tests themselves are wrong
-- Verify fix by running tests again after changes
+Every action is bound by these rules — each is a requirement or a prohibition, not a
+suggestion:
+- Fix the root cause, not the symptom.
+- Do not change test code unless you have established the tests themselves are wrong.
+- Never report a fix you have not verified by re-running the suite.
+- Stop and deliver your Final Answer when run_tests reports all 3 tests passing, or when
+  you have determined the fix requires information not available through these tools.
 
 APPROACH:
-Thought: I need to understand what the tests expect before I look at the implementation.
+[...cycle instructions and "Rules for the cycle" block, verbatim from the template...]
+```
 
+**The run that followed** — transcript, tools live; each Observation is what the tool returned:
+```
+Thought: I need to understand what the tests expect before I look at the implementation.
 Action: read_file — auth.test.js
-Observation: [File contents]
-
-Thought: Tests are calling `auth.validateToken(token)` but based on the refactor
-PR description, the function was renamed. Let me check the new implementation.
+Observation: The three test cases, each calling auth.validateToken(token) with a
+different fixture.
 
+Thought: The tests call `auth.validateToken(token)`. The refactor PR description
+mentions a rename, so I should check what the implementation exports now.
 Action: read_file — auth.js
-Observation: [File contents]
-
-Thought: Confirmed — function was renamed to `auth.verifyToken()`. Tests use old name.
-Let me check if this was an intentional API change or a mistake.
+Observation: The module exports verifyToken; no validateToken export remains.
 
+Thought: Confirmed — the function was renamed to `auth.verifyToken()` and the tests use
+the old name. I need to know whether this was an intentional API change or an oversight,
+which depends on whether other callers were updated.
 Action: search_code — "validateToken"
-Observation: [All usages across codebase]
-
-Thought: validateToken is used in 3 other places too. This is a breaking rename.
-The tests are correct — the implementation changed names without updating callers.
-I'll restore the original name in the implementation and add an alias if needed.
-
-[Apply fix]
+Observation: Three call sites outside the test file, all still using the old name.
 
+Thought: validateToken is used in 3 other places that were never updated. This is a
+breaking rename, not an intentional API change — the tests are correct and the
+implementation changed names without updating its callers. I will restore the original
+name and add the new one as an alias, then verify.
 Action: run_tests — auth.test.js
-Observation: All 3 tests passing.
+Observation: 3 passed, 0 failed.
 
-Final Answer: Root cause was function rename in auth.js that broke all callers.
-Restored original function name and added `verifyToken` as an alias for forward
-compatibility.
+Final Answer: Root cause was a function rename in auth.js that broke all callers.
+Restored the original function name and added `verifyToken` as an alias for forward
+compatibility. Verified by run_tests: all 3 tests pass.
 ```
 
 ### Example 3: Data Investigation
@@ -163,46 +241,77 @@ compatibility.
 **Before ReAct:**
 "Why are sales down this month?"
 
-**After ReAct:**
+**After ReAct — the emitted prompt:**
 ```
+You are an agent that reaches a goal by calling tools, not by answering in one pass from
+what you already know. [...framing paragraph as in Template Structure...]
+
 GOAL:
-Identify the primary factor(s) driving the 23% month-over-month decline in
-sales this quarter. Provide a ranked list of likely causes with supporting data.
+The end state you must reach before you stop:
+Produce a ranked list of the factors driving the 23% month-over-month sales decline this
+quarter, each supported by the data that establishes it.
 
 AVAILABLE TOOLS:
-- query_database: Run SQL queries against the sales database
-- fetch_analytics: Pull data from the analytics dashboard
-- read_file: Read exported reports and CSV files
+Do not call any tool that is not named here:
+- query_database: Takes a SQL query and runs it against the sales database, returning the
+  result rows.
+- fetch_analytics: Takes a metric name and date range and returns that series from the
+  analytics dashboard.
+- read_file: Takes a path and returns the contents of an exported report or CSV.
 
 CONSTRAINTS:
-- Base conclusions on data, not assumptions
-- Consider at least 3 potential causes before concluding
-- If data is insufficient to conclude, state what additional data is needed
+Every action is bound by these rules — each is a requirement or a prohibition, not a
+suggestion:
+- Base every conclusion on data you actually retrieved.
+- Consider at least 3 potential causes before concluding.
+- Do not present a cause as established when the data only makes it plausible; say which
+  it is.
+- If the available data is insufficient to conclude, state exactly what additional data
+  is needed rather than closing the gap with an assumption.
+- Stop and deliver your Final Answer when you can rank the causes by supported effect
+  size, or when you have established which data you are missing.
 
 APPROACH:
-Thought: 23% decline is significant. I should check whether it's volume (fewer
-orders), value (smaller orders), or both. Also check if it's across all segments
-or concentrated.
+[...cycle instructions and "Rules for the cycle" block, verbatim from the template...]
+```
 
+**The run that followed** — transcript, tools live; each Observation is what the tool returned:
+```
+Thought: A 23% decline is large enough to have a dominant cause. I should first
+establish whether it is volume, order value, or both, and whether it is spread across
+segments or concentrated in one.
 Action: query_database — "SELECT COUNT(*), AVG(order_value), segment FROM orders
-WHERE month = current AND month = previous GROUP BY segment"
-Observation: [Query results]
-
-Thought: Volume is down 18% but average order value is down only 5%. The decline
-is concentrated in the Enterprise segment. Let me check acquisition vs. churn.
+WHERE month IN (current, previous) GROUP BY segment, month"
+Observation: Order count down 18% overall; average order value down 5%; the drop is
+concentrated in the Enterprise segment, with SMB roughly flat.
 
+Thought: So this is mostly a volume problem in one segment, not a pricing problem
+across the book. Fewer Enterprise orders could be lost acquisition or lost accounts, and
+those have different fixes, so I need to separate them.
 Action: query_database — "SELECT new_customers, churned_customers, segment FROM
 customer_events WHERE period = last_30_days"
-Observation: [Query results]
-
-Thought: Enterprise churn is 3x normal. Let me check if there's a product or
-pricing event that coincides.
-
-[Continue investigation...]
-
-Final Answer: Primary driver is Enterprise churn (elevated 3x), concentrated
-in accounts that received the new pricing email on [date]. Secondary factor is
-reduced trial-to-paid conversion, down 12%.
+Observation: Enterprise churn roughly 3x the trailing average; new Enterprise customers
+near normal.
+
+Thought: Churn, not acquisition. Before ranking causes I need to know whether the weakness
+is confined to existing Enterprise accounts or also shows at the top of the funnel, so I
+will pull conversion over a window wide enough to place the churn spike inside it.
+Action: fetch_analytics — "trial_to_paid_conversion, last 90 days"
+Observation: Conversion down 12% over the window, with the decline beginning in the same
+week as the churn spike.
+
+Final Answer: Ranked by supported effect size.
+1. Enterprise churn — established. Churn ran roughly 3x the trailing average while new
+   Enterprise customers stayed near normal, and the order-count drop is concentrated in
+   that same segment. This is the bulk of the 18% volume decline.
+2. Trial-to-paid conversion — established. Down 12% across the 90-day window.
+3. Average order value — established but minor. Down 5% overall; too small to account for
+   a 23% total decline on its own. I did not break this figure out by segment.
+
+The churn spike and the conversion decline begin in the same week. That timing makes a
+single underlying cause plausible, not established: nothing I retrieved identifies what
+changed in that window. Confirming it requires the product and pricing change log for
+those dates joined to the churned account list, which none of these three tools expose.
 ```
 
 ## Best Use Cases
@@ -259,10 +368,17 @@ reduced trial-to-paid conversion, down 12%.
 ```
 
 ### Tools Should Be Named and Described
+
+A full sentence naming what the tool does *and what input it takes*. A verb fragment omits the
+input, so the agent has to guess how to call it:
 ```
-✅ - run_tests: Execute the test suite and return pass/fail results with error output
+✅ - run_tests: Takes a test file path, executes that suite, and returns the pass/fail output
+     with error text.
+❌ - run_tests: Execute the test suite and return pass/fail results with error output
 ❌ - testing tool
 ```
+Draw the description only from what the user actually told you. A tool documented with an input
+or a return value it does not have produces a plan that fails at the first call.
 
 ### Constraints Prevent Loops
 ```
@@ -271,9 +387,15 @@ reduced trial-to-paid conversion, down 12%.
 ```
 
 ### Include a Stop Condition
+
+Write it as the template's mandatory line — the full imperative, not a label standing in for one:
 ```
-✅ "Stop when: the fix is confirmed by passing tests OR you've determined the fix requires information not available to you"
+✅ "Stop and deliver your Final Answer when run_tests reports the suite passing, or when you
+   have determined the fix requires information not available through these tools."
+❌ "Stop when: fix confirmed or blocked"
 ```
+The ❌ form leaves the label carrying the meaning. `Stop when:` is a heading; the agent needs a
+sentence it can act on, naming the observable situation that ends the loop.
 
 ## Common Mistakes
 
@@ -292,13 +414,24 @@ reduced trial-to-paid conversion, down 12%.
 4. **Using ReAct for Static Tasks**
    - If no tools are needed, Chain of Thought is simpler and more effective
 
+5. **Writing Observations Into the Prompt**
+   - The single most damaging mistake this framework invites, because the result looks like success
+   - An Observation is a returned value, not a slot — filling one in fabricates a run
+   - The output reads as an executed investigation: real-looking results, a confident Final Answer, nothing behind either
+   - Emit the `Observation:` label and its description; the value belongs to the run
+
+6. **Emitting a Completed Cycle**
+   - The prompt ends with the cycle *instructions*, not a worked first turn
+   - A pre-filled Thought/Action pair also pre-commits the agent to a path before it has seen any real result, which is the opposite of what ReAct is for
+
 ## Quick Reference
 
 | Component | Focus | Key Question |
 |-----------|-------|--------------|
 | Goal | End state | "What does success look like?" |
 | Tools | Available actions | "What can the agent do?" |
+| Constraints | Rules and stop condition | "What is forbidden, and when does it stop?" |
 | Thought | Reasoning | "What should I do next and why?" |
 | Action | Tool use | "What specific action to take?" |
-| Observation | Result | "What happened?" |
+| Observation | Returned result — **never authored by the prompt** | "What did the tool actually return?" |
 | Final Answer | Deliverable | "Goal achieved — what's the answer?" |

package/skills/prompt-architect/references/frameworks/reverse-role.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Reverse Role Prompting flips the traditional prompting dynamic: instead of you constructing a detailed prompt, you provide a minimal intent statement and the AI interviews you — asking targeted clarifying questions — until it has enough information to execute the task well. This is the framework for when you know what you want but struggle to articulate all the details needed for a good prompt.
+Reverse Role Prompting flips the traditional prompting dynamic: instead of you constructing a detailed prompt, you provide a minimal intent statement and the AI interviews you — asking targeted clarifying questions — until it has enough information to execute the task well. This is the framework for when you know what you want but struggle to articulate all the details needed for a good prompt. A complete Reverse Role prompt emits as a short block of prose — an intent statement plus an instruction to run an interview — and carries no source-material block, because the interview is how it gathers everything it needs; SKILL.md exempts it from the material question for exactly that reason. The scaffolding is minimal, but the emission rule still holds: each line has to carry its own meaning in the sentence around it, since there is no header to lean on once the prompt is pasted.
 
 **Research basis:** Widely circulated as "reverse prompting" in practitioner communities (2023–2024). Formalized academically as **FATA** (First Ask Then Answer), arXiv 2508.08308, August 2025 — showing ~40% improvement over standard prompting. Related to **Socratic Prompting** (Chang, arXiv 2303.08769, IEEE CCWC 2023).
 
@@ -17,10 +17,10 @@ Reverse Role Prompting flips the traditional prompting dynamic: instead of you c
 ## Components
 
 ### Intent Statement
-**Purpose:** Your minimal starting point — what you want to achieve in 1-2 sentences. Intentionally brief; the AI will fill in the gaps through questions.
+**Purpose:** Your minimal starting point — what you want to achieve in 1-2 sentences. Intentionally brief; the AI will fill in the gaps through questions. Because the prompt has no separate task block, the intent line is the only thing telling the AI what the interview is in service of, so write it as a complete "My goal: …" statement rather than a bare topic — it still has to read as the objective once any surrounding scaffolding is gone.
 
 ### Interview Trigger
-**Purpose:** The instruction that activates the AI-led interview mode.
+**Purpose:** The instruction that activates the AI-led interview mode. This is the load-bearing sentence of the whole prompt, and it must ship as a complete imperative ("Before you begin, interview me to…"), because nothing else — no header, no format cue — tells the model to run an interview instead of answering immediately. The sentence has to say so itself.
 
 **Core triggers:**
 - Minimal: *"Before responding, ask me all the questions you need to give me the best possible answer."*
@@ -28,16 +28,18 @@ Reverse Role Prompting flips the traditional prompting dynamic: instead of you c
 - Expert mode: *"You are an expert in [X]. Before beginning, conduct a discovery interview to understand my specific situation. Ask one question at a time."*
 
 ### Domain Scope
-**Purpose:** Optionally specify the domain of expertise the AI should bring to the interview. This shapes the quality and relevance of its questions.
+**Purpose:** Optionally specify the domain of expertise the AI should bring to the interview. This shapes the quality and relevance of its questions. It ships as a complete opening sentence ("You are an expert [X] consultant"), which both sets the lens and, standing on its own line, needs no header to announce what it is.
 
 ### Interview Mode
-**Purpose:** Single-batch (FATA: all questions at once) vs. conversational (one question at a time). FATA is faster; conversational is more natural.
+**Purpose:** Single-batch (FATA: all questions at once) vs. conversational (one question at a time). FATA is faster; conversational is more natural. The choice ships inside the carrier sentence "Ask your questions [one at a time / all at once]," so the bracketed slot can stay a fragment while the sentence around it carries the instruction.
 
 ### Synthesis Instruction (optional)
-**Purpose:** After the interview, instruct the AI to either (a) execute the task directly, or (b) first produce a written prompt you can reuse.
+**Purpose:** After the interview, instruct the AI to either (a) execute the task directly, or (b) first produce a written prompt you can reuse. It ships as a complete closing sentence — the template's optional final line — and, like every other slot here, carries its own meaning in prose because there is no "SYNTHESIS:" header in the emitted prompt to carry it.
 
 ## Template Structure
 
+Reverse Role has no framework section headers of the kind the emitter strips — the shipped template is already a short block of prose, and it carries no source-material block because the interview elicits everything it needs. What the emission contract still asks of it is that every slot carry its own meaning in the sentence around it: the intent line reads as an objective, the interview trigger reads as an instruction to run an interview, and the batch-versus-conversational choice rides inside a carrier sentence rather than a header. The one place a header appears — the two-stage version's `STAGE 1` / `STAGE 2` labels — is written so each stage's directive survives on its own if the label is removed.
+
 ### Minimal Version
 ```
 [Your 1-2 sentence intent statement]
@@ -48,16 +50,17 @@ best possible answer. Then, once I've answered, [execute the task / generate the
 
 ### Structured Expert Version
 ```
-You are an expert [domain] consultant.
+You are an expert [DOMAIN] consultant / specialist.
 
-My goal: [1-2 sentence intent]
+My goal: [1-2 sentence description of what you want to achieve]
 
-Before you begin, interview me to understand my specific context,
-constraints, goals, and any relevant background. Ask your questions
-[one at a time / all at once]. Only proceed with [the task] once you
-are confident you have everything you need.
+Before you begin, interview me to understand my specific context, constraints,
+goals, and any relevant background. Ask your questions [one at a time / all at once].
+Only proceed with [the task / generating the full prompt] once you are confident
+you have everything you need.
 
-After the interview: [execute directly / write a full structured prompt I can reuse]
+[Optional: After the interview, synthesize my responses into a complete structured
+prompt using the most appropriate framework, then confirm before executing.]
 ```
 
 ### Two-Stage Version (Interview → Prompt Generation)
@@ -76,16 +79,18 @@ Show me the prompt before executing it.
 
 ## Complete Examples
 
+Every example below is shown in emitted form: the prompt is a short block of prose, and each line carries its own role — intent, interview trigger, mode — without relying on a header. Where an example also shows the AI's questions, read those as the model's response to the prompt, not as part of the deliverable you paste.
+
 ### Example 1: Minimal Trigger
 
-**User intent:**
+**The emitted prompt:**
 ```
 I want to create a training program for new customer success managers.
 Before responding, ask me all the questions you need to give me the
 best possible answer.
 ```
 
-**AI interview questions (FATA style):**
+**What the AI produces in response (FATA style — its output, not part of the prompt):**
 ```
 1. What is the typical background of your CSM hires? (e.g., sales background,
    support, fresh graduates, industry-specific experience)
@@ -104,6 +109,7 @@ best possible answer.
 
 ### Example 2: Expert Domain Interview
 
+**The emitted prompt:**
 ```
 You are an expert in B2B SaaS pricing strategy.
 
@@ -117,6 +123,7 @@ Only advise once you have a full picture.
 
 ### Example 3: Two-Stage Prompt Builder
 
+**The emitted prompt:**
 ```
 STAGE 1 — INTERVIEW:
 You are an expert prompt engineer and technical writer.