==================================================
 STORYGEN AI — STORY EXPORT
==================================================
Story ID:           27
Title:              Test Marketing Manager
Owner:              Raul Adrian A. Altavano - Full Stack Developer <raul.altavano@educlaas.com>
App Type:           Agentic AI App
Input Type:         file
Status:             features_generated
Source File:        Marketing_Manager_App_SOP.docx
Created:            2026-04-29 09:25:54 UTC
Updated:            2026-04-29 09:38:01 UTC
Features Generated: 2026-04-29 09:38:01 UTC
Total Clusters:     8
Total Features:     20

--- ORIGINAL INPUT ---
Department: Marketing
Function: Performance Marketing – Marketing Manager App
Version: V1.0
Roles:
MM – Marketing Manager (Primary User – Management Only)
System – Marketing Manager Application System
AI Engine – AI Insights &amp; Optimization Engine
Data Engine – KPI Aggregation Processor
Feature 1 – Campaign Code Selection &amp; Centralized Aggregation
The Marketing Manager App does NOT create campaigns.It only centralizes and manages existing campaigns.
Feature 2 – KPI Dashboard ()
KPI Dashboard reflects metrics per campaign type and per campaign objective.
Feature 3 – AI Generated Insights
AI analyzes KPI performance per campaign and per platform.
Feature 4 – Optimization Plan (Per Campaign)
Optimization is created per campaign based on AI insights. 
Feature 5 – Implementation Checklist
Once optimization is approved, checklist is created.
Feature 6 – Continuous Performance Loop
After implementation, the system re-evaluates performance.

--- USER STORY ---
# Marketing Manager Agentic Performance Optimization App

## Overview
This is an **Agentic AI App** for the Marketing department's Performance Marketing function. It empowers Marketing Managers to centralize existing campaigns across platforms, monitor KPIs in real time, and rely on autonomous AI agents to generate insights, propose optimization plans, and drive a continuous performance improvement loop. The Marketing Manager remains the decision authority while the agents handle analysis, recommendation, and follow-through.

## Actors
- **Marketing Manager (MM)**: Primary human user (management only). Selects campaigns to centralize, reviews AI-generated insights, approves or rejects optimization plans, and oversees the implementation checklist.
- **Marketing Manager Application System (System)**: Hosts the dashboard, orchestrates agent workflows, manages campaign codes, and stores aggregated KPI data.
- **Data Engine (KPI Aggregation Processor)**: Autonomous agent that ingests campaign data from connected ad platforms, normalizes metrics, and aggregates KPIs by campaign type and objective.
- **AI Insights & Optimization Engine (AI Engine)**: Autonomous agent that analyzes KPI performance per campaign and per platform, generates insights, proposes per-campaign optimization plans, builds implementation checklists, and re-evaluates performance after changes go live.

## Goals
- Provide a single, centralized command center for the Marketing Manager to oversee all active campaigns without creating them.
- Use autonomous AI to convert raw KPI data into actionable, campaign-specific optimization plans.
- Establish a closed-loop, continuous improvement cycle that measurably improves campaign performance over time.
- Keep the Marketing Manager firmly in control of all approval decisions while removing manual analysis effort.

## User Story
As a **Marketing Manager**, I want to **centralize my existing campaigns and have AI agents autonomously analyze KPIs, recommend optimizations, and track implementation through a continuous feedback loop**, so that **I can improve campaign performance with data-driven decisions while focusing my time on strategic approvals rather than manual analysis**.

## Detailed Workflow

### 1. Campaign Code Selection & Centralized Aggregation (Feature 1)
1. MM logs into the Marketing Manager App.
2. MM enters or selects existing **Campaign Codes** for campaigns already running on external platforms (Meta, Google, TikTok, LinkedIn, etc.).
3. The System validates each campaign code and registers the campaign in the central registry. *The app does not create campaigns; it only centralizes them.*
4. The **Data Engine** is triggered to begin pulling performance data for each registered campaign on a recurring schedule.

