sofia-cli 0.1.1

package/src/mcp/webSearch.ts

@@ -0,0 +1,388 @@
+/**
+ * Web search tool backed by Azure AI Foundry Agent Service.
+ *
+ * Provides a `web.search` tool that can be registered with the Copilot SDK.
+ * Uses `@azure/ai-projects` SDK with `DefaultAzureCredential` for authentication.
+ * Creates an ephemeral agent with `web_search_preview` on first search call,
+ * reuses it for the session, and deletes it on session end.
+ *
+ * When not configured or on error, degrades gracefully.
+ */
+import type { ToolDefinition } from '../shared/copilotClient.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface WebSearchResultItem {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+export interface WebSearchResult {
+  results: WebSearchResultItem[];
+  sources?: string[];
+  /** If true, the search degraded (Foundry unavailable/error). */
+  degraded?: boolean;
+  /** Error message when degraded. */
+  error?: string;
+}
+
+export interface WebSearchConfig {
+  projectEndpoint: string;
+  modelDeploymentName: string;
+}
+
+// ── Tool definition ──────────────────────────────────────────────────────────
+
+export const WEB_SEARCH_TOOL_DEFINITION: ToolDefinition = {
+  name: 'web.search',
+  description:
+    'Search the web for information about companies, industries, technologies, and trends. ' +
+    'Returns structured results with title, URL, and snippet.',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The search query string.',
+      },
+    },
+    required: ['query'],
+  },
+};
+
+// ── Configuration check ──────────────────────────────────────────────────────
+
+/**
+ * Check if web search is configured via environment variables.
+ *
+ * Uses the new env vars (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`)
+ * instead of legacy vars (`SOFIA_FOUNDRY_AGENT_ENDPOINT`, `SOFIA_FOUNDRY_AGENT_KEY`).
+ */
+export function isWebSearchConfigured(): boolean {
+  return Boolean(process.env.FOUNDRY_PROJECT_ENDPOINT && process.env.FOUNDRY_MODEL_DEPLOYMENT_NAME);
+}
+
+// ── Citation extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract citations from a Foundry agent response.
+ *
+ * Parses `url_citation` annotations from the response output items and maps
+ * them into `WebSearchResultItem[]`. Deduplicates sources by URL.
+ */
+export function extractCitations(output: unknown[]): {
+  results: WebSearchResultItem[];
+  sources: string[];
+} {
+  const results: WebSearchResultItem[] = [];
+  const seenUrls = new Set<string>();
+
+  for (const item of output) {
+    const messageItem = item as Record<string, unknown>;
+    if (messageItem.type !== 'message') continue;
+
+    const content = messageItem.content as unknown[];
+    if (!Array.isArray(content)) continue;
+
+    for (const contentBlock of content) {
+      const block = contentBlock as Record<string, unknown>;
+      if (block.type !== 'output_text') continue;
+
+      const text = String(block.text ?? '');
+      const annotations = block.annotations as unknown[];
+      if (!Array.isArray(annotations)) continue;
+
+      for (const annotation of annotations) {
+        const ann = annotation as Record<string, unknown>;
+        if (ann.type !== 'url_citation') continue;
+
+        const url = String(ann.url ?? '');
+        const title = String(ann.title ?? url);
+        const startIndex = Number(ann.start_index ?? 0);
+        const endIndex = Number(ann.end_index ?? text.length);
+        const snippet = text.slice(startIndex, Math.min(endIndex, startIndex + 200)) || title;
+
+        if (url && !seenUrls.has(url)) {
+          seenUrls.add(url);
+          results.push({ title, url, snippet });
+        }
+      }
+    }
+  }
+
+  return { results, sources: [...seenUrls] };
+}
+
+/**
+ * Fallback extraction when a response has no URL citations.
+ *
+ * Some Foundry responses can contain only plain output text without
+ * `url_citation` annotations. This extracts text blocks into lightweight
+ * snippets so downstream enrichment still has useful context.
+ */
+export function extractTextSnippets(output: unknown[]): WebSearchResultItem[] {
+  const snippets: WebSearchResultItem[] = [];
+
+  for (const item of output) {
+    const messageItem = item as Record<string, unknown>;
+    if (messageItem.type !== 'message') continue;
+
+    const content = messageItem.content as unknown[];
+    if (!Array.isArray(content)) continue;
+
+    for (let i = 0; i < content.length; i++) {
+      const block = content[i] as Record<string, unknown>;
+      if (block.type !== 'output_text') continue;
+
+      const text = String(block.text ?? '').trim();
+      if (!text) continue;
+
+      snippets.push({
+        title: 'Foundry response',
+        url: `foundry://response/${i + 1}`,
+        snippet: text.length > 300 ? `${text.slice(0, 300)}…` : text,
+      });
+    }
+  }
+
+  return snippets;
+}
+
+// ── Agent Session ────────────────────────────────────────────────────────────
+
+/**
+ * Internal state for the ephemeral web search agent.
+ * Manages lazy initialization, query execution, and cleanup.
+ */
+export interface AgentSessionDeps {
+  createClient: (endpoint: string) => unknown;
+  getOpenAIClient: (client: unknown) => Promise<unknown>;
+  createAgentVersion: (
+    client: unknown,
+    name: string,
+    options: unknown,
+  ) => Promise<{ name: string; version: string }>;
+  deleteAgentVersion: (client: unknown, name: string, version: string) => Promise<void>;
+  createConversation: (openAIClient: unknown) => Promise<{ id: string }>;
+  deleteConversation: (openAIClient: unknown, id: string) => Promise<void>;
+  createResponse: (
+    openAIClient: unknown,
+    conversationId: string,
+    input: string,
+    agentName: string,
+  ) => Promise<{ output: unknown[] }>;
+}
+
+interface AgentSessionState {
+  client: unknown;
+  openAIClient: unknown;
+  agentName: string;
+  agentVersion: string;
+  queryCount: number;
+  initialized: boolean;
+}
+
+const MAX_QUERIES_PER_AGENT = 3;
+const MAX_RETRIES = 2;
+const RETRY_DELAY_MS = 2000; // 2 second initial delay
+
+let sessionState: AgentSessionState | null = null;
+let sessionDeps: AgentSessionDeps | null = null;
+
+/**
+ * Create default dependencies using the real Azure SDK.
+ */
+async function createDefaultDeps(): Promise<AgentSessionDeps> {
+  const { AIProjectClient } = await import('@azure/ai-projects');
+  const { DefaultAzureCredential } = await import('@azure/identity');
+
+  return {
+    createClient: (endpoint: string) => new AIProjectClient(endpoint, new DefaultAzureCredential()),
+    getOpenAIClient: async (client: unknown) =>
+      (client as InstanceType<typeof AIProjectClient>).getOpenAIClient(),
+    createAgentVersion: async (client: unknown, name: string, options: unknown) => {
+      const aiClient = client as InstanceType<typeof AIProjectClient>;
+      const result = await aiClient.agents.createVersion(
+        name,
+        options as import('@azure/ai-projects').AgentDefinitionUnion,
+      );
+      return { name: result.name, version: result.version };
+    },
+    deleteAgentVersion: async (client: unknown, name: string, version: string) => {
+      await (client as InstanceType<typeof AIProjectClient>).agents.deleteVersion(name, version);
+    },
+    createConversation: async (openAIClient: unknown) => {
+      const oai = openAIClient as { conversations: { create: () => Promise<{ id: string }> } };
+      return oai.conversations.create();
+    },
+    deleteConversation: async (openAIClient: unknown, id: string) => {
+      const oai = openAIClient as { conversations: { delete: (id: string) => Promise<void> } };
+      await oai.conversations.delete(id);
+    },
+    createResponse: async (
+      openAIClient: unknown,
+      conversationId: string,
+      input: string,
+      agentName: string,
+    ) => {
+      const oai = openAIClient as {
+        responses: {
+          create: (params: unknown, options: unknown) => Promise<{ output: unknown[] }>;
+        };
+      };
+      return oai.responses.create(
+        { conversation: conversationId, input },
+        { body: { agent: { name: agentName, type: 'agent_reference' } } },
+      );
+    },
+  };
+}
+
+// ── Tool factory ─────────────────────────────────────────────────────────────
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function cleanupCurrentAgent(keepDeps: boolean): Promise<void> {
+  if (!sessionState?.initialized || !sessionDeps) {
+    sessionState = null;
+    return;
+  }
+
+  const { client, agentName, agentVersion } = sessionState;
+
+  sessionState = null;
+
+  try {
+    await sessionDeps.deleteAgentVersion(client, agentName, agentVersion);
+  } catch {
+    // Best-effort cleanup.
+  }
+
+  if (!keepDeps) {
+    sessionDeps = null;
+  }
+}
+
+/**
+ * Create a web search function that calls the Azure AI Foundry Agent Service.
+ *
+ * The returned function:
+ * - Lazily creates an ephemeral agent with web_search_preview on first call
+ * - Reuses the agent for subsequent calls
+ * - Rotates the agent after a few queries to avoid stale response behavior
+ * - Uses a fresh conversation per query to keep citation output stable
+ * - Returns structured results with URL citations
+ * - Degrades gracefully on errors (returns empty results with degraded flag)
+ *
+ * Pass `deps` for testing to inject mocked SDK clients.
+ */
+export function createWebSearchTool(
+  config: WebSearchConfig,
+  deps?: AgentSessionDeps,
+): (query: string) => Promise<WebSearchResult> {
+  sessionDeps = deps ?? null;
+
+  return async (query: string): Promise<WebSearchResult> => {
+    try {
+      const resolvedDeps = sessionDeps ?? (await createDefaultDeps());
+      sessionDeps = resolvedDeps;
+
+      if (sessionState?.initialized && sessionState.queryCount >= MAX_QUERIES_PER_AGENT) {
+        await cleanupCurrentAgent(true);
+      }
+
+      // Lazy initialization
+      if (!sessionState?.initialized) {
+        const client = resolvedDeps.createClient(config.projectEndpoint);
+        const openAIClient = await resolvedDeps.getOpenAIClient(client);
+
+        const agent = await resolvedDeps.createAgentVersion(client, 'sofia-web-search', {
+          kind: 'prompt',
+          model: config.modelDeploymentName,
+          instructions:
+            'You are a web search assistant. Search the web and return relevant results with citations.',
+          tools: [{ type: 'web_search_preview' }],
+        });
+
+        sessionState = {
+          client,
+          openAIClient,
+          agentName: agent.name,
+          agentVersion: agent.version,
+          queryCount: 0,
+          initialized: true,
+        };
+      }
+
+      // Execute query in an isolated conversation with retry logic for rate limiting.
+      const conversation = await sessionDeps.createConversation(sessionState.openAIClient);
+
+      let response: { output: unknown[] };
+
+      for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+          response = await sessionDeps.createResponse(
+            sessionState.openAIClient,
+            conversation.id,
+            query,
+            sessionState.agentName,
+          );
+          break;
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+
+          // Check for 429 rate limiting
+          if (message.includes('429') && attempt < MAX_RETRIES) {
+            const delayMs = RETRY_DELAY_MS * Math.pow(2, attempt);
+            await sleep(delayMs);
+            continue;
+          }
+
+          throw err;
+        }
+      }
+
+      try {
+        await sessionDeps.deleteConversation(sessionState.openAIClient, conversation.id);
+      } catch {
+        // Conversation cleanup failures should not fail web search results.
+      }
+
+      sessionState.queryCount += 1;
+
+      // Extract citations. response is guaranteed to be assigned by loop logic:
+      // either break assigns it, or catch throws (exiting function).
+      const { results: citationResults, sources } = extractCitations(response!.output ?? []);
+      const results =
+        citationResults.length > 0 ? citationResults : extractTextSnippets(response!.output ?? []);
+
+      return { results, sources };
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        results: [],
+        degraded: true,
+        error: message,
+      };
+    }
+  };
+}
+
+// ── Session cleanup ──────────────────────────────────────────────────────────
+
+/**
+ * Destroy the ephemeral web search agent and conversation.
+ *
+ * Safe to call multiple times. Logs warnings on cleanup failure but does not throw.
+ */
+export async function destroyWebSearchSession(): Promise<void> {
+  await cleanupCurrentAgent(false);
+}
+
+// Register cleanup on process exit
+process.on('beforeExit', () => {
+  void destroyWebSearchSession();
+});

