@ckelsoe/prompt-architect 3.2.2 → 3.4.0

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

@@ -2,12 +2,14 @@
 
 ## Overview
 
-APE (Action, Purpose, Expectation) is the most minimal structured prompt framework — even simpler than RTF or CTF. It is designed for ultra-quick, single-sentence or two-sentence prompts where adding more structure would be overkill. APE answers three essential questions in the fewest possible words: what to do, why it matters, and what success looks like.
+APE (Action, Purpose, Expectation) is the most minimal structured prompt framework — even simpler than RTF or CTF. It is designed for ultra-quick, self-contained tasks where adding more structure would be overkill. APE answers three essential questions in the fewest possible words: what to do, why it matters, and what success looks like. A complete APE prompt emits as three short sentences, which makes it the shortest template in this package.
+
+**Origin:** No single documented originator. Action-Purpose-Expectation is a community prompt-engineering convention, documented in practitioner guides from 2024 onward (earliest found: fvivas.com, 15 March 2024) with no attributed creator. It does not appear in any peer-reviewed prompting survey, including The Prompt Report (arXiv 2406.06608). **Not to be confused with** APE = "Automatic Prompt Engineer" from Zhou et al., "Large Language Models Are Human-Level Prompt Engineers" (arXiv 2211.01910, ICLR 2023) — an unrelated automated method that searches over LLM-generated candidate instructions and selects the highest-scoring one. That APE is an algorithm, not a prompt template; the two share only the acronym.
 
 ## Components
 
 ### A - Action
-**Purpose:** State the core action to take. One clear verb-driven instruction.
+**Purpose:** State the core action to take, as one complete imperative sentence. Nothing else in an APE prompt states the task, so a bare noun phrase ("meeting summary") leaves the emitted prompt with no instruction in it at all.
 
 **Questions to Ask:**
 - What exactly should happen?
@@ -15,13 +17,13 @@ APE (Action, Purpose, Expectation) is the most minimal structured prompt framewo
 - What's the one thing needed?
 
 **Examples:**
-- "Write a function that..."
-- "Summarize this document..."
-- "Translate the following..."
-- "List three alternatives to..."
+- "Write a JSDoc comment for the function above."
+- "Summarize the key decisions in the transcript above."
+- "Translate the error message above into Brazilian Portuguese."
+- "List three alternative approaches to the indexing problem described above."
 
 ### P - Purpose
-**Purpose:** State why this action is needed. Provides just enough context to calibrate the output without a full background brief.
+**Purpose:** State why this action is needed. Provides just enough context to calibrate the output without a full background brief. It ships inside the carrier sentence `Calibrate the result to this purpose: …`, so the slot itself may be a fragment.
 
 **Questions to Ask:**
 - Why is this needed?
@@ -29,13 +31,13 @@ APE (Action, Purpose, Expectation) is the most minimal structured prompt framewo
 - Who needs it and why?
 
 **Examples:**
-- "...so a new engineer can understand the codebase quickly"
-- "...for inclusion in a weekly stakeholder email"
-- "...because our target market is in Brazil"
-- "...to help decide which approach to take"
+- "a new engineer who needs to understand the codebase quickly"
+- "inclusion in a weekly stakeholder email"
+- "end users in Brazil, who will see this message in production"
+- "the team deciding which approach to pursue in tomorrow's planning session"
 
 ### E - Expectation
-**Purpose:** Define what a good result looks like. The standard for success.
+**Purpose:** Define what a good result looks like. The standard for success. It ships inside the carrier sentence `A good result meets this standard: …`, so the slot itself may be a fragment, and may hold several clauses.
 
 **Questions to Ask:**
 - What does a good result look like?
@@ -43,36 +45,65 @@ APE (Action, Purpose, Expectation) is the most minimal structured prompt framewo
 - Length, format, or tone requirements?
 
 **Examples:**
-- "Should be under 100 words and jargon-free"
-- "Should be actionable, not just descriptive"
-- "Should fit in a single Slack message"
-- "Should have a clear recommendation at the end"
+- "under 100 words and jargon-free"
+- "actionable, not just descriptive"
+- "short enough to fit in a single Slack message"
+- "ends with a clear recommendation"
 
 ## Template Structure
 
