refreshing-metrics

name	refreshing-metrics
description	Auto-updates status metrics across governance documents from MCP issue counts. Use when governance metrics are stale or after significant issue status changes requiring documentation refresh.

Refresh Governance Metrics

Purpose

Governance documents contain metrics that become stale:

• Issue counts by status/priority
• Specification completion percentages
• Feature implementation status (✅ ⚠️ ❌)
• Top projects by issue count
• Phase progress indicators

This skill automatically scans MCP data and updates all metric sections.

Refresh Process

Phase 1: Gather Current Data

1. Get Issue Statistics

Use issues_list to get all issues:

// Get all issues
const allIssues = await issues_list({})

// Get issues by status
const openIssues = await issues_list({ status: "open" })
const inProgressIssues = await issues_list({ status: "in_progress" })
const closedIssues = await issues_list({ status: "closed" })
const cancelledIssues = await issues_list({ status: "cancelled" })

// Get issues by priority
const criticalIssues = await issues_list({ priority: "critical" })
const highIssues = await issues_list({ priority: "high" })
const mediumIssues = await issues_list({ priority: "medium" })
const lowIssues = await issues_list({ priority: "low" })

// Get issues by type
const bugIssues = await issues_list({ labels: ["bug"] })
const featureIssues = await issues_list({ labels: ["feature"] })
const technicalDebtIssues = await issues_list({ labels: ["technical-debt"] })

2. Get Specification Statistics

// Get all specifications
const allSpecs = await issues_list({ type: "specification" })

// Get specs by status
const openSpecs = await issues_list({ type: "specification", status: "open" })
const inProgressSpecs = await issues_list({ type: "specification", status: "in_progress" })
const closedSpecs = await issues_list({ type: "specification", status: "closed" })

// Get specs by roadmap phase (if using phase labels)
const phase1Specs = await issues_list({ type: "specification", labels: ["phase-1"] })
const phase2Specs = await issues_list({ type: "specification", labels: ["phase-2"] })

3. Identify Top Projects

// Get all unique project values
const projectCounts = {}
allIssues.forEach(issue => {
  if (issue.project) {
    projectCounts[issue.project] = (projectCounts[issue.project] || 0) + 1
  }
})

// Sort by count
const topProjects = Object.entries(projectCounts)
  .sort((a, b) => b[1] - a[1])
  .slice(0, 5)

4. Calculate Percentages

const totalIssues = allIssues.length
const openPct = Math.round((openIssues.length / totalIssues) * 100)
const inProgressPct = Math.round((inProgressIssues.length / totalIssues) * 100)
const closedPct = Math.round((closedIssues.length / totalIssues) * 100)

const totalSpecs = allSpecs.length
const completedSpecsPct = Math.round((closedSpecs.length / totalSpecs) * 100)

Phase 2: Update Issues README

File: .wingman/issues/README.md

Find and update Status section:

**Status**: X issues open, Y issues in progress, Z issues closed

Replace with:

**Status**: [openIssues.length] issues open, [inProgressIssues.length] issues in progress, [closedIssues.length] issues closed

Find and update Metrics section:

## Metrics (Auto-Updated)

**Total Issues**: [totalIssues]
**By Status**:
- Open: [openIssues.length] ([openPct]%)
- In Progress: [inProgressIssues.length] ([inProgressPct]%)
- Closed: [closedIssues.length] ([closedPct]%)
- Cancelled: [cancelledIssues.length] ([cancelledPct]%)

**By Priority**:
- Critical: [criticalIssues.length]
- High: [highIssues.length]
- Medium: [mediumIssues.length]
- Low: [lowIssues.length]

**Top Projects**:
1. [topProjects[0][0]]: [topProjects[0][1]] issues
2. [topProjects[1][0]]: [topProjects[1][1]] issues
3. [topProjects[2][0]]: [topProjects[2][1]] issues

Update Last Updated date:

**Last Updated**: [current YYYY-MM-DD]

Phase 3: Update Specifications README

File: .wingman/specifications/README.md

Find and update Status section:

**Status**: X specifications active, Y specifications completed, Z specifications archived

Replace with:

**Status**: [openSpecs.length + inProgressSpecs.length] specifications active, [closedSpecs.length] specifications completed, [cancelledSpecs.length] specifications archived

Find and update Metrics section:

## Metrics (Auto-Updated)

**Total Specifications**: [totalSpecs]

**By Status**:
- Open (Design): [openSpecs.length] ([openSpecsPct]%)
- In Progress: [inProgressSpecs.length] ([inProgressSpecsPct]%)
- Closed (Complete): [closedSpecs.length] ([closedSpecsPct]%)
- Cancelled: [cancelledSpecs.length] ([cancelledSpecsPct]%)

**By Roadmap Phase**:
- Phase 1: [phase1Specs.length] specs
- Phase 2: [phase2Specs.length] specs
- Phase 3: [phase3Specs.length] specs

**Constitutional Compliance**:
- All specifications reviewed: [specsWithConstitutionalAlignment]/[totalSpecs] ([compliancePct]%)
- Principles coverage: [most referenced principles]

Update Last Updated date:

**Last Updated**: [current YYYY-MM-DD]

Phase 4: Update Roadmap Next Steps

File: .wingman/ROADMAP.md

This is the most complex update - requires analyzing feature implementation status

1. Read Current Next Steps File

cat .wingman/ROADMAP.md

2. Scan for Feature Status Sections

Identify features in three categories:

• ✅ Fully Implemented Features
• ⚠️ Partially Implemented Features
• ❌ Not Implemented Features

3. For Each Feature, Determine Current Status

Heuristic for feature status:

