nezam-health-score

skill_id	nezam-health-score
name	nezam-Health Score
tier	3
description	Generate and refresh root HEALTH.md with a plain-language 0-100 project health score across six dimensions.
version	1.0.0
updated	"2026-05-08T00:00:00.000Z"
changelog	[]

Purpose

Produce and maintain a living HEALTH.md at the repository root that summarizes overall project readiness as a plain-language 0–100 scorecard for technical and non-technical stakeholders.

Inputs

• .cursor/state/onboarding.yaml — prd_locked, design_locked, planning_complete, current_phase, build_mode
• .cursor/state/plan_progress.yaml — seo, ia, content, arch, design_wireframes, scaffold flags
• .cursor/state/develop_phases.yaml — phase status, testing_passed per phase
• .nezam/core/prd/PRD.md — presence and line count (>10 non-comment lines = filled)
• DESIGN.md at repo root — presence and non-blank check
• .nezam/core/plans/** — artifact presence per planning phase
• docs/reports/security/SECURITY_AUDIT.md — pass/fail status
• docs/reports/perf/LIGHTHOUSE_REPORT.md — LCP, CLS, INP values
• docs/reports/tests/COVERAGE_REPORT.md — coverage percentage
• docs/reports/a11y/A11Y_AUDIT.md — WCAG 2.2 AA pass/fail
• Optional scan findings for unresolved high/critical issues

Step-by-Step Workflow

Dimension Scoring (0–100 each)

1. Spec Completeness (max 100 pts)

• .nezam/core/prd/PRD.md exists and has >10 non-comment lines: +40 pts
• onboarding.yaml → prd_locked: true: +20 pts
• All 6 plan_progress flags true: +30 pts (5 pts each)
• build_mode is set (not empty): +10 pts

2. Design Contract (max 100 pts)

• DESIGN.md exists at repo root: +30 pts
• design_locked: true in onboarding.yaml: +30 pts
• .nezam/core/plans/04-design/DESIGN_CHOICES.yaml or .md exists: +20 pts
• .nezam/core/plans/design/WIREFRAMES.md exists: +20 pts

3. Security Posture (max 100 pts)

• docs/reports/security/SECURITY_AUDIT.md exists: +40 pts
• Audit file contains "PASS" or "pass": +40 pts
• No unresolved CRITICAL or HIGH findings in scan output: +20 pts

4. Performance Budget (max 100 pts)

• docs/reports/perf/LIGHTHOUSE_REPORT.md exists: +20 pts
• LCP < 2.5s present in report: +30 pts
• CLS < 0.1 present in report: +25 pts
• INP < 200ms present in report: +25 pts

5. Test Coverage (max 100 pts)

• docs/reports/tests/ directory has at least one file: +20 pts
• COVERAGE_REPORT.md exists: +30 pts
• Coverage ≥ 60%: +20 pts; ≥ 80%: +30 pts total
• All develop phases with testing_passed: true: +20 pts (proportional)

6. Content Quality (max 100 pts)

• .nezam/core/plans/01-research/SEO_RESEARCH.md exists: +20 pts
• .nezam/core/plans/02-ia/IA_CONTENT.md exists: +20 pts
• .nezam/core/plans/03-content/CONTENT_MAP.md exists: +20 pts
• docs/reports/a11y/A11Y_AUDIT.md exists: +20 pts
• A11Y audit passes WCAG 2.2 AA: +20 pts

Scoring Procedure

1. Compute six dimension scores using point breakdowns above.
2. For each dimension, derive:
   • score (0–100)
   • status label: Good (≥80), Warning (50–79), Missing/Partial (<50)
   • one plain-language action needed (most impactful missing item)
3. Average the six dimension scores for an overall score.
4. Apply overall status icon:
   • >=80 → ✅
   • 60-79 → ⚠️
   • <60 → ❌
5. Write/update root HEALTH.md using the standardized table contract.
6. Add one final line: the single most impactful next action in plain language.
7. Keep output plain-language and non-jargony.

Validation & Metrics

• HEALTH.md exists at repository root after each run.
• All six dimensions are present with numeric scores.
• Overall score equals the arithmetic average of dimension scores.
• Timestamp updates each regeneration.
• Action-needed cells are always actionable one-liners.

Output Format

Use this exact section structure in HEALTH.md:

• # Project Health
• Last updated: <timestamp>
• Overall: <score>/100 <icon>
• six-row markdown table with:
  • Dimension
  • Score
  • Status
  • Action needed
• To improve: <single best next action>

Integration Hooks

• /SCAN all must regenerate HEALTH.md after scan completion.
• /GUIDE status must surface a concise HEALTH.md summary first.
• /start gates and /guide status should use the same health summary layer.

Anti-Patterns

• Do not use internal engineering jargon in status/action text.
• Do not omit any of the six dimensions.
• Do not leave stale timestamps.
• Do not overwrite with empty/default values if evidence is unavailable; degrade gracefully with explicit missing-data actions.

External Reference

• Scan command contract: .cursor/commands/scan.md.
• Status command contract: .cursor/commands/guide.md and .cursor/commands/start.md.
• Reports policy: .cursor/rules/docs-reports-policy.mdc.