-```
-ACTION: [What to do]
-PURPOSE: [Why it's needed]
-EXPECTATION: [What a good result looks like]
-```
+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. That is why `ACTION` has to be a complete sentence, and why `PURPOSE` and `EXPECTATION` ship with carrier sentences that let their own slots stay fragments.
 
-Or as a single sentence:
 ```
-[ACTION] so that [PURPOSE], and it should [EXPECTATION].
+SOURCE MATERIAL:
+[Optional — paste the artifact the task operates on here, named concretely (the meeting
+transcript, the function). If the task creates something from scratch, delete this
+bracketed block along with the sentence directly below it.]
+Use the material above as the input for the task described below.
+
+ACTION:
+[One complete imperative sentence naming what to produce, e.g. "Summarize the decisions in
+the transcript above." Never a bare noun phrase like "meeting summary" — nothing else here
+states the task. The two fields below may be fragments.]
+
+PURPOSE:
+Calibrate the result to this purpose: [who needs it and what they will do with it].
+
+EXPECTATION:
+A good result meets this standard: [the success bar — length, format, tone, or quality].
 ```
 
+`SOURCE MATERIAL` is a fourth block in a three-letter acronym, and it carries no letter because it is optional. APE is usually pointed at something that already exists — a transcript, a function, a draft — and with no named place to put it, that artifact gets pasted into `ACTION`, the one field that cannot afford to lose its shape. Delete the block and the sentence beneath it whenever the task creates something from scratch.
+
+There is no collapsed single-sentence variant; see **Why There Is No Inline Form** below.
+
 ## 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: Code Comment
 
 **Before APE:**
 "Add a comment to this function."
 
-**After APE:**
+**After APE** (source material supplied):
 ```
-ACTION: Write a JSDoc comment for this function.
-PURPOSE: So a new team member can understand what it does without reading the implementation.
-EXPECTATION: Should cover parameters, return value, and one usage example. Under 8 lines.
+SOURCE MATERIAL:
+[Paste the function you want documented here]
+Use the material above as the input for the task described below.
+
+ACTION:
+Write a JSDoc comment for the function above.
+
+PURPOSE:
+Calibrate the result to this purpose: a new team member who needs to understand what the
+function does without reading its implementation.
+
+EXPECTATION:
+A good result meets this standard: covers every parameter and the return value, includes
+one usage example, and stays under 8 lines.
 ```
 
 ### Example 2: Meeting Summary
@@ -80,11 +111,22 @@ EXPECTATION: Should cover parameters, return value, and one usage example. Under
 **Before APE:**
 "Summarize this meeting."
 
-**After APE:**
+**After APE** (source material supplied):
 ```
-ACTION: Summarize the key decisions and action items from this meeting transcript.
-PURPOSE: For team members who missed the meeting and need to catch up quickly.
-EXPECTATION: Bullet points only, max 10 bullets, each under 15 words.
+SOURCE MATERIAL:
+[Paste the meeting transcript here]
+Use the material above as the input for the task described below.
+
+ACTION:
+Summarize the key decisions and action items in the transcript above.
+
+PURPOSE:
+Calibrate the result to this purpose: team members who missed the meeting and need to
+catch up quickly.
+
+EXPECTATION:
+A good result meets this standard: bullet points only, at most 10 bullets, each under 15
+words.
 ```
 
 ### Example 3: Alternative Ideas
@@ -92,11 +134,22 @@ EXPECTATION: Bullet points only, max 10 bullets, each under 15 words.
 **Before APE:**
 "Give me options."
 
-**After APE:**
+**After APE** (source material supplied):
 ```
-ACTION: List 3 alternative approaches to the database indexing problem described below.
-PURPOSE: To help the team decide which direction to pursue in tomorrow's planning session.
-EXPECTATION: Each option needs a one-sentence tradeoff (pro and con). No implementation details yet.
+SOURCE MATERIAL:
+[Paste the description of the database indexing problem here]
+Use the material above as the input for the task described below.
+
+ACTION:
+List three alternative approaches to the indexing problem described above.
+
+PURPOSE:
+Calibrate the result to this purpose: the team deciding which direction to pursue in
+tomorrow's planning session.
+
+EXPECTATION:
+A good result meets this standard: each option gets a one-sentence tradeoff naming one
+advantage and one cost, and none of them go into implementation detail yet.
 ```
 
 ### Example 4: Translation