package/src/originalPrompts/design_thinking.md

@@ -0,0 +1,178 @@
+# Essential Techniques for Running Effective Design Thinking Sessions
+
+Design thinking represents a transformative methodology that empowers teams to solve complex, ill-defined problems through human-centered approaches. This comprehensive guide synthesizes the most critical techniques for successfully facilitating design thinking sessions, drawing from established frameworks developed by leading institutions like Stanford's d.school. The report examines the foundational five-stage process of empathize, define, ideate, prototype, and test, while exploring essential exercises including empathy mapping, rapid prototyping, and various brainstorming methodologies. Key facilitation strategies emerge as crucial success factors, emphasizing the importance of maintaining neutrality, encouraging participation, and creating inclusive environments. Advanced techniques such as SCAMPER, Six Thinking Hats, and reverse brainstorming provide additional tools for overcoming creative blocks and generating innovative solutions. The synthesis reveals that effective design thinking facilitation requires both structured methodology and adaptive flexibility, supported by specific tools and exercises tailored to each phase of the process.
+
+## The Design Thinking Process Framework
+
+### Understanding the Five-Stage Model
+
+The design thinking methodology follows a structured yet flexible approach that provides teams with a systematic framework for tackling complex challenges. According to the Hasso Plattner Institute of Design at Stanford, design thinking consists of five core stages: Empathize, Define, Ideate, Prototype, and Test[1]. These stages represent a non-linear, iterative process that can have anywhere from three to seven phases depending on the specific implementation, but the five-stage model has gained widespread acceptance due to its comprehensive yet manageable structure[1].
+
+The process fundamentally reverses traditional business approaches by beginning with desirability rather than feasibility or viability, ensuring that solutions remain grounded in genuine human needs[4]. This human-centered approach distinguishes design thinking from other problem-solving methodologies and serves as the foundation for all subsequent techniques and exercises. Teams often run these stages in parallel, out of order, and repeat them as needed, reflecting the iterative nature of creative problem-solving[4].
+
+The design thinking process serves as more than just a linear sequence of activities; it represents multiple intersected arenas of thinking that allow teams to explore problems and solutions from various perspectives[5]. Understanding this framework provides the essential foundation for selecting and implementing specific techniques and exercises that will be most effective for each stage of the process.
+
+### The Empathize Stage: Building User Understanding
+
+The empathize stage focuses exclusively on user-centric research, requiring facilitators to guide teams toward gaining an empathic understanding of the problems they are attempting to solve[1]. This stage involves consulting experts to gather information about the area of concern and conducting observations to engage directly with users. Teams may also need to immerse themselves in their users' physical environments to develop deeper, more personal understanding of the issues involved and the experiences users face[1].
+
+Effective facilitation during the empathize stage requires specific techniques designed to uncover genuine user insights rather than assumptions or preconceptions. User interviews represent one of the most fundamental methods for understanding user needs, pain points, attitudes, and behaviors[4]. The Five Whys method provides another valuable tool for digging deeper into problems to diagnose root causes, while user observations help teams understand how users actually behave in real-life situations as opposed to what they claim to do[4].
+
+The empathize stage establishes the foundation for all subsequent work in the design thinking process, making it crucial for facilitators to allocate sufficient time and resources to this phase. Teams that rush through empathy-building activities often find themselves solving the wrong problems or developing solutions that fail to address genuine user needs.
+
+### The Define Stage: Synthesizing Insights
+
+Following the empathize stage, teams must analyze their observations and synthesize them to define core problems clearly and accurately[4]. This stage involves creating problem statements that capture the essential challenges identified through user research, often supplemented by personas that help keep efforts human-centered throughout the process[4]. The define stage serves as a critical transition point between understanding users and generating solutions.
+
+Effective facilitation during the define stage requires techniques that help teams organize and make sense of the research findings they have gathered. Affinity diagramming provides a systematic method for organizing research findings into meaningful clusters and patterns[4]. Journey mapping offers another valuable tool for visualizing users' experiences as they work to solve problems, helping teams identify specific pain points and opportunities for intervention[4].
+
+The define stage demands careful attention to ensuring that problem statements accurately reflect user needs rather than predetermined solutions or organizational biases. Facilitators must guide teams through the process of synthesizing complex user data into clear, actionable problem definitions that will drive effective ideation and solution development.
+
+## Core Design Thinking Exercises and Tools
+
+### Empathy Mapping: Understanding User Perspectives
+
+Empathy mapping represents one of the most critical exercises for launching design thinking workshops, enabling team members to develop deeper understanding of their target users' needs, wants, and attitudes by exploring what motivates them[2]. This visual exercise creates a structured framework for organizing user insights and identifying gaps in understanding that require further research.
+
+The empathy mapping process begins with defining the target user group clearly and specifically, followed by creating a large visual grid with four quadrants representing "Says," "Thinks," "Does," and "Feels"[2]. Teams then gather available data on their target users and engage in collaborative discussions to share insights across the group. Each quadrant is filled with observations and data that correspond to what users say, think, do, and feel, creating a comprehensive picture of user experiences and motivations[2].
+
+Analysis of the completed empathy map reveals patterns and gaps in understanding that can drive further research and ideation activities[2]. This exercise proves particularly valuable for teams working with diverse user groups or complex user needs, as it provides a systematic approach to organizing and synthesizing user insights. Facilitators should ensure that empathy mapping sessions remain grounded in actual user data rather than assumptions or stereotypes about user behavior.
+
+### Brainstorming: Generating Creative Solutions
+
+Brainstorming serves as a classic design thinking activity that promotes rapid idea generation by creating an open environment for communication where team members can share thoughts freely and build upon each other's ideas[2]. Effective brainstorming requires careful facilitation to maintain energy, encourage participation, and prevent premature evaluation of ideas that can stifle creativity.
+
+The brainstorming process begins with clearly defining the challenge that teams want to address, followed by setting specific time limits that create urgency and prevent overthinking[2]. Facilitators should encourage participants to think freely and explicitly avoid critiquing ideas during the generation phase, as evaluation can inhibit creative thinking. All ideas should be recorded visibly on whiteboards or sticky notes to ensure that contributions remain accessible to the entire group[2].
+
+Following the generation phase, teams review and categorize ideas, discussing their merits and potential for further development[2]. This structured approach to brainstorming ensures that teams generate sufficient quantities of ideas while maintaining focus on the defined challenge. Facilitators play a crucial role in maintaining momentum during brainstorming sessions and ensuring that all participants have opportunities to contribute their perspectives.
+
+### Rapid Prototyping: Testing Ideas Quickly
+
+Rapid prototyping represents a hands-on design thinking exercise that enables teams to quickly visualize and iterate on ideas by building low-fidelity models that provide insights into user interactions and design refinements[2]. This technique emphasizes speed and functionality over aesthetics, allowing teams to test concepts efficiently before investing significant resources in development.
+
+The rapid prototyping process involves selecting promising ideas from brainstorming sessions and providing teams with various materials such as paper, cardboard, or basic digital tools to create physical or digital representations of their concepts[2]. Participants should focus on core functionality and user experience rather than visual polish, with time limits of 30-60 minutes ensuring rapid iteration and preventing perfectionism[2].
+
+Testing and iteration form essential components of rapid prototyping, with teams using feedback from colleagues and target users to refine their designs continuously[2]. This iterative approach helps teams identify potential issues early in the development process and make necessary adjustments before committing to more extensive development efforts. Facilitators should emphasize the experimental nature of prototyping and encourage teams to view failures as learning opportunities rather than setbacks.
+
+## Facilitation Strategies and Best Practices
+
+### The Facilitator's Role and Responsibilities
+
+A facilitator in design thinking workshops plays a vital role in guiding participants through the design thinking process while ensuring that each stage is effectively met and that the environment remains conducive to creative thinking[3]. The facilitator's responsibilities extend beyond simple process management to include creating psychological safety, managing group dynamics, and maintaining focus on user-centered outcomes.
+
+The primary responsibilities of design thinking facilitators include guiding the process to ensure proper implementation, managing time effectively through time-boxing techniques that keep each phase within established timeframes, encouraging participation from all team members, and maintaining positive environments where every idea is valued and every participant feels appreciated[3]. These responsibilities require facilitators to balance structure with flexibility, providing enough guidance to maintain progress while allowing space for creative exploration.
+
+Time management represents a particularly critical aspect of facilitation, as design thinking sessions often involve multiple activities and diverse participants with varying levels of experience[3]. Effective facilitators develop skills in recognizing when to move groups forward and when to allow additional time for deeper exploration, always keeping the overall objectives and timeline in mind.
+
+### Essential Facilitator Attributes
+
+Successful design thinking facilitators must possess specific attributes that enable them to create environments where creativity flourishes and all participants can contribute effectively[3]. Open-mindedness stands as perhaps the most critical attribute, requiring facilitators to welcome diverse arrays of ideas without preconceptions or biases while fostering inclusive environments that support creativity[3].
+
+Maintaining a neutral stance represents another essential attribute, as facilitators should avoid leaning toward any particular idea or participant while acting as catalysts for ideation rather than influencers of outcomes[3]. This neutrality helps ensure that all perspectives receive equal consideration and that solutions emerge from the group rather than from facilitator preferences.
+
+Communication skills enable facilitators to coordinate complex group activities and express complicated ideas in simple, understandable ways that keep all participants engaged and informed[3]. Flexibility proves equally important, as design thinking's non-linear and iterative nature requires facilitators to adapt to unforeseen circumstances or changes in direction throughout the process[3]. These attributes develop through practice and experience, with techniques such as active listening, providing constructive feedback, and creating safe spaces for open dialogue serving as fundamental skills for improvement[3].
+
+### Managing Group Dynamics
+
+Effective facilitation requires careful attention to group dynamics, ensuring that all participants have equal opportunities to contribute while preventing dominant personalities from overwhelming quieter team members[3]. Facilitators must develop skills in reading group energy, identifying when participants are engaged or disengaged, and implementing strategies to maintain productive collaboration throughout the session.
+
+Encouraging participation from all team members requires deliberate attention to ensuring that quieter participants feel comfortable expressing their ideas and that more vocal participants do not dominate discussions[3]. This balance often requires facilitators to use specific techniques such as round-robin sharing, written brainstorming before verbal sharing, or small group work that allows different personality types to contribute effectively.
+
+Creating and maintaining positive environments where respect and appreciation are consistent themes helps ensure that all participants feel valued and willing to take creative risks[3]. Facilitators must model the behavior they expect from participants, demonstrating curiosity, openness to new ideas, and appreciation for diverse perspectives that contribute to successful design thinking outcomes.
+
+## Advanced Brainstorming Techniques
+
+### SCAMPER: Systematic Creative Exploration
+
+The SCAMPER technique provides a systematic approach to creative problem-solving by prompting teams to explore solutions through seven different lenses: Substitute, Combine, Adapt, Modify, Put to another use, Eliminate, and Reverse[6]. This structured brainstorming method helps teams overcome creative blocks by providing specific prompts that guide thinking in new directions and prevent teams from getting stuck in conventional approaches.
+
+Each element of SCAMPER encourages teams to examine their challenges from different perspectives, leading to more comprehensive exploration of potential solutions[6]. The substitute prompt asks teams to consider what elements could be replaced with alternatives, while combine explores how different elements might work together in new ways. Adapt focuses on how existing solutions from other contexts might apply to the current challenge, and modify examines how current approaches might be enhanced or changed.
+
+The final three elements of SCAMPER - put to another use, eliminate, and reverse - encourage more radical thinking about problems and solutions[6]. These prompts help teams break free from assumptions about how things should work and explore innovative approaches that might not emerge through traditional brainstorming methods. Facilitators can use SCAMPER systematically, working through each element in sequence, or selectively, focusing on specific elements that seem most relevant to the current challenge.
+
+### Six Thinking Hats: Multiple Perspective Analysis
+
+The Six Thinking Hats method, developed by psychologist Edward de Bono, forces teams to examine problems from six distinct perspectives by metaphorically wearing different "hats" that represent different types of thinking[6]. This technique proves particularly valuable for ensuring comprehensive analysis of challenges and preventing teams from overlooking important considerations due to personal biases or preferred thinking styles.
+
+The six hats represent different cognitive approaches: the White Hat focuses on logic and available facts, the Yellow Hat emphasizes optimism and positive aspects, the Black Hat takes a devil's advocate perspective examining risks and potential problems, the Red Hat explores emotional responses and gut instincts, the Green Hat encourages creativity and alternative thinking, and the Blue Hat manages the process and ensures adherence to the exercise rules[6].
+
+Implementation of Six Thinking Hats works best with teams of at least six people, with each participant wearing one hat for the duration of each session, though individual designers can also use the technique by systematically working through each perspective[6]. This method proves particularly effective when teams find themselves stuck in unproductive patterns of thinking or when important perspectives are being overlooked in group discussions. Facilitators should ensure that participants truly embody their assigned perspective rather than simply going through the motions of the exercise.
+
+### Reverse Brainstorming: Problem-Focused Innovation
+
+Reverse brainstorming provides an innovative approach to creative problem-solving by deliberately focusing on how to cause or worsen problems rather than solve them[5]. This counterintuitive technique often helps teams break through mental blocks and discover new perspectives on challenges by examining them from completely different angles.
+
+The reverse brainstorming process involves defining the problem clearly and then asking teams to brainstorm ways to cause or exacerbate the problem rather than solve it[5]. This radical change in direction often leads to insights about the root causes of problems and reveals assumptions that teams may not have recognized. Once teams have thoroughly explored how to create or worsen problems, they can reverse their findings to identify potential solutions that address the underlying issues.
+
+This technique proves particularly valuable when teams face dead ends in traditional brainstorming or when conventional approaches have failed to yield satisfactory results[5]. Reverse brainstorming can be used both for defining problems more clearly and for generating innovative solutions, making it a versatile tool for different stages of the design thinking process. Facilitators should prepare teams for the unusual nature of this exercise and help them understand how the reverse perspective can ultimately lead to better solutions.
+
+### Starbursting: Comprehensive Problem Exploration
+
+The Starbursting technique provides a systematic approach to exploring problems or situations by asking specific questions organized around the fundamental journalism questions: who, what, how, where, when, and why[5]. This method ensures comprehensive examination of challenges from multiple angles and helps teams avoid overlooking important aspects of complex problems.
+
+Each question category guides teams toward different aspects of the problem: "Who" questions explore stakeholders and users, "What" questions examine the nature and dimensions of the problem, "How" questions investigate processes and impacts, "Where" questions focus on locations and contexts, "When" questions examine timing and sequences, and "Why" questions explore motivations and root causes[5]. This systematic approach helps ensure that teams gather comprehensive information before moving toward solution development.
+
+Starbursting proves particularly valuable during the empathize and define stages of design thinking, as it provides a structured framework for gathering and organizing information about users and problems[5]. Facilitators can use this technique to guide research planning, ensuring that teams gather information from all relevant perspectives before attempting to define problems or generate solutions.
+
+## Implementation Considerations
+
+### Time Management and Session Structure
+
+Effective design thinking facilitation requires careful attention to time management and session structure to ensure that teams make meaningful progress while maintaining energy and engagement throughout the process[3]. Time boxing represents a fundamental technique for managing design thinking sessions, with facilitators setting specific time limits for each activity to maintain momentum and prevent teams from getting stuck in analysis paralysis.
+
+The structure of design thinking sessions should balance focused work time with opportunities for sharing, reflection, and iteration[3]. Facilitators must develop sensitivity to group energy levels and adjust timing accordingly, sometimes extending activities when teams are making productive progress and sometimes moving forward when groups become stuck or repetitive. Regular check-ins and transitions help maintain focus and ensure that all participants understand the purpose and expected outcomes of each activity.
+
+Session structure should also account for the different types of thinking required during various stages of the design thinking process, with empathy and research activities requiring different pacing than rapid ideation or prototyping sessions[3]. Facilitators should plan sessions with built-in flexibility that allows for adjustment based on group needs and emerging insights while maintaining overall progress toward session objectives.
+
+### Remote Collaboration Adaptations
+
+Modern design thinking facilitation increasingly requires adaptation for remote collaboration, with facilitators needing to modify traditional in-person exercises for virtual environments while maintaining the collaborative and creative energy that characterizes effective design thinking sessions[6]. Digital tools such as Mural, Jamboard, and Miro provide platforms for collaborative brainstorming, mapping, and visual thinking that can replicate many aspects of in-person workshops.
+
+Remote facilitation requires additional attention to ensuring participation and engagement from all team members, as virtual environments can make it easier for participants to become distracted or disengaged[6]. Facilitators should use techniques such as breakout rooms for small group work, regular check-ins with individual participants, and varied activity formats that maintain attention and energy throughout virtual sessions.
+
+The adaptation of specific exercises for remote environments often requires creative approaches that maintain the essential elements while accommodating technological constraints[6]. For example, empathy mapping can be conducted using collaborative digital whiteboards, while Six Thinking Hats exercises can use video conferencing features such as virtual backgrounds or emoji reactions to help participants embody their assigned perspectives. Facilitators should test digital tools thoroughly before sessions and have backup plans for technical difficulties that might disrupt the creative process.
+
+### Measuring Success and Iteration
+
+Successful design thinking facilitation requires ongoing attention to measuring outcomes and continuously improving facilitation approaches based on participant feedback and session results[3]. Facilitators should establish clear success criteria for each session, focusing not only on tangible outputs such as prototypes or defined problems but also on process outcomes such as participant engagement, collaboration quality, and learning.
+
+Regular reflection and feedback collection help facilitators understand what techniques work most effectively with different types of teams and challenges[3]. This might include brief surveys after sessions, structured debriefing conversations, or longer-term follow-up to understand how design thinking outcomes are implemented and whether they lead to successful solutions.
+
+Iteration represents a fundamental principle of design thinking that should also apply to facilitation approaches, with facilitators continuously experimenting with new techniques, refining existing approaches, and adapting methods based on experience and feedback[3]. This commitment to continuous improvement helps ensure that facilitation skills develop over time and that design thinking sessions become increasingly effective at generating innovative, user-centered solutions.
+
+## Conclusion
+
+The effective facilitation of design thinking sessions requires a comprehensive understanding of both structured methodologies and adaptive techniques that can respond to the dynamic nature of creative problem-solving. The five-stage framework of empathize, define, ideate, prototype, and test provides essential structure while allowing for the flexibility needed to address complex, ill-defined challenges. Core exercises such as empathy mapping, brainstorming, and rapid prototyping serve as fundamental building blocks that enable teams to generate user-centered insights and innovative solutions.
+
+The role of the facilitator emerges as perhaps the most critical factor in successful design thinking implementation, requiring individuals who possess open-mindedness, neutrality, strong communication skills, and the flexibility to adapt to changing circumstances. Advanced techniques such as SCAMPER, Six Thinking Hats, and reverse brainstorming provide additional tools for overcoming creative blocks and ensuring comprehensive exploration of problems and solutions. The synthesis of these elements creates a powerful methodology for addressing complex challenges across diverse contexts and industries.
+
+Looking forward, the continued evolution of design thinking facilitation will likely require ongoing adaptation to new technologies, remote collaboration requirements, and emerging understanding of creativity and innovation processes. The fundamental principles of human-centered design, systematic exploration, and iterative development will remain constant, while specific techniques and tools continue to evolve based on practical experience and research insights. Organizations and individuals who master these facilitation techniques will be well-positioned to tackle the complex challenges that define our rapidly changing world, creating solutions that truly serve human needs while driving innovation and positive change.
+
+Citations:
+[1] https://www.interaction-design.org/literature/article/5-stages-in-the-design-thinking-process
+[2] https://www.sei.com/insights/article/8-powerful-design-thinking-exercises-for-your-next-workshop/
+[3] https://learning.sap.com/courses/design-thinking/understanding-the-role-of-facilitator-in-design-thinking_eeb79cbc-c2cb-4ab3-a871-546651ceabff
+[4] https://www.interaction-design.org/literature/topics/design-thinking
+[5] https://www.designorate.com/design-thinking-tools-and-methods/
+[6] https://careerfoundry.com/blog/ux-design/design-thinking-exercises/
+[7] https://www.designthinkersacademy.com/anz/course/2-day-design-thinking-facilitation-workshop/
+[8] https://www.workshopper.com/post/how-to-run-a-design-thinking-workshop
+[9] https://miro.com/miroverse/design-thinking-project-planner-template/
+[10] https://makeiterate.com/how-to-run-how-might-we-workshops-a-quick-guide/
+[11] https://careerfoundry.com/blog/ux-design/what-is-design-thinking-everything-you-need-to-know-to-get-started
+[12] https://careerfoundry.com/en/blog/ux-design/design-thinking-workshop/
+[13] https://satellytes.com/blog/post/design-thinking-methods-of-the-individual-phases/
+[14] https://innominds.eu/design-thinking-workshop-agenda/
+[15] https://www.iberdrola.com/talent/design-thinking-methodology
+[16] https://designthinking-methods.de/en/
+[17] https://www.konrad.com/research/how-to-run-a-design-thinking-workshop
+[18] https://www.ideou.com/blogs/inspiration/design-thinking-process
+[19] https://blog.uxtweak.com/design-thinking-tools/
+[20] https://www.uxpin.com/studio/blog/design-thinking-workshop/
+[21] https://designthinking.es/en/como-es-el-proceso-de-design-thinking/
+[22] https://arounda.agency/blog/the-essential-ideation-techniques-for-design-thinking
+[23] https://triangility.com/19-design-thinking-methods-for-finding-effective-solutions/
+[24] https://international.binus.ac.id/graphic-design/2023/12/05/design-thinking-101-principles-tools-examples-to-transform-your-creative-process/
+[25] https://online.hbs.edu/blog/post/design-thinking-examples
+[26] https://www.innovationtraining.org/design-thinking-workshop-resources/
+[27] https://www.mural.co/templates/design-thinking-workshop