### 2. KPI Dashboard (Feature 2)
5. The **Data Engine** autonomously aggregates raw metrics from each platform and normalizes them.
6. KPIs are organized and displayed on the dashboard **per campaign type** (e.g., awareness, lead generation, conversion) and **per campaign objective**.
7. MM views consolidated KPIs across all centralized campaigns in one place.

### 3. AI Generated Insights (Feature 3)
8. The **AI Engine** autonomously runs analysis on each campaign's KPIs and benchmarks performance per platform.
9. The AI Engine produces written insights such as underperforming creatives, audience saturation, budget pacing issues, and platform-level anomalies.
10. If data confidence is low or data is incomplete, the AI Engine flags this and **defers to the MM** rather than producing a speculative insight.
11. Insights are surfaced on the dashboard, tagged by severity and campaign.

### 4. Optimization Plan – Per Campaign (Feature 4)
12. For each campaign with material insights, the **AI Engine** autonomously generates an **Optimization Plan** (e.g., shift budget, refresh creative, narrow audience, change bidding strategy).
13. Each plan includes: rationale, expected impact, risk level, and required actions.
14. The plan is presented to the MM for review.
15. MM **approves, edits, or rejects** the plan. No optimization is executed without MM approval.

### 5. Implementation Checklist (Feature 5)
16. Once approved, the **AI Engine** auto-generates an **Implementation Checklist** with discrete tasks, owners, and deadlines.
17. The System tracks checklist completion status. The MM marks tasks complete as the underlying changes are made on the ad platforms.
18. The AI Engine sends reminders for overdue tasks and escalates to the MM if a checklist stalls beyond a defined threshold.

### 6. Continuous Performance Loop (Feature 6)
19. After implementation, the **Data Engine** continues collecting fresh KPI data.
20. The **AI Engine** re-evaluates performance against the pre-implementation baseline and the optimization plan's expected impact.
21. The agent autonomously decides:
    - **If improved as expected** → mark optimization successful, log learning, monitor.
    - **If marginal/no change** → generate a new optimization plan (back to Step 12).
    - **If degraded** → raise an alert and recommend rollback, deferring to MM.
22. The cycle continues, building an institutional knowledge base of what works per campaign type and platform.

## Acceptance Criteria

### Functional
- The app allows the MM to register existing campaign codes but provides **no functionality to create new campaigns**.
- The KPI Dashboard displays metrics segmented by **campaign type** and **campaign objective**.
- AI insights are generated **per campaign and per platform** and updated at least daily.
- An optimization plan is generated **per individual campaign**, never as a generic recommendation.
- The implementation checklist is created **only after MM approval** of an optimization plan.
- The continuous performance loop automatically re-evaluates each campaign post-implementation against a stored baseline.

### Agent Guardrails & Behavior
- The AI Engine must **never execute changes directly on ad platforms** — it only proposes; the MM approves; humans implement.
- If KPI data is missing, stale (>48h), or below a confidence threshold, the AI Engine must **suppress recommendations and flag the issue** to the MM.
- The AI Engine must include a **rationale and expected impact** with every optimization proposal; recommendations without rationale are blocked.
- If post-implementation performance **degrades by more than a configured threshold**, the agent must **stop generating further optimizations** for that campaign and escalate to the MM.
- The agent must cap automatic re-optimization cycles per campaign (e.g., max 3 consecutive cycles without MM strategic review) to prevent runaway loops.
- All agent actions, recommendations, and decisions are logged in an **audit trail** viewable by the MM.

### Access & Control
- Only users with the **Marketing Manager (Management)** role can access the app.
- Approval/rejection of optimization plans is restricted to the MM role.

