X Analytics Import

X Analytics Import

Overview

Use this skill to turn X Analytics CSV exports into validated, normalized, private local snapshots. The deterministic engine is scripts/x_analytics_import.py; it uses only the Python standard library and has no network, browser, Git, or publishing side effects.

The operating rule is simple:

first run: inspect -> validate-only -> dry-run -> full-import
later runs: inspect -> validate-only -> dry-run -> incremental-import -> compare

Read references/operations.md only when command detail or recovery guidance is needed.

When to Use

Use this skill when:

• Overview, content, or video analytics CSVs are available locally.
• A first normalized baseline must be established.
• New exports must be added without duplicating prior imports.
• Two snapshots must be compared using matched coverage.
• Lane rules changed and historical posts must be reclassified.

Do not use this skill when:

• The exports still need to be downloaded from X.
• The task is to post, reply, follow, message, or modify an X account.
• The data comes from GA4, Search Console, or another analytics product.
• The user wants raw exports copied into Git or published.

Safety Contract

1. Treat raw exports, normalized rows, post text, post links, source hashes, revenue fields, and lane results as sensitive.
2. Select exact files by path, date coverage, and modification time. Never trust alphabetical glob order.
3. Run inspect, validate-only, and dry-run before every write mode.
4. Store outputs outside repositories, normally under ~/.hermes/data/x-analytics-import.
5. Never copy, rename, overwrite, stage, commit, or publish raw CSVs.
6. Never use --force unless the user explicitly requests an identical re-import.
7. A successful import does not authorize updates to notes, dashboards, websites, or Git.

Modes

Workflow

1. Identify the exact export set

Expected file families:

account_overview_analytics*.csv
account_analytics_content_<start>_<end>.csv
video_overview_analytics*.csv

Video is optional. Confirm the files belong to the intended export run. Chrome suffixes such as (1) are not chronology.

Completion criterion: every selected file has an exact path, plausible coverage, and no stale duplicate has been substituted.

2. Choose the run type

• No completed manifest exists: follow First baseline.
• A completed manifest exists and the exports are newer: follow Recurring refresh.
• The same source hashes already exist: stop at already_imported.

Completion criterion: the agent can name the prior import ID or state that no baseline exists.

3. First baseline

Run, in order:

inspect
validate-only
dry-run
full-import

Use the same exact file paths for all four stages. Stop before full-import when validation fails, reconciliation fails, or file pairing is doubtful.

After full-import, verify:

• A completed manifest and normalized snapshot exist.
• Validation, reconciliation, classification, analysis, and public-safe reports exist.
• Manifest hashes match the selected inputs.
• Date coverage and partial-day status are recorded.
• Re-running the same files with incremental-import returns already_imported.

Completion criterion: one verified baseline exists and duplicate protection is proven.

4. Recurring refresh

Run, in order:

inspect
validate-only
dry-run
incremental-import
compare-snapshots

Use incremental-import for ordinary future runs. If it returns already_imported, do not force a duplicate and do not create a comparison.

Compare the new snapshot against the previous completed snapshot. Use the original baseline only for a separate long-range view.

Comparison rules:

• Use overlapping overview dates.
• Use matched post IDs for post-level deltas.
• Report new and removed post IDs separately.
• Do not subtract whole rolling-window totals when coverage differs.

Completion criterion: a new import is either safely rejected as duplicate or written once and compared on matched coverage.