New Customer On boarding

You initiate the process by running the add-customer command with a display name and a Jira Epic key:

    uv run python main.py add-customer --name "Acme Corp" --epic CIPOE-123

Step-by-Step Execution Flow

1. Validation Check: The tool first checks if the Epic key (e.g., CIPOE-123) is already assigned to another customer. If the Epic or customer already exists, it stops and prompts you to use the sync command instead.

1. Portfolio Setup: The tool creates a dedicated directory for the new customer at data/customers/{customer_id}/. This folder will house all future data, including:

• A latest/ folder for current extractions and insights.
• An insights/ folder for individual issue analysis.
• A metadata.json file to track the sync state.

1. Initial Data Extraction: The tool fetches the specified Epic and its linked issues from Jira. Since this is a new customer, it treats this as a "First sync (migration)" and initializes all linked issues found in the extraction.

1. Sanitization:: All extracted data (descriptions, comments, etc.) is automatically sanitized to remove PII and secrets before processing.

1. Attachments:: Relevant attachments (images, PDFs, text) are downloaded to be included in the analysis.

1. AI Analysis (Baseline Generation): The tool runs the Gemini AI analysis on the extracted data. Because no previous state exists, it generates insights for all linked issues to establish a baseline.

1. Workflow Library Update: As the AI identifies workflow patterns for this new customer, the tool automatically updates the global Workflow Library. New patterns are deduplicated and added to the catalog, making them available for comparison with other customers.

1. State Saving: Finally, the tool saves the results:

1. Insights: Aggregated insights are saved to insights.json.

1. Metadata: The metadata.json file is updated to establish the "last sync" timestamp for every issue, ensuring future runs only process changes.

Running Weekly Updates / Increments

The update process is triggered using the sync command:

    uv run python main.py sync

You can also force a complete regeneration of all insights regardless of changes using the --force flag.

The tool uses a Central Issue Pool and per-issue timestamps to minimize API costs.

1. Jira Check: The tool fetches the current "Updated" timestamp for all issues linked to a customer's Epic.

1. Pool Verification: It checks data/issues/{KEY}/metadata.json to see if a fresh copy exists.

1. Selective Execution:

• • Fresh: Skipped (0 API calls).
  • Stale/Missing: The issue is extracted and analyzed using Gemini, then saved to the Pool.

1. Aggregation: The final report is built by aggregating pointers from the customer's portfolio to the Central Pool.

1. Library Synchronization

Unless the --skip-library flag is used, the update process automatically scans the fresh insights for new workflow patterns. Any newly discovered patterns are deduplicated and added to the global workflow library.