@ckelsoe/prompt-architect 3.0.0

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

@@ -0,0 +1,253 @@
+# CRISPE Framework
+
+## Overview
+
+CRISPE is a comprehensive general-purpose prompting framework covering six dimensions: Capacity and Role, Insight, Instructions, Personality, and Experiment. Its defining feature — the **Experiment** component — sets it apart from similar frameworks by explicitly asking the AI to produce multiple variants, approaches, or versions, enabling the user to compare and choose the best output rather than accepting a single answer.
+
+**Origin:** Developed by Matt Nigh (community framework, 2022). Since adopted in clinical AI literature (cited in PMC peer-reviewed medical AI studies, 2024-2025) and educational technology research (Springer, 2025).
+
+## Components
+
+### C — Capacity and Role
+**Purpose:** Define the expertise level and professional role the AI should embody. More specific than a simple "you are a..." — it combines the *type* of expertise with the *level* of sophistication expected.
+
+**Questions to Ask:**
+- What domain expertise is needed?
+- At what level? (practitioner, expert, specialist, world-class?)
+- Any specific sub-specialty?
+
+**Examples:**
+- "Act as an expert in marketing strategy with deep experience in B2B SaaS go-to-market..."
+- "You are a senior software architect specializing in distributed systems..."
+- "Act as a world-class UX researcher who has run hundreds of user interviews..."
+
+### R — Insight
+**Purpose:** Provide the background context, data, or knowledge the AI needs to perform the task effectively. This is the "briefing" — what you'd tell a new consultant before they start work.
+
+**Questions to Ask:**
+- What background does the AI need?
+- What relevant data, constraints, or history applies?
+- What does the AI need to know about the situation?
+
+**Examples:**
+- "Here's what we know: our churn rate is 8% monthly, concentrated in the SMB segment..."
+- "Context: our team uses Python exclusively, we have a 3-month deadline, and our infrastructure is AWS..."
+- "Background: this is for a Series A startup pitching to enterprise buyers for the first time..."
+
+### I — Instructions
+**Purpose:** State clearly and specifically what the AI should do. The task itself, with enough detail to remove ambiguity.
+
+**Questions to Ask:**
+- What exactly should be done?
+- What's the deliverable?
+- Any specific requirements for the output?
+
+**Examples:**
+- "Write a 6-week email drip campaign for free trial users..."
+- "Create a technical design document for this feature..."
+- "Analyze this data and identify the top 3 risk factors..."
+
+### S — Personality (Style)
+**Purpose:** Define the tone, voice, and communication style of the response. Sets how the output should *feel* — the personality it should embody.
+
+**Questions to Ask:**
+- What tone is appropriate?
+- What writing style?
+- How should the AI communicate — formal, casual, direct, nurturing?
+- Any persona to embody?
+
+**Examples:**
+- "Write in the style of a direct, no-nonsense VP of Engineering..."
+- "Use a warm, conversational tone that feels human and approachable..."
+- "Be concise and data-driven; avoid fluff; treat the reader as intelligent..."
+
+### E — Experiment
+**Purpose:** Explicitly request multiple variants, approaches, or versions of the output. This is CRISPE's unique differentiator — instead of one answer, get 2-4 options with different approaches so you can compare and select or combine.
+
+**Questions to Ask:**
+- How many variants would be useful?
+- What dimension of variation? (tone, approach, structure, length, angle)
+- Should variants be compared or presented side-by-side?
+
+**Examples:**
+- "Provide 3 variations: one data-heavy, one narrative, one bulleted"
+- "Give me 2 versions — one for a technical audience, one for executives"
+- "Write 3 headline options with different angles"
+- "Provide your best answer, then offer 2 alternative approaches I could take instead"
+
+## Template Structure
+
+```
+CAPACITY AND ROLE:
+[Define expertise level and professional role]
+
+INSIGHT:
+[Background context, data, and situation the AI needs to know]
+
+INSTRUCTIONS:
+[What exactly needs to be done — the task and deliverable]
+
+PERSONALITY (STYLE):
+[Tone, voice, communication style]
+
+EXPERIMENT:
+[Request N variants along a specific dimension — tone, approach, format, etc.]
+```
+
+## Complete Examples
+
+### Example 1: Marketing Campaign
+
+**Before CRISPE:**
+"Write email campaigns for our SaaS product."
+
+**After CRISPE:**
+```
+CAPACITY AND ROLE:
+Act as an expert B2B SaaS email marketer with 10+ years of experience in
+trial-to-paid conversion campaigns.
+
+INSIGHT:
+Our product is a project management tool for engineering teams. Free trial is
+14 days. Current trial-to-paid conversion is 12%. Data shows most conversions
+happen on days 3-5 or not at all. Our best customers are teams of 5-20 engineers
+at growth-stage startups. Key value props: GitHub integration, sprint planning,
+and automated reporting.
+
+INSTRUCTIONS:
+Write a 3-email drip sequence for free trial users. Emails trigger on: Day 1
+(welcome), Day 4 (mid-trial activation), Day 12 (pre-expiry urgency).
+
+PERSONALITY:
+Direct, peer-to-peer tone — like advice from a fellow engineer, not a sales rep.
+No corporate speak. Short. Respect the reader's time.
+
+EXPERIMENT:
+Provide 2 versions of the Day 12 urgency email: one that leads with FOMO/loss
+framing, one that leads with social proof/success stories. Note which performs
+better in most A/B tests and why.
+```
+
+### Example 2: Technical Documentation
+
+**Before CRISPE:**
+"Document our REST API."
+
+**After CRISPE:**
+```
+CAPACITY AND ROLE:
+You are a senior technical writer specializing in developer documentation for
+APIs, with experience at developer-tools companies.
+
+INSIGHT:
+This is a public REST API for a payment processing service. Primary users are
+backend developers integrating payments into their apps. Most are comfortable
+with REST but may be unfamiliar with our specific auth flow (OAuth 2.0 with
+JWT). The API has 12 endpoints. The most commonly used are: POST /charges,
+GET /charges/{id}, POST /refunds.
+
+INSTRUCTIONS:
+Document the POST /charges endpoint. Include: endpoint description, authentication
+requirements, request body parameters (table), response codes, example request
+(curl), example response (JSON), and common errors.
+
+PERSONALITY:
+Clear, precise technical writing. Minimal prose — mostly structured tables,
+code blocks, and bullet points. Treat the reader as an experienced developer
+who wants facts, not hand-holding.
+
+EXPERIMENT:
+Provide 2 formats: (1) full formal API reference style, (2) a quick-start
+"cookbook" style with opinionated examples. Note which format works best for
+onboarding vs. reference.
+```
+
+### Example 3: Strategic Analysis
+
+**Before CRISPE:**
+"Analyze our pricing strategy."
+
+**After CRISPE:**
+```
+CAPACITY AND ROLE:
+Act as a SaaS pricing strategy consultant with expertise in value-based pricing,
+packaging, and competitive positioning.
+
+INSIGHT:
+We offer 3 plans: Free (limited features), Pro ($49/month), Enterprise (custom).
+Current split: 60% free, 35% Pro, 5% Enterprise. Our main competitor charges
+$39/month for similar Pro features. We're seeing strong NPS (72) but sluggish
+expansion revenue — most Pro users stay on Pro indefinitely. Our top 10%
+customers drive 60% of revenue and are all on Enterprise.
+
+INSTRUCTIONS:
+Analyze our current pricing structure and recommend improvements to increase
+expansion revenue and ARPU without hurting free-to-paid conversion.
+
+PERSONALITY:
+Direct, CEO-level strategic thinking. Back recommendations with data logic.
+Be willing to challenge assumptions. Avoid hedging everything — take a position.
+
+EXPERIMENT:
+Give 3 strategic options: (1) a conservative tweak, (2) a mid-range restructure,
+(3) a bold rethink. For each, state the hypothesis, expected impact on ARPU and
+churn risk, and one key assumption that must be true for it to work.
+```
+
+## Best Use Cases
+
+1. **When You Want Options, Not Just One Answer**
+   - Creative decisions with multiple valid approaches
+   - A/B test candidates
+   - Exploratory analysis with multiple angles
+
+2. **Content Creation With Quality Bar**
+   - Marketing copy, campaigns, messaging
+   - Documentation with different audience cuts
+   - Communications requiring tone judgment
+
+3. **Strategic or Analytical Work**
+   - When multiple strategic options should be compared
+   - Analysis that might have different valid conclusions
+
+4. **When Style/Personality Matters Significantly**
+   - Brand voice must be carefully calibrated
+   - Audience-sensitive communications
+   - High-stakes external communications
+
+## Selection Criteria
+
+**Choose CRISPE when:**
+- ✅ You want multiple output variants to compare
+- ✅ Tone and personality need explicit control
+- ✅ Background context is extensive and critical
+- ✅ High-quality content where first draft is rarely final
+- ✅ Expertise level significantly affects output quality
+
+**Avoid CRISPE when:**
+- ❌ You need one definitive answer → use CO-STAR or RACE
+- ❌ Task is simple → use APE, RTF, or CTF
+- ❌ Multi-step process with methodology → use RISEN
+- ❌ Transforming existing content → use BAB
+
+## CRISPE vs. CO-STAR
+
+| | CRISPE | CO-STAR |
+|---|---|---|
+| Unique feature | Experiment — multiple variants | Style + Tone as explicit components |
+| Best when | You want options to compare | You know exactly what you want |
+| Output count | Multiple variants | Single polished output |
+| Audience component | Implicit in Insight/Personality | Explicit (Audience component) |
+| Complexity | Medium | High |
+
+**Rule of thumb:** If you want one great output → CO-STAR. If you want multiple options to compare → CRISPE.
+
+## Quick Reference
+
+| Component | Focus | Key Question |
+|-----------|-------|--------------|
+| Capacity & Role | Expertise | "What level of expert should do this?" |
+| Insight | Background | "What does the AI need to know?" |
+| Instructions | Task | "What exactly needs to be done?" |
+| Personality | Style | "How should it sound?" |
+| Experiment | Variants | "How many options do I want to compare?" |

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

