Swanepoel's Best Agents Four-Pattern Framework

Last updated: 26 May 2026

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 structured approach for designing, auditing, and improving AI agents using four patterns found in the world's best agents: Focus Modes (constrain the agent's action space), Transparent Execution (show the process, not just the result), Personalization (encode how the user would do the task), and Reversibility (let users undo any agent action). Use it whenever you're building a new agent, iterating on an underperforming one, or evaluating whether an agent is production-ready — especially when users report low trust, generic outputs, confusion, or fear of irreversible mistakes.

Framework

// 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 inputs do I need to apply 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 the 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 the 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 examples?

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 using 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 do the key terms in the Four-Pattern Framework mean?

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 framework that identifies four structural patterns shared by the world's best AI agents: Focus Modes, Transparent Execution, Personalization, and Reversibility. Developed from Mardu Swanepoel's analysis at Flinn AI, it gives builders a concrete checklist for designing agents that earn user trust, produce contextually accurate outputs, and safely handle high-stakes tasks. You audit your agent against all four patterns and iteratively improve each one.

What are Focus Modes in AI agent design?

Focus Modes are a design pattern where you split an agent into distinct 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 optimize deeply for each task type separately. This makes quality evaluation tractable and helps users understand what behavior to expect and what inputs to provide in each mode.

How do I implement Transparent Execution in my AI agent?

Surface the agent's working process alongside its results. At minimum, show a live to-do or progress list of completed and upcoming steps, display which tools were called with what inputs and outputs, and expose any assumptions or uncertainties the agent holds. This shifts the user from blind delegation to active collaboration, letting them intervene early if the agent is heading in the wrong direction — reducing wasted compute and increasing trust.

How do I add personalization to an AI agent?

Build a personalization layer using three mechanisms: Playbooks (domain-specific methods and principles your team follows), Memory (persisted learnings from past interactions that carry forward), and Connected Systems (external knowledge bases and tools reflecting the user's context). The test is whether the output looks like the user produced it themselves or like a generic agent did. Without personalization, the agent does something instead of the right thing.

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 levels of granularity — line-level, file-level, or conversation-state-level. It matters because it bounds the downside of any agent mistake. When users know the worst case is just an undo, they become bolder and authorize higher-value, higher-risk tasks. Without reversibility, agents get limited to only low-stakes work.

How does the Four-Pattern Framework compare to just writing better prompts?

Better prompts improve a single interaction's output quality, but the Four-Pattern Framework addresses structural design issues that prompts alone cannot fix. Focus Modes constrain tool access and user expectations. Transparent Execution requires UI-level changes to surface process. Personalization needs persistent memory and knowledge integration. Reversibility demands rollback infrastructure. These are architectural patterns, not prompt tweaks — they compound across every interaction rather than optimizing one exchange at a time.

When should I use the Four-Pattern Framework instead of just shipping fast?

Use it whenever users report low trust in agent outputs, confusion about what the agent is doing, generic results that don't match their style, or anxiety about irreversible mistakes. It is especially critical before scaling an agent to more users or higher-stakes tasks. If you ship fast without these patterns, you'll accumulate trust debt that limits adoption. The framework is also valuable during audits of existing agents to pinpoint the highest-leverage improvement.

What results can I expect after applying the Four-Pattern Framework?

Expect measurably higher user trust, increased willingness to delegate complex tasks, outputs that reflect the user's own standards and preferences, and fewer catastrophic or irreversible errors. Focus Modes make evaluation tractable so you can improve quality mode by mode. Transparent Execution reduces rework by letting users intervene early. Personalization eliminates generic outputs. Reversibility unlocks high-value use cases users previously avoided. Together, these patterns move agents from toy demos to production-grade tools.

What is speed to understanding in AI agents?

Speed to understanding is the metric an agent should optimize for: how quickly it grasps all nuances and implicit preferences of the user before producing output. It is distinct from raw speed to outcome, which can produce fast but useless results. An agent optimized for speed to understanding may ask clarifying questions, reference past interactions, or surface assumptions — all of which slow initial output but dramatically improve relevance and correctness.

How do I evaluate an AI agent using the Four-Pattern Framework?

Audit the agent against each pattern — Focus Modes, Transparent Execution, Personalization, Reversibility — and score each as absent, partial, or present. Then evaluate each Focus Mode independently using targeted evaluations rather than trying to assess a do-anything agent holistically. This pattern-by-pattern, mode-by-mode approach makes improvements incremental and measurable. The absent patterns reveal your highest-leverage opportunities.

Can I apply the Four-Pattern Framework to agents I didn't build myself?

Yes. The framework works equally well for critiquing or auditing third-party agents, vendor tools, or open-source agent projects. Map the agent's current design against all four patterns, identify which are absent or partial, and use those gaps as your evaluation criteria or improvement requests. This is especially useful when selecting between competing agent platforms or providing structured feedback to a vendor about what their product is missing.

// GET THIS SKILL — FREE