vunvulear/peek.it-008-demo/docguard-score

DocGuard Score Skill

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Run DocGuard's CDD maturity scoring engine, analyze the category breakdown, identify highest-ROI improvements, and produce an actionable improvement roadmap showing projected score gains per fix.

Execution Flow

Step 1: Run Scoring Engine

Execute both tools for comprehensive data:

npx docguard-cli score 2>&1
npx docguard-cli guard 2>&1

If in DocGuard dev environment:

node cli/docguard.mjs score 2>&1
node cli/docguard.mjs guard 2>&1

Step 2: Parse Score Breakdown

Extract the category-level scores:

Calculate Potential Gain for each category = (weight - current points).

Step 3: Grade Classification

Step 4: ROI-Based Improvement Roadmap

Sort categories by Potential Gain / Effort ratio:

For each category below 100%, calculate:

• Gap: What checks are failing?
• Effort: How hard is it to fix? (LOW = update metadata, MEDIUM = add content, HIGH = research + write)
• Impact: Points gained if fixed to 100%
• ROI: Impact / Effort ranking

Generate an improvement plan ordered by ROI:

### Improvement Roadmap
 
| Priority | Category | Current | Target | Points Gain | Effort | Action |
|:--------:|----------|:-------:|:------:|:-----------:|--------|--------|
| 1 | Structure | 80% | 100% | +5 | LOW | Create REQUIREMENTS.md |
| 2 | Changelog | 60% | 100% | +2 | LOW | Add missing entry for v0.9.5 |
| 3 | Doc Quality | 85% | 100% | +3 | MEDIUM | Fix negation language in SECURITY.md |
| 4 | Testing | 70% | 100% | +4.5 | HIGH | Add E2E test documentation |

Step 5: Guard Check Correlation

Cross-reference the score with guard results:

• For each failing guard check, show which score category it impacts
• Calculate: "If you fix these N guard warnings, score will increase from X to Y"
• Show the minimum set of fixes needed to reach the next grade level

### Path to Next Grade
 
**Current**: B (78/100)
**Next Grade**: A (85/100) — need +7 points
 
**Minimum fixes for grade A**:
1.Fix Structure (3 checks failing) → +5 points
2.Fix Changelog (1 check failing) → +2 points
Total effort: ~30 minutes

Step 6: ALCOA+ Compliance Summary

If the score engine reports ALCOA+ attributes, include:

Step 7: Historical Comparison

If user has run score before (check git log for score badge changes):

### Score History
| Date | Score | Grade | Change |
|------|:-----:|:-----:|:------:|
| 2026-03-14 | 100 | A+ | +22 |
| 2026-03-13 | 78 | B | baseline |

Step 8: Completion Report

## CDD Maturity Assessment
 
**Project**: [name]
**Score**: [X]/100 ([grade])
**Guard**: [N]/[M] checks passed
**ALCOA+**: [N]/9 attributes met
 
### Category Health
[Table from Step 2]
 
### Improvement Roadmap
[Plan from Step 4]
 
### Path to Next Grade
[Analysis from Step 5]
 
### Suggested Next Steps
-`/docguard.fix` — Fix the top [N] issues automatically
-`/docguard.review` — Deep semantic analysis for accuracy verification
-`/docguard.guard` — Verify fixes pass all validators

Behavior Rules

• ALWAYS run real CLI — never simulate scores
• Show math — explain how score is calculated (category × weight)
• Be actionable — every recommendation must have a specific action
• Compare before/after — if user has previously run score in this session, show improvement
• Focus on ROI — surface the cheapest fixes with the biggest score impact first

Context

$ARGUMENTS