@@ -0,0 +1,207 @@
+# CTF Framework
+
+## 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.
+
+## Components
+
+### C - Context
+**Purpose:** Describe the situation, background, or circumstances surrounding the task.
+
+**Questions to Ask:**
+- What is the current situation?
+- What background does the AI need to know?
+- What has already been done?
+- Why is this task needed?
+- 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..."
+
+### T - Task
+**Purpose:** State exactly what needs to be done.
+
+**Questions to Ask:**
+- What exactly needs to be done?
+- What's the deliverable?
+- 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..."
+
+### F - Format
+**Purpose:** Specify how the output should be structured.
+
+**Questions to Ask:**
+- What format should the output take?
+- How should it be structured?
+- What's the preferred presentation?
+- 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..."
+
+## Template Structure
+
+```
+CONTEXT:
+[Situation, background, circumstances]
+
+TASK:
+[What needs to be done]
+
+FORMAT:
+[How output should be structured]
+```
+
+## Complete Examples
+
+### Example 1: Requirement Change Summary
+
+**Before CTF:**
+"Summarize the new requirements."
+
+**After CTF:**
+```
+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.
+
+TASK:
+Write a brief summary of the requirement change 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
+```
+
+### Example 2: Code Explanation
+
+**Before CTF:**
+"Explain this code."
+
+**After CTF:**
+```
+CONTEXT:
+I'm a junior developer new to this codebase. The function below 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
+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)
+```
+
+### Example 3: Template Creation
+
+**Before CTF:**
+"Create a status report template."
+
+**After CTF:**
+```
+CONTEXT:
+Our team of 6 engineers sends weekly status reports to a non-technical product
+manager. Reports are currently inconsistent and take too long to write. We want
+a reusable template that takes under 10 minutes to fill out.
+
+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
+```
+
+## Best Use Cases
+
+1. **Situational Tasks**
+   - When background drives everything
+   - Handoff documents
+   - Mid-project updates
+   - Onboarding assistance
+
+2. **Context-Heavy Requests**
+   - Legacy code explanations
+   - Requirement change communication
+   - Stakeholder summaries
+
+3. **Simple, Well-Defined Tasks with Rich Background**
+   - Template creation
+   - Meeting prep
+   - Quick documentation
+
+4. **When Role is Obvious or Irrelevant**
+   - The expertise is implied by the context
+   - No need to establish an AI persona
+
+## Selection Criteria
+
+**Choose CTF when:**
+- ✅ Background/situation is the key driver
+- ✅ Role/persona is obvious or irrelevant
+- ✅ Task is simple and well-defined
+- ✅ Output format is a primary concern
+- ✅ Quick, focused execution needed
+- ✅ Context would be redundant in a Role definition
+
+**Avoid CTF when:**
+- ❌ AI expertise/persona materially changes output quality (use RTF)
+- ❌ 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-IE)
+
+## CTF vs RTF
+
+| | CTF | RTF |
+|---|---|---|
+| First component | **Context** — situational background | **Role** — AI persona/expertise |
+| Primary driver | "What's the situation?" | "Who should answer this?" |
+| Best for | Context-heavy, obvious expertise | Expertise-driven, minimal background |
+| Weakness | No persona framing | Context must fit inside Role |
+
+**Rule of thumb**: If you'd start writing "You are a..." → use RTF. If you'd start writing "Here's the situation..." → use CTF.
+
+## Common Mistakes
+
+1. **Vague Context**
+   - Include specific details: what already happened, what the constraints are, why it matters
+   - Don't just say "I need help with a project"
+
+2. **Insufficient Task Description**
+   - Be specific about the deliverable
+   - Define scope clearly
+
+3. **Missing Format Specification**
+   - Don't assume default output is correct
+   - Specify structure, length, and presentation
+
+4. **Using CTF for Complex Tasks**
+   - If context is long and task has multiple steps, upgrade to RISEN or CO-STAR
+
+## Quick Reference
+
+| Component | Focus | Key Question |
+|-----------|-------|--------------|
+| Context | Situation | "What's the background?" |
+| Task | Action | "What needs to be done?" |
+| Format | Structure | "How should it look?" |

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

