Project Health Diagnostics

🩺 Skill: Project Health Diagnostics

Purpose

After months of AI-assisted development, codebases silently drift. Components bypass design tokens. Accessibility gaps accumulate. Error states get skipped. This skill gives agents the ability to run a structured diagnostic and prescribe exactly what's missing — turning "something feels off" into an actionable, scored health report.

Trigger Phrases

Protocol: 5-Step Diagnostic Engine

STEP 1 — Scan (2–3 turns)

Detect the project's current state across 5 signal categories:

SIGNAL A: Token Architecture
  - Are CSS custom properties used? (var(--color-*), var(--space-*))
  - Is there a token file? (tokens.css, design-tokens.json, theme.ts)
  - Token coverage estimate: % of color/spacing/type using tokens vs hardcoded

SIGNAL B: WCAG Compliance
  - Presence of aria-*, role=*, alt="", tabindex
  - Color contrast annotations in component comments
  - Focus state styles (:focus-visible)
  - Skip navigation links

SIGNAL C: Resilience Coverage
  - Are empty/loading/error/offline/partial states handled in components?
  - Is there an Error Boundary component?
  - Are network failure states covered (offline queue, timeout fallback)?

SIGNAL D: Responsive Architecture
  - Breakpoint system defined? (@media, container queries)
  - Mobile-first CSS cascade?
  - Touch target minimum sizes (44×44px)?
  - Adaptive component transformations (sidebar → bottom-nav)?

SIGNAL E: AI Drift Indicators
  - Frequency of hardcoded hex colors, px values, magic numbers
  - Ratio of var(--token) vs literal values in stylesheets
  - Presence of z-index: 9999 or !important flags

STEP 2 — Score: Token Adherence Index (TAI)

Compute the TAI score using the weighted formula:

TAI = (token_coverage   × 0.40) +
      (wcag_score        × 0.25) +
      (resilience_cover  × 0.20) +
      (responsive_score  × 0.15)

Each sub-score: 0–100 based on signal presence and coverage

Grade Thresholds:
  90–100 → 🟢 Excellent  (production-ready, autonomous AI-safe)
  70–89  → 🟡 Good       (minor gaps, advisory remediation)
  50–69  → 🟠 Needs Work (significant gaps, blocking issues)
  0–49   → 🔴 Critical   (design system not enforced, high drift risk)

STEP 3 — Identify: Gap Mapping

For each sub-score below threshold, map to the responsible Agentway skill:

STEP 4 — Prescribe: Skill Activation Queue

Output a prioritized prescription using this priority model:

P0 — CRITICAL: Run immediately. Blocks production quality.
P1 — HIGH:     Run in current sprint. Significant UX impact.
P2 — MEDIUM:   Run in next sprint. Polish and consistency.
P3 — LOW:      Run when capacity allows. Nice-to-have improvement.

STEP 5 — Report: Generate Health Report Card

Produce two artifacts:

health-report.md — Human-readable with:

• TAI Score badge (0–100 with grade emoji)
• Radar breakdown (token / WCAG / resilience / responsive)
• Top 3 critical gaps with 1-line explanations
• Prioritized prescription table

health-report.json — Machine-readable for CI integration:

{
  "version": "1.6.0",
  "scannedAt": "ISO8601",
  "tai": { "score": 74, "grade": "Good",
    "breakdown": { "tokenCoverage": 82, "wcagScore": 78,
                   "resilienceCoverage": 65, "responsiveScore": 71 }},
  "drift": { "critical": 3, "high": 7, "medium": 12, "low": 4 },
  "prescription": [
    { "skill": "design-tokens", "priority": "P0",
      "reason": "Token coverage 63% — below 80% threshold" }
  ]
}

Diagnostic Reference Thresholds

CI Integration Pattern

# .github/workflows/quality-gate.yml
- name: Run Agentway Health Check
  run: agentway doctor ./ --json > health-report.json
  continue-on-error: true  # Advisory in v1.6.0

- name: Check TAI Threshold
  run: |
    TAI=$(node -e "console.log(require('./health-report.json').tai.score)")
    echo "TAI Score: $TAI"
    if [ "$TAI" -lt 60 ]; then
      echo "⚠️ TAI score below 60 — review health-report.json"
    fi

Companion Skills