fraim-framework 2.0.26 → 2.0.30

package/registry/workflows/customer-development/thank-customers.md

@@ -1,191 +1,193 @@
-# Thank Customers Workflow
-
-## INTENT
-To automatically generate and send personalized thank you emails to customers whose feedback has been implemented, strengthening customer relationships and encouraging continued engagement.
-
-## PRINCIPLES
-- **Personal Touch**: Ashley's voice, grateful tone, "Thank you for making me better..."
-- **Voice & Pronouns**: Emails are written in first person from Ashley ("I", "me", "my"). When referring to Ashley in third person (outside the email body), use they/them pronouns. Avoid gendered pronouns for Ashley.
-- **Customer-Focused**: No technical jargon or issue numbers in customer emails
-- **Short and Sweet**: To the point, instructive, humble
-- **Encourage more feedback**: ChatGPT (https://ashley-chat.wellnessatwork.me) is the best way
-
-## WORKFLOW TRIGGER
-**User triggers this workflow manually**:
-- When customer issues are resolved and deployed
-- User says: "Generate thank you emails for customers" or similar
-
-## AI AGENT PROCESS
-
-### Step 1: Issue Retrieval
-**AI Agent calls function**:
-```typescript
-import { getResolvedIssues, findExecutiveByEmail, getAshleyEmailForExecutive } from '.ai-agents/scripts/generate-thank-you-emails.ts';
-
-// Get issues resolved since last thank-you date (automatic) or user-specified date
-const resolvedIssues = await getResolvedIssues(); // Automatically uses latest thank-you date
-// OR with explicit date:
-const resolvedIssues = await getResolvedIssues('2025-10-29'); // Optional: user-specified date
-```
-
-**Note**: The `getResolvedIssues()` function automatically:
-- Finds the most recent date from existing `thank-you-candidates-YYYY-MM-DD.json` files where emails were sent (status: "sent")
-- Uses that date as the starting point to only fetch issues resolved AFTER that date
-- If no thank-you files exist, falls back to last 14 days
-- This ensures we never send duplicate thank-you emails for the same resolved issues
-
-### Step 2: Customer Information Extraction
-**AI Agent does intelligent extraction**:
-1. **Go through each resolved issue**
-2. **Extract customer email** from:
-   - Issue title format: `email@domain.com: summary`
-   - Issue body: look for email patterns
-   - If no email found, extract customer name and use database lookup
-3. **Extract customer name** from:
-   - Issue title or body
-   - Previous thank-you notes
-   - Onboarding insights documents
-
-### Step 3: Database Lookup
-**AI Agent calls function for each customer**:
-```typescript
-// Look up executive by customer email
-const executive = await findExecutiveByEmail(customerEmail);
-
-// Get Ashley email address for this executive
-const ashleyEmail = await getAshleyEmailForExecutive(executive.id);
-```
-
-### Step 4: Collate Issues by Customer
-**AI Agent organizes data**:
-- Group all resolved issues by customer email
-- **Consolidate customers with multiple email addresses** by matching customer names (case-insensitive)
-- When a customer has multiple emails, use the primary email from the database lookup
-- Output customer list to console for verification
-
-### Step 5: Generate Single Thank-You File
-**AI Agent creates ONE file**:
-- File: `docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json`
-- Format: Structured JSON (not markdown) for easy parsing by mail sending script
-- Contains ALL customers and their personalized emails
-- **AI Agent writes the email content** - be creative, personal, and contextual!
-- Follow principles: personal touch, customer-focused, short and sweet, encourage feedback
-- **NO TECHNICAL JARGON**: Do not mention issue numbers, BAML, internal systems, or technical details
-- **CUSTOMER EXPERIENCE FOCUS**: Describe what was broken from the user's perspective, what was fixed, and how they can verify it works
-- **First-person Email Body**: Use "I" for actions Ashley took (e.g., "I fixed", "I now", "I will"), not "Ashley" or "she". Sign off as Ashley.
-- Include `From:` field showing Ashley email from PPE (via `getAshleyEmailForExecutive()`)
-
-**File format** (JSON):
-```json
-{
-   "metadata": {
-     "generatedOn": "2025-10-29T02:29:02.497Z",
-     "issuesResolvedSince": "2025-10-28",
-     "totalCustomers": 2,
-     "totalIssues": 3
-   },
-   "candidates": [
-     {
-       "customer": {
-         "name": "Olga Ivanova",
-         "email": "olga.ivanova@gmail.com"
-       },
-       "executive": {
-         "name": "Olga Ivanova",
-         "id": "exec-..."
-       },
-       "status": "pending",
-       "from": {
-         "displayName": "Ashley - Olga Ivanova's AI Executive Assistant",
-         "email": "ashley+olga@ashleycalendar.ai"
-       },
-       "to": "olga.ivanova@gmail.com",
-       "subject": "Thank you for your feedback - your issues have been addressed!",
-       "greeting": "Hi Olga,",
-       "opening": "Thank you for making me better! I wanted to personally reach out because your feedback helped us catch and fix an important bug.",
-       "improvements": [
-         {
-           "title": "Issue filing feature",
-           "description": "The issue filing feature is now working properly - when you ask me to file a bug or feature request through voice, I'll handle it correctly.",
-           "verification": "Try asking me to file a bug or feature request and it should work smoothly now."
-         }
-       ],
-       "closing": "Your quick feedback saved you (and others) frustration down the line. That kind of real-time input makes all the difference as I'm learning."
-     }
-   ]
- }
-```
-
-**Note**: The structured format allows the HTML template to format each section beautifully:
-- `greeting`: Personal greeting (e.g., "Hi Olga,")
-- `opening`: Opening paragraph - thanks and context
-- `improvements[]`: Array of improvements (title, description, optional verification step)
-- `closing`: Closing paragraph - encouraging more feedback
-
-The HTML template formats each section with appropriate styling.
-
-### Step 6: User Review
-**AI Agent**:
-1. **Points user to the generated file**: `docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json`
-2. **Requests review** and any edits needed (user can edit JSON directly)
-3. **Waits for user approval** before proceeding
-
-**Note**: Each email section includes a `From:` field showing the display name and email address that will be used when sending. The signature includes a humble note about ramping up, without displaying a generic email address.
-
-### Step 7: Send Emails (Separate Command)
-**When user says "Send the emails" or similar**:
-
-**AI Agent calls function**:
-```typescript
-import { sendCustomerMail } from '.ai-agents/scripts/generate-thank-you-emails.ts';
-
-// Send emails from the candidates JSON file (all pending candidates)
-await sendCustomerMail('docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json');
-
-// OR send to a specific executive only (optional)
-await sendCustomerMail('docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json', 'exec-1761011032377-q36j91sdl');
-```
-
-**Note**: The `sendCustomerMail` function parses JSON (not markdown) for easy, deterministic parsing.
-
-**Function parameters**:
-- `candidatesFilePath` (required): Path to the JSON candidates file
-- `executiveId` (optional): If provided, only sends emails for candidates matching this executive ID. If omitted, sends to all pending candidates.
-
-**This function will**:
-- Parse the JSON candidates file
-- If `executiveId` is provided, filter to only that executive's candidates
-- For each candidate with `status: "pending"`, send email
-- Use the `from` field (displayName and email) specified in JSON
-- Use the `to`, `subject`, and `body` fields from JSON
-- Update the JSON file after each send with status: `"sent"` or `"failed"`
-- Skip candidates that already have status `"sent"` or `"failed"`
-
-## REQUIRED FUNCTIONS IN SCRIPT
-
-The script must provide these deterministic functions for AI agents to call:
-
-```typescript
-// Get resolved issues since a date
-export async function getResolvedIssues(date: string): Promise<ResolvedIssue[]>
-
-// Find executive by email in PPE database  
-export async function findExecutiveByEmail(email: string): Promise<Executive | null>
-
-// Get Ashley email for executive from PPE database
-export async function getAshleyEmailForExecutive(executiveId: string): Promise<string>
-
-// Send emails from candidates file
-// executiveId is optional - if provided, only sends to that executive; if omitted, sends to all pending
-export async function sendCustomerMail(candidatesFilePath: string, executiveId?: string): Promise<void>
-```
-
-**Note**: The script provides ONLY data retrieval and sending. The AI agent does ALL intelligent work:
-- Extracts customer info from issues (intelligent parsing)
-- Writes personalized, creative email content (better than hardcoded templates!)
-- Organizes and formats the candidates file
-
-## WORKFLOW COMPLETION
-
-**Generate workflow completes with**: Single candidates file ready for review
-**Send workflow completes with**: All emails sent and file updated with status
+# Thank Customers Workflow
+
+## INTENT
+To automatically generate and send personalized thank you emails to customers whose feedback has been implemented, strengthening customer relationships and encouraging continued engagement.
+
+## PRINCIPLES
+- **Personal Touch**: Ashley's voice, grateful tone, "Thank you for making me better..."
+- **Voice & Pronouns**: Emails are written in first person from Ashley ("I", "me", "my"). When referring to Ashley in third person (outside the email body), use they/them pronouns. Avoid gendered pronouns for Ashley.
+- **Customer-Focused**: No technical jargon or issue numbers in customer emails
+- **Short and Sweet**: To the point, instructive, humble
+- **Encourage more feedback**: ChatGPT (https://ashley-chat.wellnessatwork.me) is the best way
+
+## WORKFLOW TRIGGER
+**User triggers this workflow manually**:
+- When customer issues are resolved and deployed
+- User says: "Generate thank you emails for customers" or similar
+
+## AI AGENT PROCESS
+
+### Step 1: Issue Retrieval
+**AI Agent calls function**:
+```typescript
+// Note: Retrieve script via get_fraim_file({ path: "scripts/generate-thank-you-emails.ts" }) and save to tmp/generate-thank-you-emails.ts
+import { getResolvedIssues, findExecutiveByEmail, getAshleyEmailForExecutive } from './tmp/generate-thank-you-emails.ts';
+
+// Get issues resolved since last thank-you date (automatic) or user-specified date
+const resolvedIssues = await getResolvedIssues(); // Automatically uses latest thank-you date
+// OR with explicit date:
+const resolvedIssues = await getResolvedIssues('2025-10-29'); // Optional: user-specified date
+```
+
+**Note**: The `getResolvedIssues()` function automatically:
+- Finds the most recent date from existing `thank-you-candidates-YYYY-MM-DD.json` files where emails were sent (status: "sent")
+- Uses that date as the starting point to only fetch issues resolved AFTER that date
+- If no thank-you files exist, falls back to last 14 days
+- This ensures we never send duplicate thank-you emails for the same resolved issues
+
+### Step 2: Customer Information Extraction
+**AI Agent does intelligent extraction**:
+1. **Go through each resolved issue**
+2. **Extract customer email** from:
+   - Issue title format: `email@domain.com: summary`
+   - Issue body: look for email patterns
+   - If no email found, extract customer name and use database lookup
+3. **Extract customer name** from:
+   - Issue title or body
+   - Previous thank-you notes
+   - Onboarding insights documents
+
+### Step 3: Database Lookup
+**AI Agent calls function for each customer**:
+```typescript
+// Look up executive by customer email
+const executive = await findExecutiveByEmail(customerEmail);
+
+// Get Ashley email address for this executive
+const ashleyEmail = await getAshleyEmailForExecutive(executive.id);
+```
+
+### Step 4: Collate Issues by Customer
+**AI Agent organizes data**:
+- Group all resolved issues by customer email
+- **Consolidate customers with multiple email addresses** by matching customer names (case-insensitive)
+- When a customer has multiple emails, use the primary email from the database lookup
+- Output customer list to console for verification
+
+### Step 5: Generate Single Thank-You File
+**AI Agent creates ONE file**:
+- File: `docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json`
+- Format: Structured JSON (not markdown) for easy parsing by mail sending script
+- Contains ALL customers and their personalized emails
+- **AI Agent writes the email content** - be creative, personal, and contextual!
+- Follow principles: personal touch, customer-focused, short and sweet, encourage feedback
+- **NO TECHNICAL JARGON**: Do not mention issue numbers, BAML, internal systems, or technical details
+- **CUSTOMER EXPERIENCE FOCUS**: Describe what was broken from the user's perspective, what was fixed, and how they can verify it works
+- **First-person Email Body**: Use "I" for actions Ashley took (e.g., "I fixed", "I now", "I will"), not "Ashley" or "she". Sign off as Ashley.
+- Include `From:` field showing Ashley email from PPE (via `getAshleyEmailForExecutive()`)
+
+**File format** (JSON):
+```json
+{
+   "metadata": {
+     "generatedOn": "2025-10-29T02:29:02.497Z",
+     "issuesResolvedSince": "2025-10-28",
+     "totalCustomers": 2,
+     "totalIssues": 3
+   },
+   "candidates": [
+     {
+       "customer": {
+         "name": "Olga Ivanova",
+         "email": "olga.ivanova@gmail.com"
+       },
+       "executive": {
+         "name": "Olga Ivanova",
+         "id": "exec-..."
+       },
+       "status": "pending",
+       "from": {
+         "displayName": "Ashley - Olga Ivanova's AI Executive Assistant",
+         "email": "ashley+olga@ashleycalendar.ai"
+       },
+       "to": "olga.ivanova@gmail.com",
+       "subject": "Thank you for your feedback - your issues have been addressed!",
+       "greeting": "Hi Olga,",
+       "opening": "Thank you for making me better! I wanted to personally reach out because your feedback helped us catch and fix an important bug.",
+       "improvements": [
+         {
+           "title": "Issue filing feature",
+           "description": "The issue filing feature is now working properly - when you ask me to file a bug or feature request through voice, I'll handle it correctly.",
+           "verification": "Try asking me to file a bug or feature request and it should work smoothly now."
+         }
+       ],
+       "closing": "Your quick feedback saved you (and others) frustration down the line. That kind of real-time input makes all the difference as I'm learning."
+     }
+   ]
+ }
+```
+
+**Note**: The structured format allows the HTML template to format each section beautifully:
+- `greeting`: Personal greeting (e.g., "Hi Olga,")
+- `opening`: Opening paragraph - thanks and context
+- `improvements[]`: Array of improvements (title, description, optional verification step)
+- `closing`: Closing paragraph - encouraging more feedback
+
+The HTML template formats each section with appropriate styling.
+
+### Step 6: User Review
+**AI Agent**:
+1. **Points user to the generated file**: `docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json`
+2. **Requests review** and any edits needed (user can edit JSON directly)
+3. **Waits for user approval** before proceeding
+
+**Note**: Each email section includes a `From:` field showing the display name and email address that will be used when sending. The signature includes a humble note about ramping up, without displaying a generic email address.
+
+### Step 7: Send Emails (Separate Command)
+**When user says "Send the emails" or similar**:
+
+**AI Agent calls function**:
+```typescript
+// Note: Retrieve script via get_fraim_file({ path: "scripts/generate-thank-you-emails.ts" }) and save to tmp/generate-thank-you-emails.ts
+import { sendCustomerMail } from './tmp/generate-thank-you-emails.ts';
+
+// Send emails from the candidates JSON file (all pending candidates)
+await sendCustomerMail('docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json');
+
+// OR send to a specific executive only (optional)
+await sendCustomerMail('docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json', 'exec-1761011032377-q36j91sdl');
+```
+
+**Note**: The `sendCustomerMail` function parses JSON (not markdown) for easy, deterministic parsing.
+
+**Function parameters**:
+- `candidatesFilePath` (required): Path to the JSON candidates file
+- `executiveId` (optional): If provided, only sends emails for candidates matching this executive ID. If omitted, sends to all pending candidates.
+
+**This function will**:
+- Parse the JSON candidates file
+- If `executiveId` is provided, filter to only that executive's candidates
+- For each candidate with `status: "pending"`, send email
+- Use the `from` field (displayName and email) specified in JSON
+- Use the `to`, `subject`, and `body` fields from JSON
+- Update the JSON file after each send with status: `"sent"` or `"failed"`
+- Skip candidates that already have status `"sent"` or `"failed"`
+
+## REQUIRED FUNCTIONS IN SCRIPT
+
+The script must provide these deterministic functions for AI agents to call:
+
+```typescript
+// Get resolved issues since a date
+export async function getResolvedIssues(date: string): Promise<ResolvedIssue[]>
+
+// Find executive by email in PPE database  
+export async function findExecutiveByEmail(email: string): Promise<Executive | null>
+
+// Get Ashley email for executive from PPE database
+export async function getAshleyEmailForExecutive(executiveId: string): Promise<string>
+
+// Send emails from candidates file
+// executiveId is optional - if provided, only sends to that executive; if omitted, sends to all pending
+export async function sendCustomerMail(candidatesFilePath: string, executiveId?: string): Promise<void>
+```
+
+**Note**: The script provides ONLY data retrieval and sending. The AI agent does ALL intelligent work:
+- Extracts customer info from issues (intelligent parsing)
+- Writes personalized, creative email content (better than hardcoded templates!)
+- Organizes and formats the candidates file
+
+## WORKFLOW COMPLETION
+
+**Generate workflow completes with**: Single candidates file ready for review
+**Send workflow completes with**: All emails sent and file updated with status