@@ -0,0 +1,206 @@
+# Devil's Advocate Prompting
+
+## 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.
+
+**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.
+
+## When to Use
+
+- Testing a plan, decision, or proposal before committing
+- Preparing for pushback from stakeholders or opponents
+- Debiasing: countering groupthink or confirmation bias
+- Architecture/design reviews — find the fatal flaws first
+- Any high-stakes decision where being wrong is costly
+
+## 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.
+
+### Adversarial Instruction
+**Purpose:** Explicit instruction to be adversarial, not balanced. This is what makes it devil's advocate rather than a pros/cons analysis.
+
+### Attack Dimensions
+**Purpose:** The specific dimensions to attack. Without these, critique stays superficial.
+
+**Common dimensions:**
+- **Assumptions**: What must be true for this to work? Attack each assumption.
+- **Logic**: Where does the reasoning fail?
+- **Risks**: What are the most likely failure modes?
+- **Alternatives**: What better options are being ignored?
+- **Blind spots**: What has the author failed to consider?
+- **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.
+
+## Template Structure
+
+```
+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].
+
+POSITION TO ATTACK:
+[State the position, plan, or decision clearly]
+
+ATTACK INSTRUCTIONS:
+- Do not offer a balanced view or acknowledge positives
+- 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
+
+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]
+
+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.
+```
+
+## Complete Examples
+
+### Example 1: Architecture Decision
+
+```
+You are a rigorous devil's advocate.
+
+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.
+
+ATTACK INSTRUCTIONS:
+Generate the strongest possible case against this decision. Do not
+acknowledge any benefits. Attack the reasoning, assumptions, and plan.
+
+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
+
+SEVERITY RANKING:
+End with the 3 most fatal flaws that would cause this to fail.
+```
+
+### Example 2: Business Strategy
+
+```
+You are a rigorous devil's advocate.
+
+POSITION TO ATTACK:
+We should expand to the European market in Q3. We have strong US NPS (72),
+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.
+
+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
+
+SEVERITY RANKING:
+The 3 most fatal flaws, in order.
+```
+
+### Example 3: Product Decision
+
+```
+You are a rigorous devil's advocate.
+
+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.
+
+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
+
+SEVERITY RANKING:
+3 most fatal flaws.
+```
+
+### Example 4: Self-Attack (Devil's Advocate on AI Output)
+
+After receiving any AI recommendation:
+```
+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
+
+1. **Pre-commitment Decision Reviews**
+   - Before major investments, hires, or pivots
+   - Architecture and technical design reviews
+   - Product strategy validation
+
+2. **Countering Groupthink**
+   - When a team is too aligned ("everyone agrees" is a warning sign)
+   - When you're emotionally attached to an idea
+   - Pre-mortem supplement (DA finds weaknesses; pre-mortem assumes failure)
+
+3. **Stakeholder Preparation**
+   - What will your critics say? Find out first.
+   - Board presentations, investor pitches, procurement reviews
+
+4. **AI Output Validation**
+   - Ask the AI to attack its own recommendation (Example 4 above)
+   - Reduces over-reliance on AI confidence
+
+## Selection Criteria
+
+**Choose Devil's Advocate when:**
+- ✅ You have a position, plan, or recommendation to stress-test
+- ✅ You want the strongest *opposing* argument, not balance
+- ✅ You're making a high-stakes decision
+- ✅ Groupthink or confirmation bias is a risk
+- ✅ You want to prepare for criticism
+
+**Avoid when:**
+- ❌ You want failure modes from a failure-assumption frame → use Pre-Mortem
+- ❌ You want a quality improvement loop → use Self-Refine
+- ❌ You want principle-based critique → use CAI Critique-Revise
+- ❌ You need a balanced pros/cons analysis → use Tree of Thought
+
+## Devil's Advocate vs. Pre-Mortem
+
+| | Devil's Advocate | Pre-Mortem |
+|---|---|---|
+| Frame | "Here's why this is wrong" | "This has already failed — why?" |
+| Output | Strongest opposing argument | Specific failure causes |
+| Bias | Attacks position directly | Prospective hindsight |
+| Best for | Testing reasoning and assumptions | Risk identification and mitigation |
+
+**Use both:** Devil's Advocate finds the weakest arguments; Pre-Mortem finds the most likely failure paths. They complement each other.
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| Position Statement | What to attack |
+| Adversarial Instruction | Be forceful, not balanced |
+| Attack Dimensions | What aspects to critique |
+| Severity Ranking | The 3 most fatal flaws |