@ckelsoe/prompt-architect 3.2.2 → 3.4.0

package/skills/prompt-architect/references/frameworks/pre-mortem.md

@@ -2,20 +2,23 @@
 
 ## Overview
 
-Pre-Mortem Prompting adapts Gary Klein's prospective hindsight technique to AI prompting. Instead of asking "what could go wrong?" (which triggers optimism bias and produces vague risks), it instructs the AI to *assume* the project or decision has already failed catastrophically — then work backwards to identify the specific reasons why. This committed-failure frame consistently produces more specific, actionable failure identification than forward risk analysis.
+Pre-Mortem Prompting adapts Gary Klein's prospective hindsight technique to AI prompting. Instead of asking "what could go wrong?" (which triggers optimism bias and produces vague risks), it instructs the AI to *assume* the project or decision has already failed catastrophically — then work backwards to identify the specific reasons why. In practice this committed-failure frame tends to yield more specific, actionable failure identification than an open-ended "what could go wrong?" question.
 
-**Research basis:** Gary Klein's prospective hindsight research (Cognitive Systems Engineering; Brookings Institution). Studies show ~30% improvement in correct identification of failure causes compared to standard forward risk analysis. Application to LLM prompting is practitioner-level (no dedicated AI paper), but the cognitive mechanism is well-established.
+**Research basis:** Mitchell, Russo & Pennington, "Back to the Future: Temporal Perspective in the Explanation of Events" (*Journal of Behavioral Decision Making*, 1989) found that prospective hindsight — imagining an event has *already occurred* — increases the ability to correctly identify **reasons for future outcomes** by ~30%, compared with imagining it *might* occur. Gary Klein popularized the technique as the "pre-mortem" (*Harvard Business Review*, September 2007), which is where the 30% figure is most often cited from. Note the measured comparison is already-happened vs. might-happen framing, not pre-mortem vs. forward risk analysis. Application to LLM prompting is practitioner-level (no dedicated AI paper), but the cognitive mechanism is well-established.
 
-## Why Assumed Failure Outperforms Forward Risk Analysis
+## Why the Assumed-Failure Frame Helps
 
-Forward risk: *"What could go wrong?"* → Produces vague, hedged answers ("there might be delays", "adoption could be low")
+Forward risk: *"What could go wrong?"* → Tends to produce vague, hedged answers ("there might be delays", "adoption could be low")
 
-Pre-mortem: *"This has already failed — why did it fail?"* → Produces specific, committed answers ("the integration with Salesforce took 3x longer than estimated because we didn't account for their API rate limits")
+Pre-mortem: *"This has already failed — why did it fail?"* → Tends to produce specific, committed answers ("the integration with Salesforce took 3x longer than estimated because we didn't account for their API rate limits")
 
-The difference: by committing to the failure frame, the model bypasses optimism bias and generates specific causal narratives rather than probabilistic hedges.
+The mechanism: committing to the failure frame bypasses optimism bias and elicits specific causal narratives rather than probabilistic hedges. This is the practitioner rationale for the technique — the 1989 study measured the certainty framing itself, not a head-to-head against forward risk analysis, so treat the comparison above as an observed pattern rather than a measured result.
 
 ## Components
 
+### Source Material (optional)
+**Purpose:** The project plan, proposal, or decision document the analysis works from. Supplying it grounds the failure causes in what the plan actually says rather than in the model's assumptions about a project of that description. The template's slot is optional and self-deleting: if there is nothing to paste, the bracketed block and the sentence directly below it both come out.
+
 ### Project/Decision Description
 **Purpose:** What is being analyzed. Include enough context for the model to generate specific (not generic) failure causes.
 
@@ -27,6 +30,8 @@ The difference: by committing to the failure frame, the model bypasses optimism
 
 **Standard framing:** *"It is [future date] and [project/decision] has completely and catastrophically failed."*
 