## Assumptions & Constraints
- Existing campaigns are already created and running on external ad platforms; the app integrates via APIs to pull data using campaign codes.
- The Data Engine has authenticated read access to all relevant ad platforms.
- KPI definitions per campaign type and objective are pre-configured in the system.
- The MM (or their designated team) is responsible for executing approved checklist items on the ad platforms — the app does not push changes to platforms in V1.0.
- AI insights and optimization quality depend on data completeness; gaps in platform connectivity will limit agent effectiveness.
- This is V1.0; future versions may extend agent autonomy to direct platform actions once trust and guardrails mature.

--- FEATURE LIST SUMMARY ---
This solution enables a Marketing Manager to centralize existing multi-platform campaigns and let autonomous AI agents analyze KPIs, propose optimizations, and run a closed-loop continuous improvement cycle. The primary actors are the Marketing Manager (sole human approver), the Data Engine agent for KPI aggregation, and the AI Insights & Optimization Engine for analysis and planning. The flow moves from campaign-code registration, to dashboard monitoring, to AI insights, to per-campaign optimization plans, to MM-approved implementation checklists, and finally to post-implementation re-evaluation. The Master Data Configuration cluster holds users/roles, platform connections, KPI definitions, campaign types/objectives, and guardrail thresholds. The list contains 16 rows whose top capabilities are autonomous KPI analysis, human-in-the-loop optimization approvals, and continuous performance learning.

Feature Clusters & Features:
• Master Data Configuration
  - 1. User and Role Management — Defines Marketing Manager accounts and the management-only role that gates all approval actions in the app.
  - 2. Ad Platform Connection Registry — Stores authenticated read-only API connections to Meta, Google, TikTok, LinkedIn and other ad platforms.
  - 3. KPI Definition Catalog — Pre-configured KPI metrics, formulas, and benchmarks organized by campaign type and objective for consistent measurement.
  - 4. Campaign Type and Objective Reference — Lookup catalog of campaign types (awareness, lead-gen, conversion) and objectives used to segment dashboards and insights.
  - 5. Agent Guardrail Configuration — Configurable thresholds for data freshness, confidence, degradation limits, and max re-optimization cycles that constrain AI behavior.
• Campaign Centralization
  - 6. Campaign Code Registration — Lets the MM register existing external campaign codes into a central registry without creating new campaigns.
  - 7. Campaign Code Validation and Activation — Validates each submitted code against the connected platform and activates recurring data ingestion.
• KPI Aggregation and Monitoring
  - 8. Automated KPI Data Ingestion — Data Engine pulls raw campaign metrics from each connected ad platform on a recurring schedule.
  - 9. KPI Normalization and Aggregation — Normalizes platform-specific metrics into a unified schema and aggregates them by campaign, type, and objective.
  - 10. Centralized KPI Dashboard — Displays consolidated KPIs across all centralized campaigns segmented by campaign type and objective.
• AI Insights Generation
  - 11. AI Insight Generation per Campaign and Platform — AI Engine analyzes KPIs and produces written, severity-tagged insights for each campaign and platform.
  - 12. Data Quality and Confidence Gating — Detects stale, missing, or low-confidence data and suppresses recommendations while flagging the issue to the MM.
• Optimization Planning and Approval
  - 13. Per-Campaign Optimization Plan Generation — AI Engine produces tailored optimization plans with rationale, expected impact, risk level, and required actions.
  - 14. Optimization Plan Review and Approval — MM reviews, edits, approves, or rejects each AI-generated plan; nothing proceeds without explicit approval.
• Implementation Tracking
  - 15. AI-Generated Implementation Checklist — Auto-creates discrete tasks with owners and deadlines after plan approval and tracks completion progress.
  - 16. Checklist Reminder and Escalation — Sends reminders for overdue tasks and escalates stalled checklists to the MM beyond a defined threshold.
• Continuous Performance Loop
  - 17. Post-Implementation Re-Evaluation — Data Engine refreshes KPIs and AI Engine compares results to baseline and expected impact for each optimization.
  - 18. Autonomous Loop Decisioning and Degradation Alerts — Agent decides to mark success, generate a new plan, or halt and escalate on degradation, capping re-optimization cycles.
