@ckelsoe/prompt-architect 3.0.0

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

@@ -0,0 +1,243 @@
+# RACE Framework
+
+## 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.
+
+## Components
+
+### R - Role
+**Purpose:** Define the expertise or persona needed for the task.
+
+**Questions to Ask:**
+- What expertise is required?
+- What viewpoint should the AI take?
+- 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..."
+
+### A - Action
+**Purpose:** State what needs to be done — the task.
+
+**Questions to Ask:**
+- What exactly needs to happen?
+- What is the deliverable?
+- What's the scope?
+
+**Examples:**
+- "Review this API design for consistency..."
+- "Write user onboarding copy for..."
+- "Identify the top 3 risks in..."
+
+### C - Context
+**Purpose:** Provide the situational background needed to calibrate the output.
+
+**Questions to Ask:**
+- What's the situation?
+- What's already happened?
+- What constraints apply?
+- 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..."
+
+### E - Expectation
+**Purpose:** Define what a successful output looks like — the quality bar.
+
+**Questions to Ask:**
+- What does success look like?
+- What format should the output take?
+- What should be true of a good result?
+- 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"
+
+## Template Structure
+
+```
+ROLE: [Expertise or persona]
+
+ACTION: [What needs to be done]
+
+CONTEXT: [Background, situation, constraints]
+
+EXPECTATION: [What a good result looks like]
+```
+
+## Complete Examples
+
+### Example 1: API Review
+
+**Before RACE:**
+"Review my API design."
+
+**After RACE:**
+```
+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.
+
+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.
+```
+
+### Example 2: Onboarding Copy
+
+**Before RACE:**
+"Write onboarding text for our app."
+
+**After RACE:**
+```
+ROLE: You are a UX writer who specializes in onboarding flows for consumer apps.
+
+ACTION: Write the copy for a 3-screen onboarding flow for our task management app.
+
+CONTEXT: Users are downloading the app after seeing a social ad. Many are switching
+from pen/paper or spreadsheets. They are not tech-savvy. They've already created
+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.
+```
+
+### Example 3: Risk Assessment
+
+**Before RACE:**
+"What are the risks of this approach?"
+
+**After RACE:**
+```
+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.
+
+CONTEXT: We are migrating from a monolithic PostgreSQL database to a microservices
+architecture with separate databases per service. Timeline is 6 months. Team has
+strong SQL skills but limited microservices experience. The system handles financial
+transactions and has a 99.9% uptime SLA.
+
+EXPECTATION: List the top 5 risks ranked by likelihood × impact. For each: name,
+description (2 sentences), and one mitigation approach. Flag any risks that could
+violate the SLA or create data integrity issues as critical.
+```
+
+### Example 4: Code Documentation
+
+**Before RACE:**
+"Document this module."
+
+**After RACE:**
+```
+ROLE: You are a technical writer who writes developer documentation for open-source
+libraries.
+
+ACTION: Write documentation for the authentication module described below.
+
+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.
+```
+
+## Best Use Cases
+
+1. **Technical Reviews**
+   - Code reviews with context
+   - Architecture assessments
+   - Design critiques
+
+2. **Content with Expertise**
+   - Technical documentation
+   - UX/product copy
+   - Expert analysis
+
+3. **Contextual Analysis**
+   - Risk assessments
+   - Recommendations with constraints
+   - Prioritization tasks
+
+4. **When RTF Isn't Enough**
+   - Role alone doesn't capture enough
+   - Background materially changes the output
+   - "What does good look like?" is unclear
+
+## Selection Criteria
+
+**Choose RACE when:**
+- ✅ Role/expertise matters
+- ✅ Background context is needed
+- ✅ Success criteria need to be explicit
+- ✅ RTF feels too thin but CO-STAR feels too heavy
+- ✅ Task has both "who" and "why" dimensions
+
+**Avoid RACE when:**
+- ❌ No role/expertise needed → use CTF or APE
+- ❌ Audience, tone, style are critical → use CO-STAR
+- ❌ Complex methodology required → use RISEN
+- ❌ Transforming existing content → use BAB
+- ❌ Ultra-simple task → use APE or RTF
+
+## RACE vs. RTF vs. CO-STAR
+
+| | APE | RTF | RACE | CO-STAR |
+|---|---|---|---|---|
+| Role | No | Yes | Yes | Implicit |
+| Context | Minimal | No | Yes | Yes (rich) |
+| Expectation | Yes | Partial (Format) | Yes (explicit) | Yes (Response) |
+| Audience/Tone | No | No | No | Yes |
+| Complexity | Minimal | Low | Medium | High |
+| Best for | One-liners | Format-driven | Expert + context | Full content |
+
+**Rule of thumb:**
+- No role needed, quick → APE
+- Role matters, no context → RTF
+- Role + context + explicit outcome → RACE
+- Full content with audience/tone → CO-STAR
+
+## Common Mistakes
+
+1. **Weak Expectation**
+   - "Good quality" is not an expectation
+   - Define format, length, priority, tone, or success criteria specifically
+
+2. **Context Overload**
+   - Context should be background, not instructions
+   - Instructions belong in Action
+   - If Context is longer than Role + Action combined, consider CO-STAR
+
+3. **Skipping Role**
+   - Even when obvious, Role calibrates expertise level and perspective
+   - Don't skip it
+
+4. **Confusing Action and Expectation**
+   - Action = what to do
+   - Expectation = what a good result looks like after it's done
+
+## Quick Reference
+
+| Component | Focus | Key Question |
+|-----------|-------|--------------|
+| Role | Expertise | "Who should do this?" |
+| Action | Task | "What needs to be done?" |
+| Context | Background | "What's the situation?" |
+| Expectation | Success bar | "What does good look like?" |

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