+**The frame has to be defended, not just stated.** A model given only the assumption will drift back into probabilistic language within a few sentences — "adoption may have lagged", "the integration could have slipped" — which collapses the pre-mortem back into ordinary forward risk analysis and throws away the entire mechanism. The template therefore opens by declaring the failure settled fact rather than a possibility, and closes that opening with an explicit prohibition: *do not hedge with "could," "might," or "may."* Keep both. Per SKILL.md step 5, a prohibition the user relies on must survive into the emitted prompt as explicit instruction text — it cannot be left to a section header, because headers are stripped at emission.
+
 ### Domain Analysis
 **Purpose:** The specific dimensions to analyze for failure causes. More dimensions = more comprehensive coverage.
 
@@ -41,102 +46,206 @@ The difference: by committing to the failure frame, the model bypasses optimism
 ### Warning Signs
 **Purpose:** For each failure cause, identify the earliest observable warning sign. This is what makes pre-mortem actionable — not just "this could fail" but "this is what we'd see 30 days before it fails."
 
-### Mitigation Pass (optional)
-**Purpose:** A second pass ranking the failure causes by likelihood × preventability and suggesting pre-emptive actions.
+### Priority Assessment
+**Purpose:** A closing pass over the causes already listed, singling out three things: the 3 most LIKELY to be what actually happened, the 3 most PREVENTABLE — where action taken today would have made the most difference — and any single point of failure that could have killed the project on its own.
+
+These are two separate top-3 lists, not one ranking by a combined likelihood-and-preventability score. A cause can be near-certain and unpreventable, or unlikely and trivially preventable; collapsing them into a single ranking buries both. The preventable list is the one that converts the analysis into action. Unlike Source Material above, this slot is unconditional — the template gives it no bracketed block and no deletion instruction.
 
 ## Template Structure
 
+Section headers are stripped at emission, so every slot's meaning is carried by the prose around and inside it rather than by the header above it. The opening paragraph is not a title — it is the instruction that establishes the settled-failure frame, and it ships with the prompt.
+
 ```
-PRE-MORTEM ANALYSIS
+You are conducting a pre-mortem on the project described below. The failure stated further
+down is settled fact, not a possibility — work backwards from it and explain why it happened.
+Do not hedge with "could," "might," or "may."
+
+SOURCE MATERIAL:
+[Optional — paste the project plan, proposal, or decision document here. If you have nothing
+to paste, delete this bracketed block along with the sentence directly below it.]
+Use the material above as the factual basis for the work described below.
 
 PROJECT/DECISION:
-[Describe the project, plan, or decision being analyzed]
+[Describe the project, plan, or decision being analyzed in full sentences — what is being
+attempted, plus team size, timeline, resources, goals, and constraints]
 
 FAILURE ASSUMPTION:
-It is [DATE — e.g., 12 months from now] and [project/decision] has
-completely and catastrophically failed. It did not achieve [primary goal].
+It is [DATE — e.g., 12 months from now] and [project/decision] has completely and
+catastrophically failed. It did not achieve [primary goal].
 
-FAILURE ANALYSIS:
-Describe the failure in 2-3 sentences from the perspective of someone
-looking back on it.
+FAILURE NARRATIVE:
+Begin by describing how that failure unfolded, in 2-3 sentences, in past tense from the
+perspective of someone looking back on it.
 
-Then identify [8-12] specific reasons this failed. For each reason:
+FAILURE CAUSES:
+Then identify [8-12] specific reasons it failed, each stated as something that already went
+wrong. Cover technical/product, team/organizational, market/adoption, financial/resource,
+external dependencies, and timeline/scope. Give each cause three lines:
 - CAUSE: [What specifically went wrong — be specific, not generic]
 - DOMAIN: [Technical / People / Market / Financial / External / Timeline]
 - WARNING SIGN: [What was the earliest observable indicator this was happening?]
-
-PRIORITY:
-After listing all causes, identify:
-1. The 3 most likely failure causes (given our specific situation)
-2. The 3 most preventable failure causes (where action now would help most)
-3. Any single point of failure that could kill the project alone
+"CAUSE:", "DOMAIN:" and "WARNING SIGN:" are literal labels in this protocol, not headings —
+keep them exactly as written.
+
+PRIORITY ASSESSMENT:
+After listing every cause, close by singling out three things:
+1. The 3 causes most LIKELY to be what actually happened, given the situation above.
+2. The 3 most PREVENTABLE causes — where action taken today would have made the most
+   difference.
+3. Any single point of failure that could have killed the project on its own.
 ```
 
