@ckelsoe/prompt-architect 3.3.1 → 3.4.0

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

@@ -2,14 +2,14 @@
 
 ## Overview
 
-CTF is a simple 3-component framework focused on situational context, task clarity, and output format. It is ideal for tasks where background/situation is more important than AI persona framing, and the primary concern is getting a clearly defined output from a well-understood context.
+CTF is a simple 3-component framework focused on situational context, task clarity, and output format. It is ideal for tasks where background/situation is more important than AI persona framing, and the primary concern is getting a clearly defined output from a well-understood context. Section headers are stripped when the prompt is emitted, so a CTF prompt lands as a short flat block — a paragraph of situation, a sentence naming the task, and a format specification — preceded by an optional source-material block whenever the task operates on an artifact that already exists.
 
 **Origin:** No single documented originator. CTF appears in the community framework literature as a variant of RTF, with Context substituted for Role, documented alongside it in unattributed practitioner listings from 2024 onward (e.g. fvivas.com, 15 March 2024). No academic treatment; absent from The Prompt Report (arXiv 2406.06608).
 
 ## Components
 
 ### C - Context
-**Purpose:** Describe the situation, background, or circumstances surrounding the task.
+**Purpose:** Describe the situation, background, or circumstances surrounding the task. It fills naturally as a self-contained paragraph of situational prose, so it survives header stripping on its own — but keep it descriptive narrative, not a bare label like "legacy code," so the paragraph still reads as a situation once the `CONTEXT` header is gone.
 
 **Questions to Ask:**
 - What is the current situation?
@@ -19,12 +19,12 @@ CTF is a simple 3-component framework focused on situational context, task clari
 - What constraints or circumstances apply?
 
 **Examples:**
-- "We are mid-sprint and the client has changed the acceptance criteria for the login flow..."
-- "I'm a junior developer onboarding to a legacy Python codebase with no documentation..."
-- "Our team writes internal status reports weekly and we need to standardize the format..."
+- "We are mid-sprint and the client has revised the acceptance criteria in the requirements doc above; the dev team has not been told yet."
+- "I am a junior developer onboarding to the legacy Python module above, which nobody has documented."
+- "Our team writes internal status reports weekly and the format drifts every time, so we want one reusable structure."
 
 ### T - Task
-**Purpose:** State exactly what needs to be done.
+**Purpose:** State exactly what needs to be done, as one complete imperative sentence. Nothing else in a CTF prompt states the task, so once the `TASK` header is stripped a bare noun phrase ("a summary") leaves the emitted prompt with no instruction in it.
 
 **Questions to Ask:**
 - What exactly needs to be done?
@@ -32,12 +32,12 @@ CTF is a simple 3-component framework focused on situational context, task clari
 - What's the core action?
 
 **Examples:**
-- "Write a summary of the changed requirements for the team..."
-- "Explain what this function does in plain language..."
-- "Create a template for our weekly status report..."
+- "Summarize the changed requirements in the doc above for the development team."
+- "Explain in plain language what the function above does."
+- "Create a reusable weekly status report template the team can fill out in under 10 minutes."
 
 ### F - Format
-**Purpose:** Specify how the output should be structured.
+**Purpose:** Specify how the output should be structured. Phrase it as an instruction about the output rather than a bare descriptor — a fragment like "markdown table" dangles once the `FORMAT` header is deleted, whereas "Provide the output as a markdown table" still reads as a directive.
 
 **Questions to Ask:**
 - What format should the output take?
@@ -46,46 +46,80 @@ CTF is a simple 3-component framework focused on situational context, task clari
 - Any specific formatting requirements?
 
 **Examples:**
-- "Provide as a markdown table..."
-- "Format as a bulleted list under three headings..."
-- "Write as a concise paragraph, 100 words max..."
+- "Provide the output as a markdown table."
+- "Format the answer as a bulleted list under three headings."
+- "Write the answer as a single paragraph of 100 words or fewer."
 
 ## 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. Context is a self-contained
+paragraph and survives on its own; Task must be a complete imperative sentence, and Format
+must be phrased as an instruction about the output, because neither has a header to lean on
+once emitted.
+
 ```
+SOURCE MATERIAL:
+[Optional — include only if this task operates on material you already have. Paste the
+specific artifact here and name it in this line, e.g. "Paste the legacy authentication
+function here", "Paste the revised requirements doc here" — the artifact itself, not a
+description of it. If this task generates from scratch, delete this bracketed block along
+with the sentence directly below it.]
+Use the material above as the basis for the task described below.
+
 CONTEXT:
-[Situation, background, circumstances]
+[Describe the situation, background, or circumstances surrounding this task.
+Include relevant details like: current state, constraints, what's already been done,
+why this is needed, and any important background the AI should know.]
 
 TASK:
-[What needs to be done]
+[State clearly and specifically what needs to be done. Be explicit about the deliverable.]
 
 FORMAT:
-[How output should be structured]
+[Specify exactly how the output should be structured:
+- Overall format (document, code, list, table, etc.)
+- Required sections or components
+- Length constraints
+- Style requirements
+- Any specific formatting rules]
 ```
 
