metrics-report

name	metrics-report
description	Produce a formatted metrics report with key indicators, trends, and recommendations

Metrics Report

When to Use

Use this skill when tasked with producing a metrics report, dashboard summary, or performance assessment with quantitative data.

Output Template

# Metrics Report: [Subject]

**Period:** [start date] to [end date]
**Author:** [agent name]
**Date:** YYYY-MM-DD

## Key Metrics

| Metric | Value | Previous | Change | Status |
|--------|-------|----------|--------|--------|
| [name] | [current] | [prior period] | [+/-N%] | [up/down/stable] |

## Trends
[Analysis of patterns over time]

## Recommendations
1. **[Action]** — because [metric] shows [specific value/trend]
2. **[Action]** — because [metric] shows [specific value/trend]

Procedure

1. Collect Raw Data

From task board:

echo "=== Task Metrics ==="
# Total tasks by status
bash /home/shared/scripts/task.sh list 2>/dev/null | jq '
  group_by(.status) | map({status: .[0].status, count: length})
' 2>/dev/null

# Tasks completed per agent
bash /home/shared/scripts/task.sh list --status completed 2>/dev/null | jq '
  group_by(.owner) | map({owner: .[0].owner, completed: length})
' 2>/dev/null

# Average time to completion (if timestamps available)
bash /home/shared/scripts/task.sh list --status completed 2>/dev/null | jq '
  [.[] | select(.created_at and .completed_at) |
    ((.completed_at | split("T")[0] | split("-") | .[2] | tonumber) -
     (.created_at | split("T")[0] | split("-") | .[2] | tonumber))
  ] | if length > 0 then {avg_days: (add/length), count: length} else "no timing data" end
' 2>/dev/null

From log files:

echo "=== Log Metrics ==="
LOG_DIR="${1:-/var/log}"

# Error rate
TOTAL=$(wc -l "$LOG_DIR"/*.log 2>/dev/null | tail -1 | awk '{print $1}')
ERRORS=$(grep -ci 'error\|fail\|exception' "$LOG_DIR"/*.log 2>/dev/null | awk -F: '{sum+=$2}END{print sum}')
echo "Total log lines: $TOTAL"
echo "Error lines: $ERRORS"
[ "$TOTAL" -gt 0 ] && echo "Error rate: $(echo "scale=2; $ERRORS * 100 / $TOTAL" | bc)%"

From system metrics:

echo "=== System Metrics ==="
# Disk usage
df -h / 2>/dev/null | awk 'NR==2{print "Disk used:", $3, "of", $2, "("$5")"}'

# Process count
ps aux 2>/dev/null | wc -l | xargs -I{} echo "Running processes: {}"

# Memory (Linux)
free -h 2>/dev/null | awk '/^Mem:/{print "Memory used:", $3, "of", $2}'

From git history:

cd ~/workspace 2>/dev/null

echo "=== Development Metrics ==="
# Commits per day (last 7 days)
for i in $(seq 0 6); do
  DATE=$(date -d "$i days ago" +%Y-%m-%d 2>/dev/null || date -v-${i}d +%Y-%m-%d 2>/dev/null)
  COUNT=$(git log --oneline --after="$DATE 00:00" --before="$DATE 23:59" 2>/dev/null | wc -l | tr -d ' ')
  echo "  $DATE: $COUNT commits"
done

# Lines changed (last 7 days)
git diff --shortstat "HEAD@{7 days ago}" HEAD 2>/dev/null

2. Compute Metrics

For each metric, compute:

• Current value (this period)
• Previous value (prior period for comparison)
• Change (absolute and percentage)
• Status (improving, declining, stable)

# Example: compute change
CURRENT=42
PREVIOUS=38

if [ "$PREVIOUS" -gt 0 ]; then
  CHANGE=$(echo "scale=1; ($CURRENT - $PREVIOUS) * 100 / $PREVIOUS" | bc)
  echo "Change: ${CHANGE}%"
  if [ "$(echo "$CHANGE > 5" | bc)" -eq 1 ]; then
    STATUS="up"
  elif [ "$(echo "$CHANGE < -5" | bc)" -eq 1 ]; then
    STATUS="down"
  else
    STATUS="stable"
  fi
  echo "Status: $STATUS"
fi

3. Compare to Baselines

If baselines exist:

BASELINE_FILE="/home/shared/metrics-baseline.json"

if [ -f "$BASELINE_FILE" ]; then
  echo "=== Baseline Comparison ==="
  jq -r 'to_entries[] | "\(.key): \(.value)"' "$BASELINE_FILE"
else
  echo "No baseline found — current values will become the baseline"
fi

4. Present Numbers First, Then Interpretation

Rules for metrics presentation:

• Lead with the number, not the interpretation
• Always include units (%, ms, count, MB)
• Show direction of change with +/- prefix
• Use conditional formatting: mark concerning metrics

5. Tie Recommendations to Metrics

Every recommendation must reference a specific metric:

Pattern	Recommendation Template
Error rate increasing	"Reduce error rate (currently N%) by [specific action]"
Task throughput decreasing	"Increase task completion rate (N/week, down from M) by [action]"
Resource usage high	"Address disk usage (N% full) by [action] before reaching capacity"
Metric missing data	"Instrument [component] to collect [metric] for visibility"

6. Write the Report

REPORT_FILE="/home/shared/metrics-report-$(date +%Y%m%d).md"

cat > "$REPORT_FILE" <<'EOF'
# Metrics Report: [Subject]

**Period:** YYYY-MM-DD to YYYY-MM-DD
**Author:** [agent name]
**Date:** YYYY-MM-DD

## Key Metrics

| Metric | Value | Previous | Change | Status |
|--------|-------|----------|--------|--------|
| Tasks completed | N | N | +N% | up |
| Error rate | N% | N% | -N% | down (good) |
| Avg completion time | Nh | Nh | +Nh | up (bad) |

## Trends
- [Trend 1: what is happening over time and why it matters]
- [Trend 2]

## Detailed Breakdown

### [Metric Category 1]
| Sub-metric | Value | Notes |
|------------|-------|-------|
| ... | ... | ... |

### [Metric Category 2]
...

## Recommendations
1. **[Specific action]** — [metric] is at [value], which indicates [interpretation]. [Action] would improve this to approximately [target].
2. **[Specific action]** — [metric] shows [trend], suggesting [interpretation].

## Data Sources
- [Source 1: path/command used]
- [Source 2: path/command used]
EOF

# Register as artifact
bash /home/shared/scripts/artifact.sh register \
  --name "metrics-report" \
  --type "report" \
  --path "$REPORT_FILE" \
  --description "Metrics report for $(date +%Y-%m-%d)"

Quality Checklist

• All relevant metrics collected from available data sources
• Each metric has current value, previous value, change, and status
• Units are included for every number
• Trends are identified from multi-period data
• Every recommendation references a specific metric and value
• Recommendations include expected outcome if acted upon
• Data sources are documented for reproducibility
• Report is written to shared workspace and registered as artifact