• Agent Orchestration and Audit
  - 19. Institutional Learning Knowledge Base — Captures successful and failed optimizations per campaign type and platform to improve future agent recommendations.
  - 20. Agent Audit Trail and Action Log — Records every agent recommendation, decision, and MM action for transparent review and governance.

--- FEATURE LIST (20 features across 8 clusters) ---

#1 | Cluster: Master Data Configuration | Feature: User and Role Management
  Description: Central authority for user accounts and the management-only role that controls who can register campaigns and approve optimization plans. Access to all app features is gated by this role.
  Workflow:
    1. Admin creates a user record for the Marketing Manager.
    2. Admin assigns the Marketing Manager (Management) role.
    3. System enforces role-based access on every protected feature.
    4. Role assignments and changes are logged for audit.
  Table:       users_roles
  Columns:     id (bigint, pk), email (varchar 255), full_name (varchar 255), role (varchar 50), is_active (boolean), created_at (timestamp), updated_at (timestamp)
  Actor:       System Administrator
  AI Agent:    None
  ----
#2 | Cluster: Master Data Configuration | Feature: Ad Platform Connection Registry
  Description: Stores read-only API connections to all supported ad platforms used by the Data Engine. These connections are the foundation for centralized KPI ingestion.
  Workflow:
    1. Admin registers an ad platform (Meta, Google, TikTok, LinkedIn).
    2. Admin stores authenticated API credentials/tokens.
    3. System validates connectivity with a test call.
    4. Connection status is monitored and surfaced to the MM.
  Table:       ad_platform_connections
  Columns:     id (bigint, pk), platform_name (varchar 50), auth_token (text, encrypted), status (varchar 20), last_validated_at (timestamp), created_at (timestamp)
  Actor:       System Administrator
  AI Agent:    Data Engine Agent
  ----
#3 | Cluster: Master Data Configuration | Feature: KPI Definition Catalog
  Description: Pre-configured KPI metrics, formulas, and benchmarks segmented by campaign type and objective. Drives consistent measurement and AI benchmarking.
  Workflow:
    1. Admin defines KPI metrics (CPA, CTR, ROAS, etc.).
    2. Each KPI is mapped to formulas and benchmarks.
    3. KPIs are tied to campaign types and objectives.
    4. Catalog is referenced during ingestion and analysis.
  Table:       kpi_definitions
  Columns:     id (bigint, pk), kpi_code (varchar 50), kpi_name (varchar 100), formula (text), benchmark_value (decimal), campaign_type (varchar 50), objective (varchar 50)
  Actor:       System Administrator
  AI Agent:    AI Insights & Optimization Engine
  ----
#4 | Cluster: Master Data Configuration | Feature: Campaign Type and Objective Reference
  Description: Lookup catalog of campaign types and objectives used to organize KPIs, insights, and optimization plans. Ensures consistent segmentation everywhere in the app.
  Workflow:
    1. Admin defines campaign types (awareness, lead-gen, conversion).
    2. Admin defines associated objectives.
    3. System uses these as segmentation keys on dashboards.
    4. Reference values are reused across registrations and insights.
  Table:       campaign_type_objectives
  Columns:     id (bigint, pk), campaign_type (varchar 50), objective (varchar 50), description (text), is_active (boolean)
  Actor:       System Administrator
  AI Agent:    None
  ----
#5 | Cluster: Master Data Configuration | Feature: Agent Guardrail Configuration
  Description: Configurable thresholds that constrain AI agent behavior including data freshness, confidence, degradation limits, and max re-optimization cycles. Prevents runaway agent loops and unsafe recommendations.
  Workflow:
    1. Admin sets data freshness threshold (e.g., 48h).
    2. Admin sets minimum data confidence threshold.
    3. Admin sets degradation threshold and max re-optimization cycles.
    4. AI Engine reads these values before every action.
  Table:       agent_guardrails
  Columns:     id (bigint, pk), data_freshness_hours (int), confidence_threshold (decimal), degradation_threshold_pct (decimal), max_reopt_cycles (int), updated_at (timestamp)
  Actor:       System Administrator
  AI Agent:    AI Insights & Optimization Engine
  ----