@@ -104,11 +157,43 @@ EXPECTATION: Each option needs a one-sentence tradeoff (pro and con). No impleme
 **Before APE:**
 "Translate this."
 
-**After APE:**
+**After APE** (source material supplied):
+```
+SOURCE MATERIAL:
+[Paste the error message to be translated here]
+Use the material above as the input for the task described below.
+
+ACTION:
+Translate the error message above into Brazilian Portuguese.
+
+PURPOSE:
+Calibrate the result to this purpose: end users in Brazil, who will see this message in
+production when the app fails.
+
+EXPECTATION:
+A good result meets this standard: natural-sounding Brazilian Portuguese rather than a
+literal translation, with technical terms left in English.
 ```
-ACTION: Translate the following error message into Portuguese (Brazilian).
-PURPOSE: Our app is launching in Brazil and this error will be seen by end users.
-EXPECTATION: Natural-sounding Brazilian Portuguese, not a literal translation. Keep technical terms in English.
+
+### Example 5: Deploy Freeze Announcement
+
+**Before APE:**
+"Write an announcement."
+
+**After APE** (no source material — the announcement is written from scratch, so the
+`SOURCE MATERIAL` block and the sentence below it are both deleted):
+```
+ACTION:
+Write a Slack announcement telling the engineering team that Friday deploys are frozen
+until January 5.
+
+PURPOSE:
+Calibrate the result to this purpose: engineers who need to know what changed and what to
+do instead, not why the policy exists.
+
+EXPECTATION:
+A good result meets this standard: one short paragraph, plain and direct, no more than
+four sentences, ending with who to contact for an exception.
 ```
 
 ## Best Use Cases
@@ -158,24 +243,27 @@ EXPECTATION: Natural-sounding Brazilian Portuguese, not a literal translation. K
 | Context needed? | Minimal (Purpose) | Yes | No |
 | Best for | Ultra-quick, one-off | Context-heavy | Expertise-driven |
 
-## Inline APE Pattern
-
-APE works especially well as a single sentence:
-
-```
-[ACTION] for [PURPOSE], and it should [EXPECTATION].
-```
-
-**Examples:**
-```
-Summarize this PR description for a non-technical stakeholder, and it should fit in two sentences.
-```
-```
-List three naming alternatives for this function for a code review discussion, and each should be self-explanatory without comments.
-```
-```
-Write a commit message for these changes for git history, and it should follow conventional commits format.
-```
+## Why There Is No Inline Form
+
+Earlier versions of this document offered a collapsed single sentence as an equal option,
+in two different and mutually inconsistent syntaxes — `[ACTION] so that [PURPOSE], and it
+should [EXPECTATION].` and `[ACTION] for [PURPOSE], and it should [EXPECTATION].` The
+shipped template implements neither, and the emitted prompt should not use them. Two
+things break when APE is collapsed:
+
+- **There is nowhere to put source material.** Most APE tasks operate on something that
+  already exists. In the collapsed form that artifact has to be pasted into the middle of
+  the instruction sentence, which is the one field the template protects.
+- **The connectives are load-bearing and rigid.** `so that` and `and it should` only fit
+  purposes and expectations that happen to be single clauses. A real expectation is
+  usually several ("bullet points only, at most 10 bullets, each under 15 words"), and
+  splicing that after `and it should` yields a sentence that no longer parses as an
+  instruction.
+
+Brevity is preserved without the collapse. A complete APE prompt is three sentences, and
+for a from-scratch task the emitted block is three lines of prose — still the shortest
+output any template in this package produces. The brevity comes from APE having only
+three fields, not from compressing them onto one line.
 
 ## Common Mistakes
 

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

@@ -4,6 +4,8 @@
 
 BAB (Before, After, Bridge) is a transformation-focused framework ideal for rewrite, refactor, and conversion tasks. It explicitly defines the current state, the desired state, and asks for the path between them. Nothing in the standard framework set handles "change this into that" as cleanly as BAB.
 