+`SOURCE MATERIAL` is a fourth block in a three-letter acronym, and it carries no letter
+because it is optional. CTF is often pointed at something that already exists — a legacy
+function, a revised requirements doc, a draft — and that artifact is pasted here and
+referred to as "the … above" from inside the Task. Delete the block and the sentence
+beneath it whenever the task generates something 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: Requirement Change Summary
 
 **Before CTF:**
 "Summarize the new requirements."
 
-**After CTF:**
+**After CTF** (source material supplied):
 ```
+SOURCE MATERIAL:
+[Paste the client's revised login-flow requirements here]
+Use the material above as the basis for the task described below.
+
 CONTEXT:
 We are in sprint 3 of a 6-sprint project. The client just revised the login flow
-requirements: they now want SSO via Google instead of email/password. The dev team
-hasn't been told yet and we need to communicate this clearly without causing panic.
+requirements in the document above: they now want SSO via Google instead of
+email/password. The dev team hasn't been told yet and we need to communicate this
+clearly without causing panic.
 
 TASK:
-Write a brief summary of the requirement change to share with the development team
+Write a brief summary of the requirement change above to share with the development team
 in Slack.
 
 FORMAT:
-- 3-5 bullet points
-- Plain language, no jargon
-- End with a single action item
-- Keep total under 150 words
+Format the summary as 3-5 bullet points in plain language with no jargon, ending with a
+single action item, and keep the total under 150 words.
 ```
 
 ### Example 2: Code Explanation
@@ -93,21 +127,24 @@ FORMAT:
 **Before CTF:**
 "Explain this code."
 
-**After CTF:**
+**After CTF** (source material supplied):
 ```
+SOURCE MATERIAL:
+[Paste the undocumented legacy authentication function here]
+Use the material above as the basis for the task described below.
+
 CONTEXT:
-I'm a junior developer new to this codebase. The function below is from a legacy
+I'm a junior developer new to this codebase. The function above is from a legacy
 authentication module that nobody has documented. I need to understand it before
 refactoring it next week.
 
 TASK:
-Explain what this function does, why each section exists, and flag any potential
+Explain what the function above does, why each section exists, and flag any potential
 issues I should know before touching it.
 
 FORMAT:
-- Short plain-language summary (2-3 sentences)
-- Line-by-line breakdown as a numbered list
-- Potential issues section at the end (bullet points)
+Open with a short plain-language summary of 2-3 sentences, then give a line-by-line
+breakdown as a numbered list, and end with a bulleted "Potential issues" section.
 ```
 
 ### Example 3: Template Creation
@@ -115,7 +152,8 @@ FORMAT:
 **Before CTF:**
 "Create a status report template."
 
-**After CTF:**
+**After CTF** (no source material — the template is designed from scratch, so the
+`SOURCE MATERIAL` block and the sentence below it are both deleted):
 ```
 CONTEXT:
 Our team of 6 engineers sends weekly status reports to a non-technical product
@@ -126,11 +164,9 @@ TASK:
 Create a weekly status report template that balances completeness with brevity.
 
 FORMAT:
-Markdown template with:
-- Section headers with fill-in placeholders
-- Brief instruction comment under each header
-- Total estimated fill-in time: under 10 minutes
-- Length when filled: 200-300 words
+Produce a markdown template with section headers, a fill-in placeholder under each header,
+and a brief instruction comment beneath it. Aim for under 10 minutes of fill-in time and a
+filled length of 200-300 words.
 ```
 
 ## Best Use Cases
@@ -170,7 +206,7 @@ Markdown template with:
 - ❌ Audience and tone are critical (use CO-STAR)
 - ❌ Multi-step process with methodology needed (use RISEN)
 - ❌ Explicit dos/don'ts required (use TIDD-EC)
-- ❌ Input→output transformation (use RISE — the Role/Input/Steps/Expectation form)
+- ❌ Input→output transformation (use RISE-IE — the Role/Input/Steps/Expectation form)
 
 ## CTF vs RTF
 