#6 | Cluster: Campaign Centralization | Feature: Campaign Code Registration
  Description: Allows the Marketing Manager to register existing campaign codes for centralized monitoring without creating new campaigns. Establishes the campaign registry that drives all downstream analysis.
  Workflow:
    1. MM logs into the app.
    2. MM enters or selects existing campaign codes from external platforms.
    3. MM tags each with platform, type, and objective.
    4. System stores the campaign in the central registry.
    5. System schedules data ingestion.
  Table:       centralized_campaigns
  Columns:     id (bigint, pk), campaign_code (varchar 100), platform_id (bigint, fk), campaign_type (varchar 50), objective (varchar 50), registered_by (bigint, fk), status (varchar 20), created_at (timestamp)
  Actor:       Marketing Manager
  AI Agent:    None
  ----
#7 | Cluster: Campaign Centralization | Feature: Campaign Code Validation and Activation
  Description: Validates each registered code against its source ad platform and activates the campaign for recurring KPI ingestion. Ensures only legitimate, reachable campaigns enter the loop.
  Workflow:
    1. System calls platform API to verify the code exists.
    2. System retrieves basic campaign metadata.
    3. If valid, campaign is activated for ingestion.
    4. If invalid, MM is notified to correct the code.
  Table:       campaign_validation_log
  Columns:     id (bigint, pk), campaign_id (bigint, fk), validation_status (varchar 20), platform_response (text), validated_at (timestamp)
  Actor:       Marketing Manager Application System
  AI Agent:    Data Engine Agent
  ----
#8 | Cluster: KPI Aggregation and Monitoring | Feature: Automated KPI Data Ingestion
  Description: Data Engine autonomously pulls raw performance metrics from each connected ad platform on a recurring schedule. Forms the data backbone for all dashboards and AI analysis.
  Workflow:
    1. Data Engine schedules pulls per campaign.
    2. Agent calls each platform API using stored credentials.
    3. Raw metrics are stored with timestamps.
    4. Failures and stale data are flagged.
  Table:       raw_kpi_ingestion
  Columns:     id (bigint, pk), campaign_id (bigint, fk), platform_id (bigint, fk), metric_payload (jsonb), pulled_at (timestamp), status (varchar 20)
  Actor:       Data Engine Agent
  AI Agent:    Data Engine Agent
  ----
#9 | Cluster: KPI Aggregation and Monitoring | Feature: KPI Normalization and Aggregation
  Description: Normalizes raw platform metrics into a unified KPI schema and aggregates them by campaign, type, and objective. Enables apples-to-apples comparison across platforms.
  Workflow:
    1. Agent maps platform-specific fields to KPI catalog.
    2. Agent computes derived KPIs using stored formulas.
    3. Aggregates are produced per campaign, type, and objective.
    4. Normalized data is written to the analytics store.
  Table:       kpi_aggregates
  Columns:     id (bigint, pk), campaign_id (bigint, fk), kpi_code (varchar 50), value (decimal), period_start (date), period_end (date), computed_at (timestamp)
  Actor:       Data Engine Agent
  AI Agent:    Data Engine Agent
  ----
#10 | Cluster: KPI Aggregation and Monitoring | Feature: Centralized KPI Dashboard
  Description: Single command center displaying consolidated KPIs across all centralized campaigns, segmented by campaign type and objective. Gives the MM at-a-glance visibility into performance.
  Workflow:
    1. MM opens the dashboard.
    2. System loads aggregated KPIs across all campaigns.
    3. Views are segmented by campaign type and objective.
    4. MM filters and drills down by platform or campaign.
  Table:       dashboard_views
  Columns:     id (bigint, pk), user_id (bigint, fk), filter_config (jsonb), last_viewed_at (timestamp)
  Actor:       Marketing Manager
  AI Agent:    Data Engine Agent
  ----