+**Origin:** Predates LLMs as a direct-response copywriting formula. The earliest verified dated appearance is Kevan Lee's "27 Best Copywriting Formulas" (Buffer blog, 13 October 2014), which lists Before-After-Bridge as formula #1 and — unlike the other formulas in that article, which it credits to named copywriters such as Bob Stone — presents it as already-common property with no attributed author. No individual coiner has been verified. Its use in prompt engineering is a later community adaptation of the copywriting formula.
+
 ## Components
 
 ### B - Before
@@ -15,10 +17,10 @@ BAB (Before, After, Bridge) is a transformation-focused framework ideal for rewr
 - What are the limitations?
 - What does it look like right now?
 
-**Examples:**
-- "This function uses nested callbacks and is difficult to read..."
-- "Our homepage copy is written for developers, not customers..."
-- "This README is disorganized with no clear structure..."
+**Examples** (complete sentences, not bare noun phrases):
+- "The function above nests three fetch calls as callbacks, so the control flow is hard to follow and no step can be tested on its own."
+- "The homepage copy above is written for developers rather than for the operations managers who actually buy the product."
+- "The README above has no section headers and buries the setup instructions behind a wiki link."
 
 ### A - After
 **Purpose:** Describe the desired end state — what it should look like once the transformation is complete.
@@ -29,10 +31,10 @@ BAB (Before, After, Bridge) is a transformation-focused framework ideal for rewr
 - What problems should be solved?
 - What does success look like?
 
-**Examples:**
-- "...should use async/await and be readable by a junior developer"
-- "...should speak to non-technical buyers who care about outcomes"
-- "...should have a clear structure with quick start and API docs sections"
+**Examples** (complete sentences, not bare noun phrases):
+- "The same logic implemented with async/await, readable by a junior developer who has not worked with Promises."
+- "Copy that speaks to non-technical buyers in terms of the outcomes they care about."
+- "A README with a clear structure, a quick start on the first screen, and a populated API docs section."
 
 ### B - Bridge
 **Purpose:** Describe how to get from Before to After — the approach, constraints, and rules for the transformation.
@@ -43,26 +45,61 @@ BAB (Before, After, Bridge) is a transformation-focused framework ideal for rewr
 - What should be changed vs. left alone?
 - Any constraints on approach?
 
-**Examples:**
-- "Preserve all existing functionality, only change syntax"
-- "Keep the same information but reframe for a non-technical audience"
-- "Maintain existing section content, just restructure the order and add missing sections"
+**Examples** (each a self-contained imperative carrying its own verb):
+- "Preserve all existing functionality and change only the syntax."
+- "Keep the same information but reframe it for a non-technical audience."
+- "Maintain the existing section content; restructure the order and add the missing sections."
+- *Prohibitions take explicit "Do not…" / "Never…" form:* "Do not rename any variable." / "Never introduce a new dependency."
 
 ## Template Structure
 
+Section headers are stripped at emission, so every header's meaning is carried by the
+unbracketed prose that ships inside each slot rather than by the label above it. Do not
+reintroduce header-only structure.
+
+Two elements of the shipped template are not framework components. The leading
+`SOURCE MATERIAL` block holds the artifact being transformed and is **not optional here** —
+BAB requires something to transform, so unlike the source-material slot in other templates
+it is never deleted. The closing `Now …` line restates the transformation as an imperative
+so the prompt ends with an instruction rather than with a list of constraints.
+
 ```
+SOURCE MATERIAL:
+[Paste the artifact to be transformed here — the artifact itself, never a description of it.
+Name it concretely and keep it bracketed for the user to fill in, e.g. "[Paste the current
+job posting here]".]
+Use the material above as the material to be transformed for the work described below.
+
 BEFORE:
-[Current state — what exists, what's wrong, what needs to change]
+This is the state that material is in now, and why it must change:
+[Describe the current state in complete sentences, not a bare noun phrase. Say what exists
+now, what is wrong with it, and what needs to change. Quote the material above wherever a
+specific flaw is visible in it.]
 
 AFTER:
-[Desired state — what it should look like, qualities it should have]
+This is what it must become once the transformation is complete:
+[Describe the desired end state in complete sentences. Cover the qualities the result must
+have and the criteria that make it successful. Name the audience only if the user identified
+one; otherwise leave "[you fill this in: who will read the result]".]
 
 BRIDGE:
-[How to get there — transformation rules, constraints, what to preserve]
+Follow these rules when carrying out the transformation:
+[State each rule as a self-contained imperative carrying its own verb — "Preserve every salary
+and benefits detail exactly as written", not "salary details". Write prohibitions as
+"Do not…" or "Never…". Cover:
+- What must be preserved unchanged, and what should change
+- Any constraint on approach, style, tone, length, or format]
+
+Now [state the transformation as an imperative naming the material, e.g. "rewrite the job
+posting above"].
 ```
 
 ## Complete Examples
 