package/skills/prompt-architect/references/frameworks/devils-advocate.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Devil's Advocate Prompting instructs the AI to generate the strongest possible case *against* a position, plan, decision, or idea — not a balanced view, not a straw man, but the most forceful and substantive opposing argument possible. Named after the historical role in Catholic canonization proceedings where someone was appointed specifically to argue against sainthood, it is the framework for deliberately attacking your own thinking to find weaknesses before others do.
+Devil's Advocate Prompting instructs the AI to generate the strongest possible case *against* a position, plan, decision, or idea — not a balanced view, not a straw man, but the most forceful and substantive opposing argument possible. Named after the historical role in Catholic canonization proceedings where someone was appointed specifically to argue against sainthood, it is the framework for deliberately attacking your own thinking to find weaknesses before others do. A complete Devil's Advocate prompt emits as an opening instruction paragraph that establishes the adversarial frame, followed by the position under attack, an optional supporting document, and the attack directives — the section headers are stripped at emission, so each block is written to carry its own meaning in prose rather than lean on the header above it.
 
 **Research basis:** "Enhancing AI-Assisted Group Decision Making through LLM-Powered Devil's Advocate" (ACM IUI 2024, peer-reviewed). Key finding: AI devil's advocates arguing against AI recommendations (not just the user's position) produced more appropriate human reliance on AI. Related: Steelman (steelman.dylanamartin.com) implements a four-round structured adversarial argumentation framework.
 
@@ -17,13 +17,16 @@ Devil's Advocate Prompting instructs the AI to generate the strongest possible c
 ## Components
 
 ### Position Statement
-**Purpose:** The argument, plan, or decision to attack. State it clearly — the stronger the devil's advocate, the clearer the target must be.
+**Purpose:** The argument, plan, or decision to attack. State it clearly — the stronger the devil's advocate, the clearer the target must be. Write it as complete sentences: the opening instruction promises a case "against the following position," and once the `POSITION TO ATTACK` header is stripped, nothing else names what that position is, so the statement itself has to read as the thing being attacked.
+
+### Supporting Material (optional)
+**Purpose:** The proposal, design doc, or strategy memo that sets the position out in full. Supplying it lets the attack engage the position's actual claims and reasoning rather than the model's assumptions about a position of that description. The template's slot is optional and self-deleting: if there is nothing to paste, the bracketed block and the carrier sentence directly below it both come out. That carrier sentence — "Treat the document above as the detailed source of the position's claims, assumptions, and reasoning" — lets the pasted document stay a bare artifact by naming, in prose, what to do with it once its header is gone.
 
 ### Adversarial Instruction
-**Purpose:** Explicit instruction to be adversarial, not balanced. This is what makes it devil's advocate rather than a pros/cons analysis.
+**Purpose:** Explicit instruction to be adversarial, not balanced. This is what makes it devil's advocate rather than a pros/cons analysis. It ships as a list of standing imperatives, and the prohibition among them — "Do not acknowledge positives or offer a balanced view" — must survive into the emitted prompt as that explicit "Do not…" text. Per SKILL.md step 5, a restriction the user relies on cannot be left to a section header, because headers are stripped at emission; phrased as a standing imperative, the instruction carries with or without its header.
 
 ### Attack Dimensions
-**Purpose:** The specific dimensions to attack. Without these, critique stays superficial.
+**Purpose:** The specific dimensions to attack. Without these, critique stays superficial. They ship under a "Focus on:" carrier line as an enumerated list, so the dimensions read as directives once `ATTACK DIMENSIONS` is removed rather than as a bare heading over a list of nouns.
 
 **Common dimensions:**
 - **Assumptions**: What must be true for this to work? Attack each assumption.
@@ -34,71 +37,101 @@ Devil's Advocate Prompting instructs the AI to generate the strongest possible c
 - **Falsification criteria**: What evidence would prove this wrong?
 
 ### Severity Ranking (optional)
-**Purpose:** Rank identified weaknesses by how fatal they are. Separates show-stoppers from minor issues.
+**Purpose:** Rank identified weaknesses by how fatal they are. Separates show-stoppers from minor issues. When included it ships as a closing instruction — "After the full attack, list the THREE MOST FATAL flaws…" — phrased as a sequenced directive so the "do this last" ordering survives the header being stripped.
 
 ## 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 sets the adversarial frame, and it ships with the prompt. `POSITION TO ATTACK` comes first so the document that follows reads as backing an already-stated claim; the `SUPPORTING MATERIAL` block is optional and self-deleting, and its bracketed contents and the carrier sentence beneath them both come out whenever the position is stated inline with no document behind it.