#11 | Cluster: AI Insights Generation | Feature: AI Insight Generation per Campaign and Platform
  Description: AI Engine autonomously analyzes KPIs and generates written, severity-tagged insights for each campaign and platform. Surfaces issues like underperforming creatives, audience saturation, and pacing anomalies.
  Workflow:
    1. AI Engine reads latest KPI aggregates per campaign.
    2. Agent benchmarks against catalog and historical baselines.
    3. Agent produces written insights with severity tags.
    4. Insights are surfaced on the dashboard at least daily.
  Table:       ai_insights
  Columns:     id (bigint, pk), campaign_id (bigint, fk), platform_id (bigint, fk), insight_text (text), severity (varchar 20), confidence_score (decimal), generated_at (timestamp)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#12 | Cluster: AI Insights Generation | Feature: Data Quality and Confidence Gating
  Description: Detects stale, missing, or low-confidence data and suppresses speculative AI recommendations, deferring to the Marketing Manager. Protects decision quality by preventing weak insights.
  Workflow:
    1. Agent checks data freshness against guardrail.
    2. Agent computes confidence score for the dataset.
    3. If thresholds fail, recommendations are suppressed.
    4. A data-quality flag is raised to the MM.
  Table:       data_quality_flags
  Columns:     id (bigint, pk), campaign_id (bigint, fk), flag_type (varchar 50), details (text), confidence_score (decimal), raised_at (timestamp)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#13 | Cluster: Optimization Planning and Approval | Feature: Per-Campaign Optimization Plan Generation
  Description: AI Engine autonomously generates per-campaign optimization plans complete with rationale, expected impact, and risk level. Plans without rationale are blocked by guardrails.
  Workflow:
    1. Agent selects campaigns with material insights.
    2. Agent drafts optimization actions (budget, creative, audience, bidding).
    3. Agent attaches rationale, expected impact, and risk level.
    4. Plan is queued for MM review.
  Table:       optimization_plans
  Columns:     id (bigint, pk), campaign_id (bigint, fk), proposed_actions (jsonb), rationale (text), expected_impact (text), risk_level (varchar 20), status (varchar 20), generated_at (timestamp)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#14 | Cluster: Optimization Planning and Approval | Feature: Optimization Plan Review and Approval
  Description: Marketing Manager reviews each AI-generated plan and approves, edits, or rejects it; nothing advances without explicit approval. Keeps the human firmly in control of all optimizations.
  Workflow:
    1. MM opens the pending plan.
    2. MM reviews rationale and expected impact.
    3. MM approves, edits, or rejects the plan.
    4. Decision is logged with timestamp and reasoning.
  Table:       plan_decisions
  Columns:     id (bigint, pk), plan_id (bigint, fk), decided_by (bigint, fk), decision (varchar 20), edits (jsonb), notes (text), decided_at (timestamp)
  Actor:       Marketing Manager
  AI Agent:    AI Insights & Optimization Engine
  ----
#15 | Cluster: Implementation Tracking | Feature: AI-Generated Implementation Checklist
  Description: Auto-generates a structured checklist of implementation tasks with owners and deadlines after plan approval. The MM tracks execution as changes are made manually on ad platforms.
  Workflow:
    1. On approval, agent generates discrete tasks.
    2. Each task has owner, deadline, and acceptance criteria.
    3. Checklist is published to the MM.
    4. MM marks tasks complete as platform changes are made.
  Table:       implementation_checklists
  Columns:     id (bigint, pk), plan_id (bigint, fk), task_description (text), owner_id (bigint, fk), deadline (date), status (varchar 20), completed_at (timestamp)
  Actor:       Marketing Manager
  AI Agent:    AI Insights & Optimization Engine
  ----