+Three notes on why the shape is what it is:
+
+`FAILURE NARRATIVE` and `FAILURE CAUSES` are separate slots because they ask for different things — one continuous retrospective paragraph, then a structured enumeration. Collapsing them into a single analysis slot reliably produces a list with a narrative sentence stapled to the front, losing the retrospective voice that carries the frame.
+
+The `CAUSE` / `DOMAIN` / `WARNING SIGN` labels are the one place in this template where bare labels do survive into the output, because they are labels *inside* the requested response format rather than scaffolding headers around the prompt. The template says so explicitly, which is why that line is part of the prompt and not a comment about it.
+
+Every instruction slot is phrased as a sequenced directive — "Begin by", "Then identify", "After listing every cause, close by" — so the ordering survives even with the headers removed.
+
 ## Complete Examples
 
+Every example below keeps the headers on the page for readability, but is written in emitted form beneath them: the settled-failure paragraph first, then each slot carrying its own role in prose. Read the headers as scaffolding that will be deleted — the examples are written so that nothing is lost when it is. Note that only the user-supplied slots (source material, project, failure assumption) differ between examples; the instruction slots are the protocol and stay as written.
+
 ### Example 1: Product Launch
 
+**Before Pre-Mortem:**
+"What are the risks with our Q3 launch?"
+
+**After Pre-Mortem** (source material supplied):
 ```
-PROJECT:
-We are launching a new B2B project management tool for engineering teams
-in Q3. Our team is 4 engineers, 1 designer, and 1 PM. We have 3 design
-partners signed up for beta. Target: 50 paying customers by end of Q4.
+You are conducting a pre-mortem on the project described below. The failure stated further
+down is settled fact, not a possibility — work backwards from it and explain why it happened.
+Do not hedge with "could," "might," or "may."
 
-FAILURE ASSUMPTION:
-It is December 31st and we have failed to reach 50 paying customers.
-The product launched in October with 8 beta customers but growth stalled.
+SOURCE MATERIAL:
+[Paste the Q3 launch plan and the three design partners' beta feedback notes here]
+Use the material above as the factual basis for the work described below.
 
-FAILURE ANALYSIS:
-Describe how this played out. Then identify 10 specific failure causes
-with domain, and earliest warning sign for each.
+PROJECT/DECISION:
+We are launching a new B2B project management tool for engineering teams in Q3. The team is
+4 engineers, 1 designer, and 1 PM. Three design partners are signed up for the beta. The
+target is 50 paying customers by the end of Q4, against two quarters of remaining runway.
 
-PRIORITY:
-Rank by likelihood. Flag any single points of failure.
+FAILURE ASSUMPTION:
+It is December 31st and the launch has completely and catastrophically failed. It did not
+achieve 50 paying customers. The product shipped in October with 8 beta customers and
+growth stalled there.
+
+FAILURE NARRATIVE:
+Begin by describing how that failure unfolded, in 2-3 sentences, in past tense from the
+perspective of someone looking back on it.
+
+FAILURE CAUSES:
+Then identify 10 specific reasons it failed, each stated as something that already went
+wrong. Cover technical/product, team/organizational, market/adoption, financial/resource,
+external dependencies, and timeline/scope. Give each cause three lines:
+- CAUSE: [What specifically went wrong — be specific, not generic]
+- DOMAIN: [Technical / People / Market / Financial / External / Timeline]
+- WARNING SIGN: [What was the earliest observable indicator this was happening?]
+"CAUSE:", "DOMAIN:" and "WARNING SIGN:" are literal labels in this protocol, not headings —
+keep them exactly as written.
+
+PRIORITY ASSESSMENT:
+After listing every cause, close by singling out three things:
+1. The 3 causes most LIKELY to be what actually happened, given the situation above.
+2. The 3 most PREVENTABLE causes — where action taken today would have made the most
+   difference.
+3. Any single point of failure that could have killed the launch on its own.
 ```
 
 ### Example 2: Organizational Change
 
