tomevault-io 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 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.