#16 | Cluster: Implementation Tracking | Feature: Checklist Reminder and Escalation
  Description: Sends automated reminders for overdue checklist tasks and escalates stalled implementations to the Marketing Manager. Ensures approved optimizations actually get executed on time.
  Workflow:
    1. Agent monitors task deadlines.
    2. Reminders are sent for upcoming and overdue tasks.
    3. If a checklist stalls beyond threshold, MM is escalated.
    4. Escalation events are logged.
  Table:       checklist_reminders
  Columns:     id (bigint, pk), checklist_id (bigint, fk), reminder_type (varchar 30), sent_at (timestamp), escalated (boolean)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#17 | Cluster: Continuous Performance Loop | Feature: Post-Implementation Re-Evaluation
  Description: Data Engine refreshes KPIs and the AI Engine compares post-implementation results to the pre-implementation baseline and expected impact. Establishes whether each optimization actually worked.
  Workflow:
    1. Data Engine refreshes KPIs after implementation.
    2. AI Engine compares results to stored baseline.
    3. Agent measures actual impact against expected impact.
    4. Result is recorded against the originating plan.
  Table:       post_impl_evaluations
  Columns:     id (bigint, pk), plan_id (bigint, fk), baseline_snapshot (jsonb), post_snapshot (jsonb), impact_delta (decimal), outcome (varchar 30), evaluated_at (timestamp)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#18 | Cluster: Continuous Performance Loop | Feature: Autonomous Loop Decisioning and Degradation Alerts
  Description: Agent autonomously decides next action based on outcome — log success, generate new plan, or halt and escalate on degradation — while respecting max re-optimization cycle caps. Drives the closed-loop continuous improvement cycle safely.
  Workflow:
    1. Agent classifies outcome as improved, marginal, or degraded.
    2. If improved, agent logs success and continues monitoring.
    3. If marginal, agent generates a new optimization plan (capped by max cycles).
    4. If degraded beyond threshold, agent halts and escalates to MM with rollback recommendation.
  Table:       loop_decisions
  Columns:     id (bigint, pk), campaign_id (bigint, fk), evaluation_id (bigint, fk), decision (varchar 30), cycle_count (int), escalated (boolean), decided_at (timestamp)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#19 | Cluster: Agent Orchestration and Audit | Feature: Institutional Learning Knowledge Base
  Description: Captures successful and failed optimizations per campaign type and platform to build organizational learning. Improves the quality of future AI recommendations over time.
  Workflow:
    1. Agent records outcome of every optimization.
    2. Patterns are tagged by campaign type and platform.
    3. Successful and failed plays are indexed for retrieval.
    4. Future plan generation references this knowledge base.
  Table:       agent_knowledge_base
  Columns:     id (bigint, pk), campaign_type (varchar 50), platform_id (bigint, fk), play_pattern (text), outcome (varchar 30), evidence_refs (jsonb), recorded_at (timestamp)
  Actor:       AI Insights & Optimization Engine
  AI Agent:    AI Insights & Optimization Engine
  ----
#20 | Cluster: Agent Orchestration and Audit | Feature: Agent Audit Trail and Action Log
  Description: Records every AI agent recommendation, decision, and human action in a transparent, queryable audit trail. Provides governance and accountability for autonomous behavior.
  Workflow:
    1. Every agent action and decision is logged with context.
    2. MM approvals/rejections are linked to the originating plan.
    3. MM can view a full timeline per campaign.
    4. Logs are retained for governance and review.
  Table:       agent_audit_log
  Columns:     id (bigint, pk), actor_type (varchar 30), actor_id (bigint), entity_type (varchar 50), entity_id (bigint), action (varchar 50), payload (jsonb), occurred_at (timestamp)
  Actor:       Marketing Manager
  AI Agent:    AI Insights & Optimization Engine
  ----

==================================================
 END OF STORY EXPORT
==================================================
