Swanepoel's Best Agents Four-Pattern Framework
Apply the four structural patterns shared by the world's best AI agents to dramatically improve any agent you are building or evaluating.
// TL;DR
Swanepoel's Best Agents Four-Pattern Framework is a structural design framework for building, auditing, or improving AI agents. It identifies the four patterns shared by the world's best agents: Focus Modes (constrain the agent's action space), Transparent Execution (show the process, not just results), Personalization (encode how the user would do the task), and Reversibility (let users undo agent actions). Use it whenever you're designing a new agent, iterating on an underperforming one, or evaluating whether an agent is production-ready. It's especially valuable when agents produce low-trust outputs, confuse users, ignore context, or cause irreversible mistakes.
// When should I use Swanepoel's Best Agents Four-Pattern Framework?
Use this skill whenever you are designing, building, auditing, or critiquing an AI agent — whether from scratch or iterating on an existing one. Especially relevant when an agent produces low-trust outputs, confuses users, ignores personal context, or causes irreversible mistakes.
// What information do I need before applying the Four-Pattern Framework?
- Agent descriptionrequired
A plain-language description of the agent you are building or evaluating — what it does, who it serves, and what tools or systems it uses. - Current pain points
What is currently going wrong or suboptimal with the agent? (e.g. low output quality, user confusion, irreversible errors, impersonal results) - User profile
Who is the end user of the agent and what are their expectations, expertise level, and goals? - Task domain
The domain or category of tasks the agent performs (e.g. coding, legal review, research, writing).
// What are the core principles behind Swanepoel's Four-Pattern Framework?
Steal Like an Artist (Deep Study Principle)
Before building, go and look at what the best agents are doing, study them deeply, really understand them, make their patterns your own, and use that to come up with something better and unique. This is not copying — it is the prerequisite to originality.
Constrain to Excel
A general-purpose agent that can do anything tends to do nothing exceptionally well. Constraining the action and input space through Focus Modes allows you to optimize deeply for a smaller surface area before expanding.
Delegation vs. Collaboration
The goal of Transparent Execution is to shift the user's relationship with the agent from pure delegation (hand off, get result) to active collaboration (shared process, shared understanding). Transparency builds trust; opacity destroys it.
Speed to Understanding, Not Just Speed to Outcome
It is easy to generate an output quickly. It is hard to generate the right output. Agents should optimize for speed to understanding — grasping all nuances and implicit preferences of the user — so they do the right thing, not just something.
Bound the Downside
Reversibility is not about undoing failures; it is about making the worst-case cost known and manageable. When users know their downside is bounded, they become bolder, take more risks, and tackle higher-value tasks.
// How do you apply Swanepoel's Four-Pattern Framework step by step?
- 1
Map the agent's current design against all four patterns
For each of the four patterns — Focus Modes, Transparent Execution, Personalization, Reversibility — ask: does this agent currently implement this pattern? Score it as absent, partial, or present. This audit reveals your highest-leverage improvement opportunities.
- 2
Design or redesign Focus Modes for the agent
Identify the 2–5 distinct task types the agent performs (e.g. planning, researching, debugging, drafting). Define a separate mode for each. For each mode: (a) drop tools not needed in that mode, (b) refine the system prompt to that mode's constraints, (c) set explicit user-facing expectations so users know what behavior to expect and what inputs to provide. Do not try to do everything in one undifferentiated mode.
- 3
Implement Transparent Execution across the agent's output surface
Surface the agent's process, not just its results. At minimum include: a live to-do / progress list showing completed and upcoming steps; visibility into which tools were called and with what inputs and outputs; and any assumptions or uncertainties the agent holds. The user must be able to intervene early if the agent is heading in the wrong direction — this reduces waste.
- 4
Build a Personalization layer that encodes how the user would do the task themselves
Give the agent the thoughts, systems, knowledge, and principles the user would apply if doing the task personally. This can take multiple flavors: (a) Playbooks — domain-specific methods and principles (e.g. how this legal firm reviews contracts); (b) Memory — persisted learnings from past interactions that carry forward; (c) Connected skills and systems — external knowledge bases, tools, or connectors that reflect the user's context. The test: would the output look like the user did it, or like a generic agent did it?
- 5
Engineer Reversibility at multiple levels of granularity
Identify every action the agent takes that could have a meaningful downside. For each, design an undo or rollback mechanism. Offer reversibility at the finest granularity useful (e.g. line-level, file-level, conversation-state-level). Where possible, enable parallel outputs with the same input so all but the best can be discarded. Integrate with native platform change-tracking APIs (e.g. Word's track-changes) where applicable. The goal is that the user can say yes to bold experiments knowing the worst case is just an undo.
- 6
Evaluate and iterate each pattern independently
Because each pattern operates on a constrained surface (Focus Modes in particular shrink the action space), you can run targeted evaluations (e-vals) on each mode and each pattern separately. Don't try to evaluate a do-anything agent holistically — evaluate it mode by mode, pattern by pattern, and improve incrementally.
// What does the Four-Pattern Framework look like in real-world agent projects?
A customer support agent that handles billing, technical troubleshooting, and account changes — currently returning low-trust answers and making irreversible account modifications users complain about.
Apply Focus Modes by splitting the agent into Billing Mode, Troubleshooting Mode, and Account Mode — each with its own system prompt, tool set, and user expectation framing. Add Transparent Execution so users see a live task list and every API call made. Add a Personalization layer seeded with the company's support playbook and a memory of past user interactions. Add Reversibility by staging all account changes as pending-confirmation before execution and logging a rollback path for each action.
A research agent for a consulting firm that synthesizes market reports — users don't trust the outputs and don't know if the agent read the right sources.
Transparent Execution is the primary lever: surface every document the agent read, what it concluded from each, and what it is uncertain about. Add a Research Mode Focus Mode that sets user expectations (expect questions back, not a final report) and a Synthesis Mode that produces the final output. Use Personalization via a Playbook that encodes the firm's analytical framework (e.g. MECE structuring, specific source hierarchies). Reversibility here means versioned drafts so any synthesis can be rolled back to a prior state.
// What mistakes should I avoid when applying the Four-Pattern Framework?
- Optimizing for speed to outcome instead of speed to understanding — generating fast output that misses the user's implicit preferences is worse than slower output that gets it right.
- Building a do-anything, ask-anything agent without Focus Modes — this makes it impossible to optimize quality on any single task type and leaves users unsure how to get the best result.
- Showing the agent's final result without showing its process — this destroys trust even when the result is correct, because the user has no way to verify or intervene.
- Treating personalization as optional polish — if the agent does something instead of the right thing, the output is useless regardless of how fast it arrived.
- Ignoring reversibility until something goes wrong — the absence of reversibility suppresses user boldness and limits the agent to only low-stakes tasks, dramatically reducing its value.
// What key terms do I need to know for the Four-Pattern Framework?
- Focus Modes
- A design pattern where the agent is placed into a specific named mode (e.g. Planning Mode, Debug Mode, Research Mode) that constrains both the agent's action space and the user's expected inputs and behaviors — enabling deeper optimization and clearer user expectations.
- Transparent Execution
- A design pattern that makes the agent's internal process — its to-do list, tool calls, inputs, outputs, assumptions, and uncertainties — fully visible to the user in real time, shifting the user relationship from delegation to collaboration.
- Personalization
- A design pattern that equips the agent with the thoughts, systems, knowledge, principles, and patterns the user would apply if doing the task themselves — enabling the agent to do the right thing rather than just something.
- Reversibility
- A design pattern that gives users the ability to undo or roll back agent actions at multiple levels of granularity, bounding the cost of mistakes and making users bolder in tackling high-value tasks.
- Speed to Understanding
- The metric an agent should optimize for: how quickly it grasps all nuances and implicit preferences of the user before producing output — as distinct from raw speed to outcome, which can produce fast but useless results.
- Playbook
- A Personalization artifact encoding a team or firm's domain-specific methods, principles, and approaches to a task type (e.g. how a legal firm reviews a contract) — provided to the agent so it executes tasks the way the user's organization would.
- Memory
- A Personalization mechanism where the agent creates and stores learnings from past interactions, drawing on them in subsequent sessions to continuously improve its alignment with the user's preferences and context.
- Bound the Downside
- The core value proposition of Reversibility: by making the worst-case cost of agent actions known and recoverable, users can confidently authorize higher-risk, higher-value tasks.
// FREQUENTLY ASKED QUESTIONS
What is Swanepoel's Best Agents Four-Pattern Framework?
It is a structural design framework that identifies the four patterns shared by the world's best AI agents: Focus Modes, Transparent Execution, Personalization, and Reversibility. Created by Mardu Swanepoel of Flinn AI, it gives builders and evaluators a concrete checklist for what separates exceptional agents from mediocre ones. You apply it by auditing your agent against each pattern, then designing or retrofitting the missing ones.
What are Focus Modes in AI agent design?
Focus Modes are a design pattern where the agent operates in specific named modes — like Planning Mode, Research Mode, or Debug Mode — each with its own constrained tool set, system prompt, and user expectations. Instead of building a do-anything agent, you split tasks into 2–5 modes and optimize each independently. This improves quality, user clarity, and evaluability.
How do I implement Transparent Execution in my AI agent?
Surface the agent's process in real time, not just its final result. At minimum, show a live to-do or progress list, which tools were called with what inputs and outputs, and any assumptions or uncertainties the agent holds. This lets users intervene early if the agent goes off-track, shifting the dynamic from blind delegation to active collaboration and dramatically increasing trust.
How do I add Personalization to an AI agent?
Equip the agent with the user's own methods, knowledge, and principles through three mechanisms: Playbooks (domain-specific approaches, like how your firm reviews contracts), Memory (persisted learnings from past interactions), and Connected Systems (external knowledge bases and tools reflecting user context). The test: would the output look like the user did it, or like a generic agent did it?
What is Reversibility in AI agents and why does it matter?
Reversibility is a design pattern that gives users the ability to undo or roll back agent actions at multiple granularity levels — line-level, file-level, or conversation-state-level. It bounds the worst-case cost of any agent action, making mistakes recoverable. This is critical because without reversibility, users limit agents to low-stakes tasks only, dramatically reducing the agent's value.
How does the Four-Pattern Framework compare to just following general AI agent best practices?
General best practices tend to be scattered and abstract — 'use good prompts,' 'add guardrails.' Swanepoel's framework is structural and exhaustive across four specific dimensions. It gives you a concrete audit checklist (Focus Modes, Transparent Execution, Personalization, Reversibility) so you can score gaps and prioritize fixes. It also provides specific implementation guidance for each pattern rather than generic advice.
When should I use the Four-Pattern Framework for my agent?
Use it whenever you are designing a new agent, iterating on an underperforming one, or evaluating an agent for production readiness. It's especially high-leverage when users don't trust agent outputs, are confused about what the agent can do, get generic-feeling results, or have experienced irreversible errors. It applies across all domains — coding, legal, research, customer support, writing.
What results can I expect after applying the Four-Pattern Framework?
Expect measurably higher user trust (from Transparent Execution), improved output quality and user clarity (from Focus Modes), outputs that feel like the user did them (from Personalization), and increased willingness to use the agent for high-value tasks (from Reversibility). The framework also makes evaluation easier because you can test each mode and pattern independently rather than trying to evaluate a do-anything agent holistically.
What is Speed to Understanding in AI agent design?
Speed to Understanding is the metric agents should optimize for: how quickly the agent grasps all nuances and implicit preferences of the user before producing output. It is distinct from Speed to Outcome, which focuses on fast output regardless of quality. An agent optimizing for Speed to Understanding may ask clarifying questions or surface assumptions first, producing slower but dramatically more useful results.
How do I audit an existing agent using the Four-Pattern Framework?
For each of the four patterns — Focus Modes, Transparent Execution, Personalization, Reversibility — ask whether your agent currently implements it and score it as absent, partial, or present. This creates a 4-cell scorecard that immediately reveals your highest-leverage improvement opportunities. Then use the framework's workflow to design or retrofit the weakest patterns first.
What are Playbooks and Memory in the context of agent Personalization?
Playbooks are domain-specific method documents encoding how a team or organization does a task — for example, a consulting firm's MECE analysis framework or a legal firm's contract review checklist. Memory is a mechanism where the agent stores learnings from past user interactions and applies them in future sessions. Together they ensure the agent produces outputs aligned with the user's specific approach, not generic results.
Turn Any YouTube Video Into An AI Skill
SkillForge captures a creator's exact methodology from their video and turns it into a reusable AI skill you can invoke in Claude, ChatGPT, or any LLM.
Forge your own skill