Auto-update status metrics across governance documents - scans MCP issues/specs to calculate current counts and percentages, updates README files and NEXT_STEPS with accurate data
Automatically updates governance metrics by scanning MCP issues and specs, then refreshes README files and NEXT_STEPS with current counts, percentages, and implementation status. Triggered when metrics are stale (>30 days), after major milestones, or when explicitly requested to maintain accurate project health visibility.
/plugin marketplace add samjhecht/wrangler/plugin install wrangler@samjhecht-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
MANDATORY: When using this skill, announce it at the start with:
š§ Using Skill: refresh-metrics | [brief purpose based on context]
Example:
š§ Using Skill: refresh-metrics | [Provide context-specific example of what you're doing]
This creates an audit trail showing which skills were applied during the session.
You are updating status metrics across all governance documents to reflect the current state of issues, specifications, and implementation progress.
Governance documents contain metrics that become stale:
This skill automatically scans MCP data and updates all metric sections.
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)
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]
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]
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:
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 (refresh-metrics skill)
**Next Review**: [current date + 30 days]
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
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)
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]
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]
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]
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.
Situation: Specs don't have phase-1, phase-2 labels
Response:
Situation: User modified Next Steps structure significantly
Response:
Situation: Spec says "closed" but has open issues
Response:
Metrics refresh is complete when:
Recommended schedule:
Can be triggered by:
Read-only scanning: This skill uses MCP issues_list and issues_search (read operations only) - never modifies issue data, only updates metric sections in markdown files.
Preserve user content: When updating README files, only replace metric sections - never delete user-added content.
Percentage rounding: Always round to nearest integer for readability.
Trend indicators: Only show trends if you have historical data to compare.
Accurate metrics are essential for governance effectiveness. Stale data leads to poor decisions. Make refresh easy and automatic so it becomes routine maintenance, not a burden.
Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing APIs, or debugging security issues.