@@ -0,0 +1,203 @@
+# RCoT (Reverse Chain-of-Thought)
+
+## Overview
+
+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).
+
+## Why RCoT Works
+
+Forward reasoning errors typically come from:
+- Overlooking a condition in the question
+- Misinterpreting a constraint
+- Assuming something that wasn't stated
+
+When the model reconstructs "what question would produce my answer?", it must articulate what conditions its reasoning implicitly assumed. Comparing these implicit assumptions against the actual question reveals the gaps.
+
+**Limitation:** RCoT catches overlooking and misinterpretation errors well, but is less effective at catching hallucinated facts (fabricated information that is internally consistent) or pure arithmetic errors.
+
+## Components
+
+### Initial Generation
+**Purpose:** Standard reasoning pass — generate an initial answer using Chain-of-Thought or direct reasoning. This is the answer to verify.
+
+### Question Reconstruction
+**Purpose:** Given only the answer (not the original question), reconstruct what the question must have been. The model must articulate the implicit conditions its reasoning assumed.
+
+**Trigger:** *"Looking only at the answer below, reconstruct the question that would produce this answer. List every condition, constraint, and piece of information the question must have contained."*
+
+### Condition Cross-Check
+**Purpose:** Compare the reconstructed question's conditions against the actual question's conditions. List any conditions that: appear in the actual question but not the reconstruction (overlooked), appear in the reconstruction but not the actual question (assumed/hallucinated), or are present in both but interpreted differently.
+
+### Correction
+**Purpose:** Feed the identified discrepancies back to the model to generate a corrected answer that addresses what was missed.
+
+## Template Structure
+
+```
+STEP 1 — INITIAL ANSWER:
+Answer the following question using step-by-step reasoning.
+Show your work.
+
+QUESTION: [Your question]
+
+STEP 2 — QUESTION RECONSTRUCTION:
+Looking only at the answer above (ignore the original question),
+reconstruct the question that would produce this answer.
+List every condition, constraint, and piece of information
+the question must have contained.
+
+RECONSTRUCTED QUESTION: [AI generates this]
+
+STEP 3 — CROSS-CHECK:
+Now compare the reconstructed question to the original question.
+Identify:
+- Conditions in the ORIGINAL question but MISSING from your reconstruction
+  (these are conditions you overlooked in your reasoning)
+- Conditions in your RECONSTRUCTION but NOT in the original question
+  (these are assumptions you made that weren't stated)
+- Conditions present in both but interpreted differently
+
+STEP 4 — CORRECTION:
+If discrepancies were found, generate a corrected answer that addresses
+every condition in the original question. If no discrepancies, confirm
+the original answer is correct.
+```
+
+## Complete Examples
+
+### Example 1: Multi-Condition Logic Problem
+
+```
+STEP 1 — INITIAL ANSWER:
+A company has 3 departments: Engineering, Marketing, and Sales.
+Engineering has 2x as many employees as Marketing.
+Sales has 5 fewer employees than Engineering.
+Marketing has 10 employees.
+How many total employees does the company have?
+
+Show your reasoning step by step.
+
+STEP 2 — QUESTION RECONSTRUCTION:
+Given only this answer: "45 employees total"
+What conditions must the question have contained?
+List every constraint implied by this answer.
+
+STEP 3 — CROSS-CHECK:
+Compare your reconstructed conditions to the actual question.
+What did you overlook? What did you assume that wasn't stated?
+
+STEP 4 — CORRECTION:
+If your cross-check found discrepancies, recalculate with all
+conditions properly applied.
+```
+
+### Example 2: Complex Requirement Analysis
+
+```
+STEP 1:
+Given these requirements: [paste requirements]
+Which of the following implementation approaches satisfies all of them?
+[List options]
+
+[AI generates initial recommendation]
+
+STEP 2 — RECONSTRUCTION:
+Looking only at the recommendation above, reconstruct the requirements
+that must have been in the original question.
+
+STEP 3 — CROSS-CHECK:
+Compare your reconstructed requirements to the actual requirements above.
+Which requirements did you not account for in your recommendation?
+
+STEP 4 — CORRECTION:
+Update the recommendation to satisfy the overlooked requirements.
+```
+
+### Example 3: Multi-Step Technical Analysis
+
+```
+STEP 1:
+[Complex technical question with multiple constraints]
+Analyze and recommend an approach.
+
+[AI generates initial analysis]
+
+STEP 2 — RECONSTRUCTION:
+From the analysis above only, list every constraint and requirement
+the original question must have specified.
+
+STEP 3 — CROSS-CHECK:
+Compare against the actual question. What was overlooked?
+What was assumed without basis?
+
+STEP 4 — CORRECTION:
+Revise the analysis to address everything found in Step 3.
+```
+
+## Abbreviated Version (Single Prompt)
+
+For simpler use cases, collapse all steps into one compound prompt:
+
+```
+Answer the following question step by step: [QUESTION]
+
+Then, working only from your answer (not re-reading the question),
+reconstruct what the question must have contained.
+
+Compare your reconstruction to the actual question. Identify any
+conditions you overlooked or misinterpreted.
+
+If discrepancies exist, provide a corrected answer.
+```
+
+## Best Use Cases
+
+1. **Multi-Condition Logic Problems**
+   - Questions with several constraints that must all be satisfied
+   - Eligibility determination, scheduling, constraint satisfaction
+
+2. **Complex Technical Requirements**
+   - Architecture decisions with multiple requirements
+   - Code that must satisfy several constraints simultaneously
+
+3. **Legal/Financial/Medical Analysis**
+   - Multi-clause documents where missing one condition is costly
+   - Any domain where overlooked conditions cause errors
+
+4. **Verification Layer in Pipelines**
+   - Add RCoT as a verification step after any complex reasoning
+   - Especially useful before high-stakes decisions
+
+## Selection Criteria
+
+**Choose RCoT when:**
+- ✅ The question has multiple conditions/constraints that could be overlooked
+- ✅ You want to verify that reasoning addressed everything
+- ✅ Previous answers to similar questions have missed conditions
+- ✅ Domain is high-stakes and overlooked conditions are costly
+
+**Avoid when:**
+- ❌ Simple question with one condition → overhead not worth it
+- ❌ Verification needs involve factual accuracy → CRITIC (tool-grounded) is better
+- ❌ Arithmetic verification → PS+ or explicit calculation check is faster
+- ❌ Creative or generative task → no "conditions to miss"
+
+## RCoT vs. Other Reasoning Frameworks
+
+| | RCoT | Chain of Thought | Plan-and-Solve | Step-Back |
+|---|---|---|---|---|
+| Direction | Forward then backward (verification) | Forward only | Forward with planning | Abstract then forward |
+| Best for | Catching overlooked conditions | Linear reasoning | Numerical calculation | Principle-grounded reasoning |
+| Adds | Verification pass | None | Planning + variable extraction | Abstraction step |
+| Failure mode | Doesn't catch hallucinations | Errors compound | Still needs correct variables | Step-back too vague |
+
+## Quick Reference
+
+| Step | Purpose |
+|------|---------|
+| Initial Answer | Generate reasoning (forward) |
+| Reconstruction | "What question produced this?" (backward) |
+| Cross-Check | Compare conditions: original vs. reconstructed |
+| Correction | Fix what was overlooked or misinterpreted |