+Every example below is shown in emitted form: the source material first, then each slot
+carrying its own role in prose, then the closing imperative. Read the headers as scaffolding
+that will be deleted — the examples are written so that nothing is lost when it is.
+
 ### Example 1: Code Refactoring
 
 **Before BAB:**
@@ -70,22 +107,33 @@ BRIDGE:
 
 **After BAB:**
 ```
+SOURCE MATERIAL:
+[Paste the JavaScript function to be refactored here]
+Use the material above as the material to be transformed for the work described below.
+
 BEFORE:
-This JavaScript function uses nested callbacks (callback hell) and is difficult
-to read, test, and maintain. It fetches user data, then fetches their orders,
-then fetches order details — all nested three levels deep.
+This is the state that material is in now, and why it must change:
+The function above fetches user data, then that user's orders, then the details for
+each order, with the three calls nested inside one another as callbacks. The nesting
+makes the control flow hard to follow, error handling is repeated separately at every
+level, and no individual step can be tested on its own.
 
 AFTER:
-The same logic implemented using async/await with proper error handling. Should
-be readable by a junior developer who is comfortable with ES6+ but unfamiliar
-with Promises. Each step should be clearly separated and independently testable.
+This is what it must become once the transformation is complete:
+The same logic implemented with async/await, with each of the three fetch steps clearly
+separated and independently testable, and with error handling consolidated in one place
+rather than repeated per level. The result must be readable by a junior developer who is
+comfortable with ES6+ syntax but has not worked with Promises.
 
 BRIDGE:
-- Preserve all existing functionality and API call structure
-- Replace only the async pattern (callbacks → async/await)
-- Add try/catch error handling at the top level
-- Do not change variable names or data structures
-- Add inline comments explaining the flow
+Follow these rules when carrying out the transformation:
+- Preserve every existing behavior, along with the sequence and shape of the API calls, exactly as written.
+- Replace only the asynchronous pattern, converting the nested callbacks to async/await.
+- Add a single try/catch at the top level that covers all three fetch steps.
+- Do not rename any variable and do not change any data structure.
+- Add one inline comment per fetch step stating what that step retrieves.
+
+Now rewrite the JavaScript function above.
 ```
 
 ### Example 2: Copy Rewrite
@@ -95,23 +143,34 @@ BRIDGE:
 
 **After BAB:**
 ```
+SOURCE MATERIAL:
+[Paste the current homepage headline and body copy here]
+Use the material above as the material to be transformed for the work described below.
+
 BEFORE:
-Our current homepage headline reads: "A robust, scalable event-driven
-microservices orchestration platform." It was written by engineers for
-engineers. Conversion rate is poor because our actual buyers are non-technical
-operations managers.
+This is the state that material is in now, and why it must change:
+The headline above reads "A robust, scalable event-driven microservices orchestration
+platform." It was written by engineers for engineers, and it names the architecture
+rather than the problem the product solves. Our actual buyers are non-technical
+operations managers, and conversion on this page is poor.
 
 AFTER:
-A headline and 3-sentence description that immediately communicates business
-value to an operations manager. Should answer "what problem does this solve
-for me?" within the first 10 words. Should not use any technical jargon.
+This is what it must become once the transformation is complete:
+A headline plus a three-sentence description that communicates business value to a
+non-technical operations manager. The reader must be able to answer "what problem does
+this solve for me?" from the first ten words alone, without knowing what a microservice
+is.
 
 BRIDGE:
-- Keep the core value proposition (automation, reliability, scale)
-- Replace technical terms with business outcomes
-- Use active voice and plain language
-- Tone: confident, clear, outcome-focused
-- Length: headline (8 words max) + 2-3 supporting sentences
+Follow these rules when carrying out the transformation:
+- Preserve the core value proposition of automation, reliability, and scale.
+- Replace every technical term with the business outcome it produces.
+- Write in active voice and plain language.
+- Keep the tone confident, clear, and outcome-focused.
+- Limit the headline to 8 words and the supporting copy to 2-3 sentences.
+- Do not use technical jargon anywhere in the result.
+
+Now rewrite the homepage headline and body copy above.
 ```
 
 ### Example 3: Documentation Restructure
