Run Metrics

Run Metrics

When to Use

• Generating monthly or custom-range metrics reports
• Reviewing adoption rates and comment quality across languages
• Producing charts for metrics visualization
• Reviewing companion quality trends across recent months
• Saving finalized metrics to the database (only when user explicitly requests)

Defaults

Unless the user says otherwise, always apply these defaults:

• Environment: production
• Charts: Always include --charts
• Languages: All languages (do not pass --exclude)
• Save: Do NOT pass --save unless the user explicitly asks to save (e.g. "save it", "persist", "write to DB")
• Format: JSON output (UTF-8 encoded)
• Quality trends follow-up: If the user asks for metrics but does not explicitly ask for quality trends, ask a short follow-up after sharing the metrics results: "Do you want the quality trends chart for the same period too?"
• Quality trends auto-run: If the user explicitly asks for quality trends, comment trends, or asks broadly for charts/trends/quality, also run the companion quality-trends report for the same period.

Date Resolution

The user will typically specify a calendar month by name (e.g. "March", "January 2025"). Resolve to the full month date range:

When only a month name is given without a year, use the current year. Be careful with month lengths (28/29/30/31 days).

Running Metrics

Step 1: Run the Command

Show the resolved command and run it immediately in a single foreground terminal invocation with a 180-second timeout (timeout: 180000). Before running, clean up stale output so you never accidentally present old results.

Important: Do NOT use 2>&1 — that merges stderr log messages (e.g. "Saved: output\charts\adoption.png") into the JSON output file, producing invalid JSON. Pipe stdout through Out-File -Encoding UTF8 so the output file is always valid UTF-8 JSON.

Full terminal command (cleanup + run):

New-Item -ItemType Directory -Path output -Force | Out-Null; if (Test-Path output/metrics_output.json) { Remove-Item output/metrics_output.json }; if (Test-Path output/charts) { Remove-Item output/charts/* -Force }; python cli.py report metrics -s <start_date> -e <end_date> --charts | Out-File -Encoding UTF8 output/metrics_output.json

After the command completes, read the output file with read_file to get the JSON results — do NOT use a separate terminal command. Then use view_image (not a terminal command) to display the chart PNGs. This means the entire workflow requires only one terminal invocation.

Examples

# March 2025, production, all languages, with charts (typical request)
python cli.py report metrics -s 2025-03-01 -e 2025-03-31 --charts

# Staging environment
python cli.py report metrics -s 2025-03-01 -e 2025-03-31 --charts --environment staging

# Exclude specific languages
python cli.py report metrics -s 2025-03-01 -e 2025-03-31 --charts --exclude Java Golang

# Custom date range
python cli.py report metrics -s 2025-03-10 -e 2025-03-20 --charts

# Save to database (ONLY when user explicitly requests)
python cli.py report metrics -s 2025-03-01 -e 2025-03-31 --charts --save

Companion Quality Trends

The quality-trends report is the companion chart view for metrics work.

• If the user explicitly asks for quality trends, comment trends, or a broader trends/chart view, run it automatically for the same time window.
• If the user only asked for metrics, ask whether they want the quality trends chart too after presenting the metrics result.

Translating the date window

The quality-trends command uses --months plus an optional --end-date, not a start date. Convert the requested metrics window into an inclusive calendar-month count:

Use the same resolved end date from the metrics request for --end-date.

Quality trends command

if (Test-Path output/charts/comment_bucket_trends.png) { Remove-Item output/charts/comment_bucket_trends.png -Force }; python cli.py report quality-trends --months <month_count> --end-date <end_date>

Optional additions:

• --environment staging
• --languages Python CSharp C# Java TypeScript JavaScript Go
• --exclude-human
• --neutral

After it completes, summarize the terminal output and use view_image to show the saved chart at output/charts/comment_bucket_trends.png.