Agent Skills: Refresh Governance Metrics

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: .wrangler/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: .wrangler/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: .wrangler/ROADMAP_NEXT_STEPS.md

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

1. Read Current Next Steps File

cat .wrangler/ROADMAP_NEXT_STEPS.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" .wrangler/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" .wrangler/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 (.wrangler/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 (.wrangler/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_NEXT_STEPS.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