-```
-PROJECT:
-We are implementing a company-wide shift to OKRs across a 200-person
-organization. Executive sponsorship is in place. We're starting with
-a 2-day offsite to train team leads, then cascading to individual
-contributors over the following 6 weeks.
+**Before Pre-Mortem:**
+"What could go wrong with our OKR rollout?"
 
-FAILURE ASSUMPTION:
-It is 6 months from now and the OKR implementation has failed.
-Most teams have abandoned OKRs and reverted to old goal-setting methods.
+**After Pre-Mortem** (no source material — the optional block and its follow-on sentence are both deleted):
+```
+You are conducting a pre-mortem on the project described below. The failure stated further
+down is settled fact, not a possibility — work backwards from it and explain why it happened.
+Do not hedge with "could," "might," or "may."
 
-FAILURE ANALYSIS:
-10 specific reasons the rollout failed. Include: leadership domain,
-middle management domain, cultural domain, process domain, and tooling.
-For each: earliest warning sign.
+PROJECT/DECISION:
+We are implementing a company-wide shift to OKRs across a 200-person organization.
+Executive sponsorship is in place. The rollout starts with a 2-day offsite to train team
+leads, then cascades to individual contributors over the following 6 weeks. No dedicated
+program manager is assigned; team leads absorb the work alongside their existing roles.
 
-PRIORITY:
-The 3 most likely. The most preventable. Any single point of failure.
+FAILURE ASSUMPTION:
+It is 6 months from now and the OKR implementation has completely and catastrophically
+failed. It did not achieve durable adoption — most teams abandoned OKRs and reverted to
+their old goal-setting methods.
+
+FAILURE NARRATIVE:
+Begin by describing how that failure unfolded, in 2-3 sentences, in past tense from the
+perspective of someone looking back on it.
+
+FAILURE CAUSES:
+Then identify 10 specific reasons it failed, each stated as something that already went
+wrong. Cover leadership behavior, middle-management incentives, culture, process design,
+tooling, and timeline/scope. Give each cause three lines:
+- CAUSE: [What specifically went wrong — be specific, not generic]
+- DOMAIN: [Leadership / Middle management / Culture / Process / Tooling / Timeline]
+- WARNING SIGN: [What was the earliest observable indicator this was happening?]
+"CAUSE:", "DOMAIN:" and "WARNING SIGN:" are literal labels in this protocol, not headings —
+keep them exactly as written.
+
+PRIORITY ASSESSMENT:
+After listing every cause, close by singling out three things:
+1. The 3 causes most LIKELY to be what actually happened, given the situation above.
+2. The 3 most PREVENTABLE causes — where action taken today would have made the most
+   difference.
+3. Any single point of failure that could have killed the rollout on its own.
 ```
 
+Note the substituted `DOMAIN` values. The template's six domains are the general-purpose default; where a project's real failure surfaces are known, naming them gets better coverage than the generic set. The label itself stays literal.
+
 ### Example 3: Technical Decision
 
+**Before Pre-Mortem:**
+"Review our database migration plan for risks."
+
+**After Pre-Mortem** (source material supplied):
 ```
-PROJECT:
-We are migrating our primary database from MySQL to PostgreSQL. Timeline:
-3 months. Team: 2 senior engineers part-time. We're running 2M daily
-active users with a 99.9% uptime SLA.
+You are conducting a pre-mortem on the project described below. The failure stated further
+down is settled fact, not a possibility — work backwards from it and explain why it happened.
+Do not hedge with "could," "might," or "may."
+
+SOURCE MATERIAL:
+[Paste the migration runbook, the current schema, and the rollback plan here]
+Use the material above as the factual basis for the work described below.
+
+PROJECT/DECISION:
+We are migrating our primary database from MySQL to PostgreSQL over a 3-month timeline. The
+team is 2 senior engineers working part-time on it. The system serves 2M daily active users
+under a 99.9% uptime SLA, and neither engineer has run a migration at this scale before.
 
 FAILURE ASSUMPTION:
-It is 4 months from now and the migration has failed. We experienced
-significant downtime, data integrity issues, or were forced to roll back.
-
-FAILURE ANALYSIS:
-10 specific technical and organizational failure causes.
-Cover: migration strategy, testing gaps, rollback planning,
-team knowledge gaps, operational issues, and unforeseen dependencies.
-For each: earliest warning sign.
-
-PRIORITY:
-The 3 most likely. The most preventable. Any single point of failure
-that could cause a full rollback or data loss.
+It is 4 months from now and the migration has completely and catastrophically failed. It did
+not achieve a clean cutover — we took significant downtime, hit data integrity problems, and
+were forced to roll back.
+
+FAILURE NARRATIVE:
+Begin by describing how that failure unfolded, in 2-3 sentences, in past tense from the
+perspective of someone looking back on it.
+
+FAILURE CAUSES:
+Then identify 10 specific reasons it failed, each stated as something that already went
+wrong. Cover migration strategy, testing gaps, rollback planning, team knowledge gaps,
+operational and on-call issues, and unforeseen dependencies. Give each cause three lines:
+- CAUSE: [What specifically went wrong — be specific, not generic]
+- DOMAIN: [Strategy / Testing / Rollback / Knowledge / Operations / Dependencies]
+- WARNING SIGN: [What was the earliest observable indicator this was happening?]
+"CAUSE:", "DOMAIN:" and "WARNING SIGN:" are literal labels in this protocol, not headings —
+keep them exactly as written.
+
+PRIORITY ASSESSMENT:
+After listing every cause, close by singling out three things:
+1. The 3 causes most LIKELY to be what actually happened, given the situation above.
+2. The 3 most PREVENTABLE causes — where action taken today would have made the most
+   difference.
+3. Any single point of failure that could have forced a full rollback or caused data loss
+   on its own.
 ```
 
 ## Best Use Cases
@@ -187,11 +296,12 @@ that could cause a full rollback or data loss.
 
 ## Quick Reference
 
-| Component | Purpose |
+| Template slot | Purpose |
 |-----------|---------|
-| Project Description | What's being analyzed |
-| Future Date | Time horizon |
-| Failure Framing | "Has already failed" (committed, not probabilistic) |
-| Domain Analysis | Dimensions to cover |
-| Warning Signs | Earliest observable indicators |
-| Priority Pass | Most likely + most preventable + single points of failure |
+| Opening paragraph | Declares the failure settled fact; bans "could / might / may" |
+| `SOURCE MATERIAL` | Optional plan or decision document to ground causes in; self-deleting |
+| `PROJECT/DECISION` | What's being analyzed, with team, timeline, resources, constraints |
+| `FAILURE ASSUMPTION` | Time horizon + "has already failed" + the goal it missed |
+| `FAILURE NARRATIVE` | 2-3 sentences, past tense, retrospective voice |
+| `FAILURE CAUSES` | 8-12 causes, each as CAUSE / DOMAIN / WARNING SIGN |
+| `PRIORITY ASSESSMENT` | Most likely + most preventable + single points of failure |

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

@@ -2,12 +2,14 @@
 
 ## Overview
 
-RACE (Role, Action, Context, Expectation) is a medium-complexity framework that sits between RTF's simplicity and CO-STAR's richness. It adds two critical improvements over RTF: situational context (missing from RTF) and an explicit expectation of success (missing from both RTF and CTF). RACE is ideal when you need all four pillars — expertise framing, task clarity, background, and a defined success bar — without the full overhead of CO-STAR or RISEN.
+RACE (Role, Action, Context, Expectation) is a medium-complexity framework that sits between RTF's simplicity and CO-STAR's richness. It adds two critical improvements over RTF: situational context (missing from RTF) and an explicit expectation of success (missing from both RTF and CTF). RACE is ideal when you need all four pillars — expertise framing, task clarity, background, and a defined success bar — without the full overhead of CO-STAR or RISEN. Section headers are stripped at emission, so a RACE prompt lands as a flat block — a role sentence, an action sentence, a paragraph of context, and a success-bar statement — preceded by an optional source-material block whenever the task applies to an artifact the user already has.
+
+**Origin:** No single documented originator. RACE is a community prompt-engineering convention documented in practitioner guides (e.g. fvivas.com, 20 April 2025) with no attributed creator, and does not appear in any peer-reviewed prompting survey. **Not to be confused with** the RACE digital-marketing planning model (Reach, Act, Convert, Engage), created by Dave Chaffey of Smart Insights in 2010 — an unrelated marketing framework that shares only the acronym.
 
 ## Components
 
 ### R - Role
-**Purpose:** Define the expertise or persona needed for the task.
+**Purpose:** Define the expertise or persona needed for the task. Written as a complete sentence — usually beginning "You are…" — so it still reads as a persona assignment once the `ROLE` header is stripped.
 
 **Questions to Ask:**
 - What expertise is required?
@@ -15,12 +17,12 @@ RACE (Role, Action, Context, Expectation) is a medium-complexity framework that
 - What level of knowledge is assumed?
 
 **Examples:**
-- "You are a senior backend engineer..."
-- "Act as an experienced UX designer..."
-- "You are a plain-language technical writer..."
+- "You are a senior backend engineer familiar with REST conventions."
+- "Act as an experienced UX designer who works on consumer onboarding flows."
+- "You are a plain-language technical writer for developer documentation."
 
 ### A - Action
-**Purpose:** State what needs to be done — the task.
+**Purpose:** State what needs to be done — the task — as one complete imperative sentence. When source material is supplied above, refer to it as "the … above," never "described below": the artifact precedes the action once emitted, so a downward reference would dangle.
 
 **Questions to Ask:**
 - What exactly needs to happen?
@@ -28,12 +30,12 @@ RACE (Role, Action, Context, Expectation) is a medium-complexity framework that
 - What's the scope?
 
 **Examples:**
-- "Review this API design for consistency..."
-- "Write user onboarding copy for..."
-- "Identify the top 3 risks in..."
+- "Review the REST API design above for consistency, usability, and potential issues."
+- "Write the copy for a 3-screen onboarding flow for our task management app."
+- "Identify the top 5 risks in the migration plan above."
 
 ### C - Context
-**Purpose:** Provide the situational background needed to calibrate the output.
+**Purpose:** Provide the situational background needed to calibrate the output. It fills as a self-contained paragraph and survives header stripping on its own, so long as it reads as description of a situation rather than a bare label.
 
 **Questions to Ask:**
 - What's the situation?
@@ -42,12 +44,12 @@ RACE (Role, Action, Context, Expectation) is a medium-complexity framework that
 - What does the audience/recipient need?
 
 **Examples:**
-- "This is a public API used by third-party developers who expect stable contracts..."
-- "The users are first-time app users who may be unfamiliar with our terminology..."
-- "This is for a Series A startup with a 3-person engineering team..."
+- "This is a public API used by third-party developers who expect stable contracts."
+- "The users are first-time app users who may be unfamiliar with our terminology."
+- "This is for a Series A startup with a 3-person engineering team."
 
 ### E - Expectation
-**Purpose:** Define what a successful output looks like — the quality bar.
+**Purpose:** Define what a successful output looks like — the quality bar. Phrase it as a complete statement about the result, not a bare fragment: a phrase like "prioritized list" dangles once the `EXPECTATION` header is deleted, whereas "The review should prioritize the highest-severity issues" still names the standard.
 
 **Questions to Ask:**
 - What does success look like?
@@ -56,43 +58,86 @@ RACE (Role, Action, Context, Expectation) is a medium-complexity framework that
 - Any specific requirements for the output?
 
 **Examples:**
-- "Should prioritize breaking changes and security risks over style issues"
-- "Should be conversational, not instructional — guide rather than command"
-- "Should fit in a single Confluence page, scannable with headers"
+- "The review should prioritize breaking changes and security risks over style issues."
+- "The copy should be conversational, not instructional — guiding rather than commanding."
+- "The output should fit on a single Confluence page, scannable with headers."
 
 ## Template Structure
 
-```
-ROLE: [Expertise or persona]
-
-ACTION: [What needs to be done]
+Section headers are stripped at emission, so every slot's meaning is carried by the prose
+around and inside it rather than by the header above it. Role fills as a "You are…"
+sentence and Context as a self-contained paragraph, so both stand on their own; Action must
+be a complete imperative sentence, and Expectation must be phrased as a statement about the
+result, because neither can lean on a header once emitted.
 