function getFeatureStatus(featureName) {
  // Search for related specification
  const spec = await issues_search({ query: featureName, type: "specification" })

  if (spec && spec.status === "closed") {
    return "fully_implemented"
  }

  // Search for related issues
  const issues = await issues_search({ query: featureName })
  const openIssues = issues.filter(i => i.status === "open")
  const completedIssues = issues.filter(i => i.status === "closed")

  if (completedIssues.length > 0 && openIssues.length === 0) {
    return "fully_implemented"
  } else if (completedIssues.length > 0 && openIssues.length > 0) {
    return "partially_implemented"
  } else {
    return "not_implemented"
  }
}

4. Calculate Overall Completion Percentage

// Count features in each category
const fullyImplemented = [count from ✅ section]
const partiallyImplemented = [count from ⚠️ section]
const notImplemented = [count from ❌ section]
const totalFeatures = fullyImplemented + partiallyImplemented + notImplemented

// Calculate weighted percentage
// Fully = 100%, Partially = 50%, Not = 0%
const overallPct = Math.round(
  ((fullyImplemented * 100) + (partiallyImplemented * 50)) / totalFeatures
)

5. Update Executive Summary

### Current State
- ✅ [fullyImplemented]/[totalFeatures] features fully implemented ([fullyPct]%)
- ⚠️ [partiallyImplemented]/[totalFeatures] features partially implemented ([partiallyPct]%)
- ❌ [notImplemented]/[totalFeatures] features not implemented ([notPct]%)
- 📊 Overall: ~[overallPct]% complete

6. Update Last Updated

**Last Updated By**: Claude Code (refreshing-metrics skill)
**Next Review**: [current date + 30 days]

Phase 5: Verify Constitutional Compliance

Scan specifications for constitutional alignment sections:

# Count specs with constitutional alignment
grep -l "Constitutional Alignment" .wingman/specifications/*.md | wc -l

Calculate compliance percentage:

const specsWithAlignment = [count from grep]
const compliancePct = Math.round((specsWithAlignment / totalSpecs) * 100)

Update in Specifications README:

**Constitutional Compliance**:
- All specifications reviewed: [specsWithAlignment]/[totalSpecs] ([compliancePct]%)

If <100%, add note:

⚠️ [totalSpecs - specsWithAlignment] specifications missing Constitutional Alignment section

Phase 6: Extract Principle Coverage

Scan specifications to see which principles are most referenced:

# Count references to each principle
grep -h "Principle 1\|Principle 2\|Principle 3" .wingman/specifications/*.md | sort | uniq -c | sort -rn

Update Specifications README with most referenced principles:

**Principles coverage**: Most referenced: Principle 1 (X specs), Principle 3 (Y specs), Principle 5 (Z specs)

Automated Calculations

Issue Velocity (Optional Advanced Metric)

Calculate weekly close rate:

// Get issues closed in last 7 days
const oneWeekAgo = new Date()
oneWeekAgo.setDate(oneWeekAgo.getDate() - 7)

const recentlyClosedIssues = closedIssues.filter(issue => {
  const closedDate = new Date(issue.updatedAt)
  return closedDate >= oneWeekAgo
})

const weeklyVelocity = recentlyClosedIssues.length

Add to Issues README Metrics section (optional):

**Velocity**:
- Issues closed (last 7 days): [weeklyVelocity]
- Average time to close: [calculate average if possible]

Specification Completion Trend

Calculate trend over time:

// Compare current completion % with last known %
// If increasing: 📈
// If decreasing: 📉
// If stable: ➡️

Add trend indicator to Next Steps:

- 📊 Overall: ~[overallPct]% complete [📈/📉/➡️ vs last month]

Update Report

After completing all updates, generate summary:

# Metrics Refresh Complete

**Date**: [YYYY-MM-DD]
**Files Updated**: 3

---

## Summary of Changes

### Issues README (.wingman/issues/README.md)

**Previous**:
- Total Issues: [old count]
- Open: [old count]
- Closed: [old count]

**Updated to**:
- Total Issues: [new count] ([+/- change])
- Open: [new count] ([+/- change])
- Closed: [new count] ([+/- change])

**Top Projects Updated**: [list]

### Specifications README (.wingman/specifications/README.md)

**Previous**:
- Total Specs: [old count]
- Completed: [old count] ([old %])

**Updated to**:
- Total Specs: [new count] ([+/- change])
- Completed: [new count] ([new %])

**Constitutional Compliance**: [X]% ([+/- change])

### Next Steps (ROADMAP.md)

**Previous Overall Completion**: ~[old %]%

**Updated Overall Completion**: ~[new %]% ([+/- change])

**Features Moved**:
- ❌ → ⚠️: [list features that started implementation]
- ⚠️ → ✅: [list features that completed]

---

## Current Project Health

**Issue Backlog**: [open + in_progress count] active issues
**Specification Pipeline**: [open + in_progress specs count] active specs
**Implementation Progress**: ~[overall %]% complete

**Velocity** (if calculated):
- [weeklyVelocity] issues closed last 7 days

**Constitutional Compliance**: [compliancePct]% of specs have alignment sections

---

## Recommendations

[Based on metrics, provide recommendations:]

**If backlog growing**: Consider reducing scope or increasing velocity
**If completion % declining**: Review roadmap priorities
**If constitutional compliance <100%**: Update missing specs with alignment sections
**If no recent closes**: Check if issues are blocked

---

**Next Metrics Refresh**: [current date + 30 days]

Edge Cases

No Issues Exist Yet

Situation: Fresh project with no MCP issues

Response:

**Status**: No issues tracked yet

**Metrics**: N/A - Use `issues_create` to begin tracking work

Keep README structure, just show zeros/N/A for metrics.

Specifications Without Phase Labels

Situation: Specs don't have phase-1, phase-2 labels

References

For detailed information, see:

• references/detailed-guide.md - Complete workflow details, examples, and troubleshooting