@@ -121,21 +180,32 @@ BRIDGE:
 
 **After BAB:**
 ```
+SOURCE MATERIAL:
+[Paste the current README here]
+Use the material above as the material to be transformed for the work described below.
+
 BEFORE:
-Our README starts with a 500-word technical architecture explanation. New
-contributors can't find the quick start. There is no installation section —
-setup instructions are buried in a wiki link. The API docs section is empty.
+This is the state that material is in now, and why it must change:
+The README above opens with a 500-word technical architecture explanation, so a new
+contributor cannot find the quick start without scrolling past it. There is no
+installation section — setup instructions exist only behind a wiki link — and the API
+docs section is present but empty.
 
 AFTER:
-A README that a new contributor can use to be productive within 15 minutes.
-Clear sections, scannable with headers, quick start in the first screen.
+This is what it must become once the transformation is complete:
+A README that a new contributor can follow to a working local setup within 15 minutes,
+organized into clearly headed sections that can be scanned rather than read, with the
+quick start visible on the first screen.
 
 BRIDGE:
-- Keep all existing content (do not delete information, only reorganize)
-- Reorder sections: Overview → Quick Start → Installation → Usage → API → Contributing
-- Move architecture explanation to a collapsible section or link to wiki
-- Add a minimal API docs skeleton with TODO placeholders
-- Add a table of contents at the top
+Follow these rules when carrying out the transformation:
+- Preserve all existing content; reorganize it rather than deleting any information.
+- Order the sections as Overview, Quick Start, Installation, Usage, API, Contributing.
+- Move the architecture explanation into a collapsible section or replace it with the wiki link.
+- Add a minimal API docs skeleton with TODO placeholders where content is missing.
+- Add a table of contents at the top.
+
+Now restructure the README above.
 ```
 
 ### Example 4: Tone Transformation
@@ -145,21 +215,32 @@ BRIDGE:
 
 **After BAB:**
 ```
+SOURCE MATERIAL:
+[Paste the draft response to the customer complaint here]
+Use the material above as the material to be transformed for the work described below.
+
 BEFORE:
-This customer complaint response sounds defensive and shifts blame to the
-customer. It uses passive voice and doesn't offer a clear resolution path.
+This is the state that material is in now, and why it must change:
+The draft above reads as defensive and shifts blame onto the customer. It states what
+happened in passive voice, and it closes without telling the customer what will happen
+next or what they should do.
 
 AFTER:
-A response that acknowledges the problem, takes responsibility, and gives the
-customer a clear next step. Should feel warm, professional, and solution-focused.
+This is what it must become once the transformation is complete:
+A response that acknowledges the problem, takes responsibility for it, and gives the
+customer one clear next step. It must read as warm, professional, and focused on
+resolving the issue.
 
 BRIDGE:
-- Keep the factual information (what happened, timeline)
-- Remove defensive language and blame shifting
-- Add an explicit apology in the first sentence
-- End with a single, specific action item the customer should take
-- Tone: empathetic but professional, not overly apologetic
-- Length: match original (under 150 words)
+Follow these rules when carrying out the transformation:
+- Preserve the factual account of what happened and the timeline exactly as given.
+- Open with an explicit apology in the first sentence.
+- Close with a single specific action item for the customer.
+- Remove all defensive language and every statement that assigns blame to the customer.
+- Keep the tone empathetic but professional, and do not over-apologize.
+- Match the original length and stay under 150 words.
+
+Now rewrite the customer complaint response above.
 ```
 
 ## Best Use Cases