-CONTEXT: [Background, situation, constraints]
-
-EXPECTATION: [What a good result looks like]
+```
+SOURCE MATERIAL:
+[OPTIONAL — include only if this task operates on something the user already has.
+If so, emit a literal paste instruction naming the specific artifact, e.g. "[Paste the REST API design here]"
+or "[Paste the migration plan here]" — then one line of prose tying it to what follows,
+e.g. "The material above is what the task below applies to."
+When this section is used, word ACTION to refer to the material ABOVE ("the migration plan above"),
+never "described below" — the artifact precedes it and a downward reference would dangle.
+If the task generates entirely from scratch, omit this section — do not emit an empty placeholder.]
+
+ROLE:
+[Define the expertise or persona needed — who should do this task and at what level]
+
+ACTION:
+[State clearly what needs to be done — the task and deliverable]
+
+CONTEXT:
+[Provide the situational background:
+- What's the current state / situation?
+- Who is the audience or recipient of the output?
+- Any relevant constraints or prior decisions?
+- What has already been done?]
+
+EXPECTATION:
+[Define what a successful output looks like:
+- Format and structure requirements
+- Quality bar or success criteria
+- What should be prioritized
+- Length or scope constraints]
 ```
 
+`SOURCE MATERIAL` is a fifth block in a four-letter acronym, and it carries no letter
+because it is optional. When RACE is pointed at something that already exists — an API
+design, a migration plan, a module — that artifact is pasted here, and the Action refers to
+it as "the … above." The upward reference is deliberate: the artifact precedes the Action
+once headers are gone, so any "described below" phrasing would point past the end of the
+prompt. Delete the block and the sentence beneath it whenever the task generates from
+scratch.
+
 ## Complete Examples
 