package/src/originalPrompts/design_thinking_persona.md

@@ -0,0 +1,76 @@
+# 🎯 Agent Role
+
+You are a world-class Design Thinking expert and facilitator. You have extensive experience guiding diverse teams through all stages of the Design Thinking process—Empathize, Define, Ideate, Prototype, and Test. You are skilled in adapting methods for both in-person and remote settings, and in fostering inclusive, creative, and psychologically safe environments.
+
+---
+
+# 🗣️ Tone & Communication Style
+
+- Communicate with clarity, empathy, and authority.
+- Use accessible language tailored to the audience’s experience level.
+- Encourage collaboration and build on others’ contributions.
+
+---
+
+# 🧭 Behavioral Guidelines
+
+- Analyze the ideas or contributions provided by participants.
+- Build on the ideas of others and those proposed by the provided cards (if applicable).
+- Select the most appropriate Design Thinking technique based on the nature of the input (e.g., clustering, “How Might We,” SCAMPER, etc.).
+- When appropriate, ask clarifying questions to deepen understanding or refine direction.
+
+---
+
+# 🔁 Reasoning Pattern: ReAct (Reason + Act)
+
+Before responding, follow this reasoning process:
+
+1. **Reason**:
+
+   - Identify the type and quality of input (e.g., raw idea, user need, insight).
+   - Determine which Design Thinking technique best supports the next step.
+   - Consider the context (e.g., workshop phase, team dynamics, delivery format).
+
+2. **Act**:
+   - Apply the selected technique.
+   - Generate or refine ideas using the structured output format below.
+
+---
+
+# 🧾 Output Format
+
+When synthesizing or proposing ideas, use the following structure:
+
+- **Idea Title**: [Concise, compelling name]
+- **Description**: [Brief explanation of the idea]
+- **Workflow Steps Covered**: [Which Design Thinking stages this idea supports]
+- **Aspirational Solution Scope**: [What success looks like if this idea is implemented]
+
+---
+
+# 🚫 Guardrails
+
+- Do not generate ideas unrelated to user needs or workshop context.
+- Avoid jargon unless the audience is experienced.
+- If input is unclear or insufficient, ask for clarification before proceeding.
+
+---
+
+# 🧪 Example (ReAct in Action)
+
+**Input**: “We should help users feel more confident when using our product.”
+
+**Agent Response**:
+
+Reasoning:
+
+- This is a user need focused on emotional experience.
+- It suggests a problem worth reframing into a “How Might We” question.
+- The best technique here is to reframe and ideate.
+
+Action:
+
+- Idea Title: Confidence Companion
+- Description: A built-in assistant that offers contextual tips, encouragement, and success stories to boost user confidence.
+- Workflow Steps Covered: Define, Ideate, Prototype
+- Aspirational Solution Scope: A product experience that empowers users and reduces drop-off due to uncertainty.