+
 ```
-You are a rigorous devil's advocate. Your task is NOT to give a balanced
-view — your task is to generate the strongest possible case against the
-following [position / plan / decision / proposal].
+You are a rigorous devil's advocate. Your task is NOT to give a balanced view —
+your task is to generate the strongest possible case against the following position.
 
 POSITION TO ATTACK:
-[State the position, plan, or decision clearly]
+[State the position, plan, decision, or proposal clearly]
+
+SUPPORTING MATERIAL (optional):
+[Optional — paste the proposal, design doc, strategy memo, or other document
+that sets out this position here. If you have nothing to paste, delete this
+bracketed block and the sentence below it.]
+Treat the document above as the detailed source of the position's claims,
+assumptions, and reasoning.
 
 ATTACK INSTRUCTIONS:
-- Do not offer a balanced view or acknowledge positives
+- Do not acknowledge positives or offer a balanced view
 - Attack every assumption the position depends on
 - Identify every logical gap or unsupported claim
 - Surface every significant risk or failure mode
 - Point out what better alternatives are being ignored
-- Be as forceful and specific as possible — no vague objections
+- Be as forceful and specific as possible
 
 ATTACK DIMENSIONS:
-Focus your attack on: [select relevant dimensions]
-- Core assumptions (what must be true for this to work?)
-- Internal logic (where does the reasoning break down?)
-- Execution risks (what makes this fail in practice?)
-- Overlooked alternatives (what better options exist?)
-- [Add domain-specific dimensions as needed]
+Focus on:
+1. Core assumptions (what must be true for this to work?)
+2. Internal logic (where does the reasoning break down?)
+3. Execution risks (what makes this fail in practice?)
+4. Overlooked alternatives (what better options exist?)
+5. [Add domain-specific dimensions as needed]
 
 SEVERITY RANKING:
-After the attack, list the THREE MOST FATAL flaws — the ones that, if
-unaddressed, would cause this to fail regardless of execution quality.
+After the full attack, list the THREE MOST FATAL flaws — the ones that,
+if unaddressed, would cause this to fail regardless of execution quality.
 ```
 
 ## Complete Examples
 
+Every example below keeps the headers on the page for readability, but is written in emitted form beneath them: the opening instruction 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.
+
 ### Example 1: Architecture Decision
 
+**Before Devil's Advocate:**
+"Should we move to microservices?"
+
+**After Devil's Advocate** (supporting material supplied):
 ```
-You are a rigorous devil's advocate.
+You are a rigorous devil's advocate. Your task is NOT to give a balanced view —
+your task is to generate the strongest possible case against the following position.
 
 POSITION TO ATTACK:
-We should rewrite our monolithic Python backend as microservices.
-The motivation: our deployment pipeline is slow, different teams want
-to deploy independently, and we're seeing performance issues in the
-payments module.
+We should rewrite our monolithic Python backend as microservices. The motivation:
+our deployment pipeline is slow, different teams want to deploy independently, and
+we're seeing performance issues in the payments module.
+
+SUPPORTING MATERIAL:
+[Paste the migration RFC and the current deployment-pipeline metrics here]
+Treat the document above as the detailed source of the position's claims,
+assumptions, and reasoning.
 
 ATTACK INSTRUCTIONS:
-Generate the strongest possible case against this decision. Do not
-acknowledge any benefits. Attack the reasoning, assumptions, and plan.
+- Do not acknowledge positives or offer a balanced view
+- Attack every assumption the position depends on
+- Identify every logical gap or unsupported claim
+- Surface every significant risk or failure mode
+- Point out what better alternatives are being ignored
+- Be as forceful and specific as possible
 
 ATTACK DIMENSIONS:
-- Core assumptions about what microservices solve
-- Organizational and team readiness
-- Technical complexity being introduced
-- Whether the stated problems actually require microservices
-- Migration risks and the transition period
+Focus on:
+1. Core assumptions about what microservices actually solve
+2. Organizational and team readiness
+3. The technical complexity being introduced
+4. Whether the stated problems actually require microservices
+5. Migration risks and the transition period
 
 SEVERITY RANKING:
-End with the 3 most fatal flaws that would cause this to fail.
+After the full attack, list the THREE MOST FATAL flaws — the ones that,
+if unaddressed, would cause this to fail regardless of execution quality.
 ```
 
 ### Example 2: Business Strategy
 