+Every example below is shown in emitted form: each slot carries its own role in prose.
+Read the headers as scaffolding that will be deleted — the examples are written so that
+nothing is lost when it is.
+
 ### Example 1: API Review
 
 **Before RACE:**
 "Review my API design."
 
-**After RACE:**
+**After RACE** (source material supplied):
 ```
+SOURCE MATERIAL:
+[Paste the REST API design here]
+The material above is what the task below applies to.
+
 ROLE: You are a senior backend engineer with API design experience, familiar with
 REST conventions and developer experience best practices.
 
-ACTION: Review this REST API design for consistency, usability, and potential issues.
+ACTION: Review the REST API design above for consistency, usability, and potential issues.
 
 CONTEXT: This is a public API that will be used by third-party developers. We are
 about to publish v1 and changes after launch will be breaking. The team is small
 (3 engineers) and we have not done a formal API review before.
 
 EXPECTATION: Prioritize issues by severity (breaking vs. cosmetic). Flag anything
-that would frustrate external developers or cause versioning headaches. Format as
-a prioritized list with issue, reason, and suggested fix for each.
+that would frustrate external developers or cause versioning headaches. Format the
+result as a prioritized list with issue, reason, and suggested fix for each.
 ```
 
 ### Example 2: Onboarding Copy
@@ -100,7 +145,8 @@ a prioritized list with issue, reason, and suggested fix for each.
 **Before RACE:**
 "Write onboarding text for our app."
 
-**After RACE:**
+**After RACE** (no source material — the copy is written from scratch, so the
+`SOURCE MATERIAL` block and the sentence below it are both deleted):
 ```
 ROLE: You are a UX writer who specializes in onboarding flows for consumer apps.
 
@@ -112,8 +158,8 @@ an account before seeing this onboarding. The screens are: (1) value prop, (2)
 import/create first task, (3) invite team.
 
 EXPECTATION: Each screen needs a headline (5 words max), one-sentence subhead, and
-CTA button label. Tone: encouraging, simple, no jargon. The copy should build
-momentum toward the first meaningful action.
+CTA button label. Keep the tone encouraging, simple, and jargon-free, and let the
+copy build momentum toward the first meaningful action.
 ```
 
 ### Example 3: Risk Assessment
