Document Version: 1.1 Last Updated: 2026-04-04 Status: ACTIVE

GitHub Health -- Assessment & Resolution

Decisions: 28 (see .planning/github-health-skill/DECISIONS.md) Research: .research/github-health/RESEARCH_OUTPUT.md

Critical Rules (MUST follow)

1. MUST check gh auth status scopes before running any phase
2. MUST present findings before proposing fixes (assessment first)
3. MUST use per-finding triage — NEVER batch-apply fixes (Guardrail #2)
4. MUST report every API failure — NO SILENT FAILURES (Decision #22)
5. MUST check dedup guard (<30min) before running (Decision #9)
6. MUST check suppressions.json and skip suppressed findings
7. MUST follow CLAUDE.md Section 5 anti-patterns and Section 2 security rules
8. SHOULD read history JSONL for warm-up context (Decision #15)
9. SHOULD check ROADMAP.md before presenting fix options

Routing Guide

When to Use

• User explicitly invokes /github-health
• User asks about GitHub repo health, security alerts, or CI status
• Session-begin surfaces RED/YELLOW github-health quick check

When NOT to Use

• For internal code quality metrics: use /ecosystem-health
• For quick alert triage: use /alerts
• For deep CI failure diagnosis: use /gh-fix-ci
• For SonarCloud issues: use /sonarcloud

Modes

Workflow

Phase 0: Pre-Flight (MUST)

Step 0a: Token Scope Check (Decision #25)

Run gh auth status. Present coverage summary. If repo scope is missing: offer limited assessment (community profile, topics, traffic for public repos still work). Let user choose available phases or abort.

Step 0b: Dedup Guard (Decision #9)

Read last entry from .claude/state/github-health-history.jsonl. If <30min ago: "Last run: [grade], [N]m ago. Re-run? [Y/n]". If declined, show last results.

Step 0c: Warm-Up Context (Decision #15)

GitHub Health Check
Last run: [grade] ([color]), [time ago]
Previous issues: [P0: N, P1: N, P2: N, P3: N]
Full assessment with triage: ~5-10 min. Single phase: ~2-3 min.
Running [mode] now...

Done when: Token scopes verified, dedup checked, warm-up displayed.

Phases 1-7: Assessment

Read REFERENCE.md for full check lists, API endpoints, and fix recipes per phase. Each phase: report ALL API failures (Rule #4). Announce progress: "Phase [name] complete (N of 7)."

Grading (Decision #10): A=0 issues, B=P3 only, C=1-2 P2, D=any P1 or 3+ P2, F=any P0.

License flags (Decision #12): WARNING: copyleft + unknown. INFO: FSL. Ignore: MIT, Apache, BSD, ISC. See REFERENCE.md.

Done when: All phases (or scoped phase) graded, findings collected.

Dashboard Display (MUST)

/github-health assessment -- [repo] -- [date]

SECURITY          [grade]  [N issues]
ACTIONS           [grade]  [N issues]
DEPENDENCIES      [grade]  [N issues]
CONFIG            [grade]  [N issues]
RELEASE           [grade]  [N issues]
INSIGHTS          [grade]  (informational)
PR HEALTH         [grade]  [N issues]

Total: [N] issues | P0: [n] | P1: [n] | P2: [n] | P3: [n]

If --scope was used, note which phases were skipped.

Done when: Dashboard shown, user acknowledges.

Triage Loop (MUST for non-quick modes)

Reminder: per-finding confirmation required (Guardrail #2). NEVER batch.

ROADMAP check (MUST): Before presenting findings, read ROADMAP.md. If a finding is already tracked, note: "Already tracked: [location]."

Triage mode selection: Before entering the loop, ask: "Triage mode: (1) Review each finding [default], (2) Fix all fixable / defer rest, (3) You decide by severity. Choose [1/2/3]:" Mode 2: auto-fix all with available fixes, defer everything else. Mode 3: fix P0/P1, defer P2, skip P3.

Suppression check (Decision #11): Read suppressions.json. Skip suppressed findings (log: "Suppressed: [finding] (reason)").

Per-finding presentation (mode 1):

Finding [N] of [M] | Progress: [X] fixed, [Y] deferred, [Z] skipped

[SEVERITY] [Phase]: [description]
  Evidence: [source]
  Fix: [available fix or "manual steps required"]
  Recommendation: [Fix/Defer/Skip] because [rationale]

  [F]ix  [D]efer  [S]kip  [Su]ppress

P0 suppression warning: If user chooses Suppress on a P0: "Warning: Suppressing a P0 finding is an anti-pattern. Confirm? [Y/n] If yes, expiry date required."

Decision revision: User says "revise N" → re-present finding N for new decision. Update state file.

Fix execution (Decision #24):

1. On first fix, create github-health-fixes branch from current HEAD
2. Each fix: execute + atomic commit. Report all API failures (Rule #4).
3. After all fixes: push branch (with user approval — Guardrail #7), create PR

Defer collection (Decision #17): Batch all deferred items → route to /add-debt once after triage.

Suppress writes (Decision #11): Update suppressions.json with ID, reason, expiry.

UI-only fixes (Decision #23): Step-by-step layman instructions with URLs. See REFERENCE.md Recipe 14.

Done when: All findings triaged, fixes committed, deferred items batched.

Verification (MUST)

Before presenting the summary, verify:

1. Completeness: All phases ran (or were explicitly scoped out). Report any that errored.
2. Fix integrity: Compare triage "Fix" decisions against commits on the fix branch. Flag any fix without a corresponding commit.
3. Orphan check: If fix branch exists but no PR was created, warn: "Branch github-health-fixes has N commits but no PR. Create PR? [Y/n]"
4. Defer routing: Verify deferred item count matches what will be sent to /add-debt.

Done when: All 4 checks pass or issues surfaced to user.

Post-Triage Summary (MUST)

GitHub Health Triage Complete
  Fixed: [N] items ([list])
  Deferred: [N] items (routing to /add-debt)
  Skipped: [N] items
  Suppressed: [N] items
  PR: [URL if fixes were committed]

Update history JSONL with full run results including phases object (per-phase letter grades). Triage state file persists for /session-end to report: "GitHub health: N findings triaged (M fixed, K deferred)."

Retro prompt: "Any observations? (Inaccurate findings, fix recipes that need updating, missing checks.) Enter feedback or 'none'." Save to state file process_feedback field.

Done when: Summary displayed, history updated, feedback captured.

Guard Rails

• API failure: Report which call failed and why. Continue with remaining phases. NEVER abort entire assessment for one phase failure.
• Scope explosion: If a fix requires >1 commit or >10 minutes, defer.
• Duplicate runs: Warn if <30 min since last run. Offer override.
• Batch fixes prohibited: Every fix requires individual user confirmation (Guardrail #2).
• Push protocol: NEVER push to remote without explicit user approval (Guardrail #7).
• Graceful degradation: If token scopes are insufficient, offer limited assessment with available phases rather than aborting entirely.
• Pause/resume: User says "pause" → save all triage decisions to state file, print progress ("N of M findings triaged, K fixes applied"), exit. On next invocation, offer to resume from state file.
• Disengagement: User says "stop" or "cancel" → save state, print summary of what was done, note incomplete status. Next invocation offers resume.

Anti-Patterns

• Batch auto-fixing without per-item confirmation (violates Guardrail #2)
• Running during PR review (health reflects repo state, not PR diff)
• Suppressing P0 findings without resolution
• Re-running repeatedly to pollute trend data

Compaction Resilience

• State file: .claude/state/task-github-health-triage.state.json
• Update frequency: After each finding triage decision
• Recovery: On resume, re-read state, skip triaged findings
• Schema:

  {
    "findings": [{ "id": "str", "severity": "P0-P3", "phase": "str",
                    "action": "fix|defer|skip|suppress", "timestamp": "ISO" }],
    "mode": "full|scope",
    "grades": { "security": "A-F", ... },
    "started": "ISO",
    "process_feedback": "str|null"
  }

Data & Artifact Contracts

Version History