+**Before Devil's Advocate:**
+"Is expanding to Europe a good idea?"
+
+**After Devil's Advocate** (no supporting material — the position is stated inline, so the optional block and its carrier sentence are both deleted):
 ```
-You are a rigorous devil's advocate.
+You are a rigorous devil's advocate. Your task is NOT to give a balanced view —
+your task is to generate the strongest possible case against the following position.
 
 POSITION TO ATTACK:
 We should expand to the European market in Q3. We have strong US NPS (72),
@@ -106,48 +139,61 @@ product-market fit with SMBs, and three European companies have expressed
 interest. We'll hire a country manager in the UK and use them as a beachhead.
 
 ATTACK INSTRUCTIONS:
-Argue forcefully against this expansion strategy. Be specific — use
-facts, numbers, and logic. No acknowledgment of positives.
+- Do not acknowledge positives or offer a balanced view
+- Attack every assumption the position depends on
+- Identify every logical gap or unsupported claim
+- Surface every significant risk or failure mode
+- Point out what better alternatives are being ignored
+- Be as forceful and specific as possible
 
 ATTACK DIMENSIONS:
-- Whether inbound interest indicates real market demand
-- Resource/runway requirements vs. what's being allocated
-- UK-as-beachhead strategy for EU expansion
-- Timing relative to our current US growth trajectory
-- GDPR, data residency, and regulatory readiness
+Focus on:
+1. Whether inbound interest indicates real market demand
+2. Resource and runway requirements versus what's being allocated
+3. The UK-as-beachhead strategy for EU expansion
+4. Timing relative to the current US growth trajectory
+5. GDPR, data residency, and regulatory readiness
 
 SEVERITY RANKING:
-The 3 most fatal flaws, in order.
+After the full attack, list the THREE MOST FATAL flaws — the ones that,
+if unaddressed, would cause this to fail regardless of execution quality.
 ```
 
 ### Example 3: Product Decision
 
+**Before Devil's Advocate:**
+"Should we build a mobile app?"
+
+**After Devil's Advocate** (supporting material supplied; severity ranking omitted — the opening paragraph already carries the adversarial frame, so a leaner variant still stands):
 ```
-You are a rigorous devil's advocate.
+You are a rigorous devil's advocate. Your task is NOT to give a balanced view —
+your task is to generate the strongest possible case against the following position.
 
 POSITION TO ATTACK:
-We should add a native mobile app to our web SaaS product. Our top users
-are asking for it, mobile usage of similar tools is growing, and a
-competitor just launched one.
+We should add a native mobile app to our web SaaS product. Our top users are asking
+for it, mobile usage of similar tools is growing, and a competitor just launched one.
 
-ATTACK DIMENSIONS:
-- Whether "top users asking" is representative demand
-- Resource cost vs. ROI for a 4-person engineering team
-- Whether mobile actually expands our TAM or just cannibalizes web
-- Competitor's mobile launch as a signal vs. noise
-- What we're giving up by doing this instead of something else
+SUPPORTING MATERIAL:
+[Paste the product one-pager and the top-user feature requests here]
+Treat the document above as the detailed source of the position's claims,
+assumptions, and reasoning.
 
-SEVERITY RANKING:
-3 most fatal flaws.
+ATTACK DIMENSIONS:
+Focus on:
+1. Whether "top users asking" is representative demand
+2. Resource cost versus ROI for a 4-person engineering team
+3. Whether mobile actually expands the TAM or just cannibalizes web
+4. The competitor's mobile launch as a signal versus noise
+5. What is given up by doing this instead of something else
 ```
 
 ### Example 4: Self-Attack (Devil's Advocate on AI Output)
 
-After receiving any AI recommendation:
+This one needs no template. It is a follow-up turn pasted after any AI recommendation, and "your own recommendation above" points at that prior output — which is the source material, already in place:
 ```
-Now argue forcefully against your own recommendation above. What are
-the strongest reasons it's wrong? What did you overlook? What
-assumptions did you make that may not hold? Be as critical as possible.
+Now argue forcefully against your own recommendation above. What are the
+strongest reasons it's wrong? What did you overlook? What assumptions did
+you make that may not hold? Be as critical as possible.
 ```
 
 ## Best Use Cases
@@ -200,7 +246,8 @@ assumptions did you make that may not hold? Be as critical as possible.
 
 | Component | Purpose |
 |-----------|---------|
-| Position Statement | What to attack |
+| Position Statement | What to attack, stated as complete sentences |
+| Supporting Material | Optional document behind the position; self-deleting |
 | Adversarial Instruction | Be forceful, not balanced |
 | Attack Dimensions | What aspects to critique |
 | Severity Ranking | The 3 most fatal flaws |