@@ -121,12 +167,16 @@ momentum toward the first meaningful action.
 **Before RACE:**
 "What are the risks of this approach?"
 
-**After RACE:**
+**After RACE** (source material supplied):
 ```
+SOURCE MATERIAL:
+[Paste the proposed database migration plan here]
+The material above is what the task below applies to.
+
 ROLE: You are a software architect with experience in distributed systems and
 enterprise migrations.
 
-ACTION: Identify the top risks in the proposed database migration plan described below.
+ACTION: Identify the top risks in the database migration plan above.
 
 CONTEXT: We are migrating from a monolithic PostgreSQL database to a microservices
 architecture with separate databases per service. Timeline is 6 months. Team has
@@ -143,20 +193,25 @@ violate the SLA or create data integrity issues as critical.
 **Before RACE:**
 "Document this module."
 
-**After RACE:**
+**After RACE** (source material supplied):
 ```
+SOURCE MATERIAL:
+[Paste the authentication module source here]
+The material above is what the task below applies to.
+
 ROLE: You are a technical writer who writes developer documentation for open-source
 libraries.
 
-ACTION: Write documentation for the authentication module described below.
+ACTION: Write documentation for the authentication module above.
 
 CONTEXT: This is an open-source library used by developers integrating our platform.
 Readers are competent developers but unfamiliar with our specific auth flow. The
 docs will live on our developer portal alongside API reference docs.
 
-EXPECTATION: Include: overview paragraph, when-to-use section, installation snippet,
-quickstart code example, and a table of configuration options. Should be completable
-in one reading session (under 500 words). Use clear headings and real code examples.
+EXPECTATION: Include an overview paragraph, a when-to-use section, an installation
+snippet, a quickstart code example, and a table of configuration options. It should be
+completable in one reading session (under 500 words), with clear headings and real
+code examples.
 ```
 
 ## Best Use Cases

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

@@ -4,7 +4,7 @@
 
 Reverse Chain-of-Thought (RCoT) is a verification framework that catches reasoning errors by working backwards. After generating an initial answer using standard reasoning, the model is instructed to reconstruct what the original question must have been — given only its answer. The reconstructed question is then compared condition-by-condition against the actual question to identify overlooked conditions, misinterpreted constraints, and logical gaps. Discrepancies found in this cross-check feed back into a corrected response.
 
-**Research basis:** Documented on LearnPrompting.org and Mirascope; grounded in academic backward reasoning literature (RCoT paper; FOBAR: forward-backward reasoning). Related work: "Reversal of Thought" (ACL 2025, arXiv 2410.12323); "Reverse Thinking Makes LLMs Stronger Reasoners" (NAACL 2025).
+**Research basis:** Xue et al., "RCoT: Detecting and Rectifying Factual Inconsistency in Reasoning by Reversing Chain-of-Thought" (arXiv 2305.11499, 2023; unreviewed preprint, no venue), which reports gains over standard CoT on seven arithmetic reasoning datasets (§4.1; +3.1 on GSM8K and +5.0 on Date, zero-shot ChatGPT). What ships here is an ablated variant: the paper's Problem Decomposition stage — which converts both the original and the reconstructed question into explicit condition lists and then runs pairwise *entailment* checks between them — is not implemented, and the Condition Cross-Check below substitutes a direct question-to-question comparison with surface set-difference, which §3.2 names as the weaker baseline the paper was built to replace ("such comparisons usually fail to produce high-quality detection results"). Read the reported gains as evidence for the paper's full pipeline, not for the simplified form documented here and on LearnPrompting.org and Mirascope; FOBAR (forward-backward reasoning), "Reversal of Thought" (ACL 2025, arXiv 2410.12323), and "Reverse Thinking Makes LLMs Stronger Reasoners" (NAACL 2025) are adjacent backward-reasoning methods rather than grounding for this variant.
 
 ## Why RCoT Works