metrics

name	metrics
description	Compute and display pipeline timing metrics for a project by reading YAML frontmatter from all project documents.
argument-hint	<callsign>
allowed-tools	["Read","Glob","Grep","Bash","mcp__wcp__wcp_get_artifact","mcp__wcp__wcp_attach","mcp__wcp__wcp_comment"]

Metrics

You compute pipeline timing metrics for a project by reading the YAML frontmatter from all project artifacts on a WCP work item, enriching with git/PR data, and producing a metrics report.

Inputs

• All artifacts on WCP work item $ARGUMENTS
• The current repository — for git and PR data

Before You Start

1. Locate the conventions file in the current repo root — look for CLAUDE.md, AGENTS.md, or CONVENTIONS.md (use the first one found). Read it in full. From the ## Pipeline Configuration section, extract Repository Details (default branch, branch prefix, etc.).
2. Verify the work item exists: wcp_get($ARGUMENTS) or attempt to read any artifact.

Step-by-Step Procedure

1. Read All Frontmatter

Read each of these artifacts via wcp_get_artifact($ARGUMENTS, filename):

• prd.md
• discovery-report.md
• architecture-proposal.md
• gameplan.md
• test-coverage-matrix.md
• progress.md
• review-report.md
• qa-plan.md

For each that returns content, extract the YAML frontmatter (lines between the opening and closing --- markers). Skip any that don't exist.

Parse these fields from each document:

• pipeline_stage
• pipeline_stage_name
• pipeline_started_at
• pipeline_completed_at
• pipeline_approved_at (architecture-proposal.md, gameplan.md)
• pipeline_backfilled (boolean)
• pipeline_m*_started_at / pipeline_m*_completed_at (progress.md)
• pipeline_pr_created_at / pipeline_pr_url (progress.md)

2. Enrich with Git/PR Data

Check for PR merge data:

gh pr list --head '<branch-prefix>$ARGUMENTS' --state merged --json mergedAt,createdAt,url --limit 1

If a merged PR is found, extract mergedAt and createdAt. If no merged PR, try open PRs:

gh pr list --head '<branch-prefix>$ARGUMENTS' --state open --json createdAt,url --limit 1

3. Compute Metrics

For each stage, compute:

• Duration: completed_at - started_at (if both exist)
• Wait → Next: time between this stage's completed_at and the next stage's started_at

For stages with approval checkpoints:

• Stage Duration: completed_at - started_at (agent work time)
• Human Review Time: approved_at - completed_at (time waiting for human approval)

For implementation milestones:

• Per-milestone duration: mN_completed_at - mN_started_at
• Total implementation time: sum of all milestone durations

Compute summary metrics:

• Total Lead Time: First stage started_at (or completed_at if backfilled) → PR merge time (or latest completed_at)
• Active Agent Time: Sum of all stage durations (where both started_at and completed_at exist)
• Human Review Time: Sum of approval wait times (architecture + gameplan)
• Idle/Queue Time: Total Lead Time - Active Agent Time - Human Review Time
• Agent Efficiency: Active Agent Time / (Active Agent Time + Idle/Queue Time)

4. Format Durations

Format all durations in human-readable form:

• Under 1 hour: Xm (e.g., 25m)
• 1-24 hours: Xh Ym (e.g., 2h 15m)
• Over 24 hours: Xd Yh (e.g., 3d 2h)

5. Write Metrics Report

Attach the metrics report to the work item:

wcp_attach(
  id=$ARGUMENTS,
  type="metrics",
  title="Pipeline Metrics",
  filename="metrics.md",
  content="[metrics report]"
)

Use this template for the report content:

# Pipeline Metrics — $ARGUMENTS

> Generated: <current date/time>
> Data quality: [live / partially backfilled / fully backfilled]

## Stage Timeline

| Stage | Document | Started | Completed | Duration | Wait → Next |
|-------|----------|---------|-----------|----------|-------------|
| 0: PRD | prd.md | ... | ... | ... | ... |
| 1: Discovery | discovery-report.md | ... | ... | ... | ... |
| 2: Architecture | architecture-proposal.md | ... | ... | ... | — |
| 2→3: Human Review | — | ... | approved ... | ... | — |
| 3: Gameplan | gameplan.md | ... | ... | ... | — |
| 3→4: Human Review | — | ... | approved ... | ... | — |
| 4: Test Generation | test-coverage-matrix.md | ... | ... | ... | ... |
| 5: Implementation | progress.md | — | — | — | — |
| 5/M1 | — | ... | ... | ... | ... |
| 5/M2 | — | ... | ... | ... | ... |
| [continue for each milestone] | | | | | |
| 7: QA Plan | qa-plan.md | ... | ... | ... | ... |
| PR Created | — | — | ... | — | ... |
| PR Merged | — | — | ... | — | — |

Use `—` for fields where data is unavailable.

## Summary

| Metric | Value |
|--------|-------|
| **Total Lead Time** (PRD start → PR merge) | ... |
| **Active Agent Time** | ... |
| **Human Review Time** | ... |
| **Idle/Queue Time** | ... |
| **Agent Efficiency** | ...% |

## Implementation Breakdown

| Milestone | Duration | Files | Tests |
|-----------|----------|-------|-------|
| M1 | ... | ... | ... |
| M2 | ... | ... | ... |
| **Total** | ... | ... | ... |

[If milestone-level data is available from progress.md]

## Data Quality Notes

- [Note which stages have live vs backfilled timestamps]
- [Note any stages with missing data]
- [Note if started_at is missing (backfilled documents)]

6. Handle Missing Data

• If a field is missing, display — in the table
• If started_at is missing (backfilled), duration cannot be computed — show — for duration
• If only completed_at exists, still show it in the timeline for ordering
• Note data quality issues in the "Data Quality Notes" section

7. Post Summary Comment

Add a comment to the work item summarizing the metrics:

wcp_comment(
  id=$ARGUMENTS,
  author="pipeline/metrics",
  body="Metrics report attached as metrics.md — [brief summary of key metrics]"
)

What NOT To Do

• Do not modify any project artifacts. Only produce metrics.md.
• Do not fabricate timestamps. Use — for missing data.
• Do not run pipeline stages. This is a read-only analysis tool.

When You're Done

Tell the user:

1. The metrics report has been attached to $ARGUMENTS as metrics.md
2. Summarize key metrics: total lead time, active agent time, agent efficiency
3. Note any data quality limitations (backfilled vs live data)