repo-health

Files (62)

• SKILL.md
• audit-dependency-usage.sh · scripts/
• check-doc-links.sh · scripts/
• classify-finding.sh · scripts/
• compare-specs.sh · scripts/
• compute-grade.sh · scripts/
• detect-dead-code.sh · scripts/
• find-duplicates.sh · scripts/
• find-uncovered.sh · scripts/
• fix-doc-links.sh · scripts/
• fix-env-example.sh · scripts/
• fix-lint.sh · scripts/
• fix-rollback.sh · scripts/
• install-missing-tools.sh · scripts/
• common.sh · scripts/lib/
• fix-common.sh · scripts/lib/
• installers.sh · scripts/lib/
• parse-test-results.sh · scripts/
• run-scan-suite.sh · scripts/
• scan-12factor-factor-1.sh · scripts/
• scan-12factor-factor-10.sh · scripts/
• scan-12factor-factor-11.sh · scripts/
• scan-12factor-factor-12.sh · scripts/
• scan-12factor-factor-2.sh · scripts/
• scan-12factor-factor-3.sh · scripts/
• scan-12factor-factor-4.sh · scripts/
• scan-12factor-factor-5.sh · scripts/
• scan-12factor-factor-6.sh · scripts/
• scan-12factor-factor-7.sh · scripts/
• scan-12factor-factor-8.sh · scripts/
• scan-12factor-factor-9.sh · scripts/
• scan-12factor-report.sh · scripts/
• scan-12factor.sh · scripts/
• scan-cognitive-complexity.sh · scripts/
• scan-complexity.sh · scripts/
• scan-docs.sh · scripts/
• scan-environment-tools.sh · scripts/
• scan-environment-transient.sh · scripts/
• scan-environment.sh · scripts/
• scan-licenses.sh · scripts/
• scan-linters-detect.sh · scripts/
• scan-linters-run.sh · scripts/
• scan-linters.sh · scripts/
• scan-sbom.sh · scripts/
• scan-secrets.sh · scripts/
• scan-security.sh · scripts/
• scan-setup.sh · scripts/
• scan-tech-debt-step-1.sh · scripts/
• scan-tech-debt-step-2.sh · scripts/
• scan-tech-debt-step-3.sh · scripts/
• scan-tech-debt-step-4.sh · scripts/
• scan-tech-debt-step-5.sh · scripts/
• scan-tech-debt-step-6.sh · scripts/
• scan-tech-debt-step-7.sh · scripts/
• scan-tech-debt.sh · scripts/
• scan-tests-coverage.sh · scripts/
• scan-tests-parse.sh · scripts/
• scan-tests-presence.sh · scripts/
• scan-tests-report.sh · scripts/
• scan-tests-slow.sh · scripts/
• …and 2 more

SKILL.md (first lines)

# Repository Health Audit

A rigorous, deterministic repository audit covering nine dimensions. The audit detects
issues, classifies them, and computes a grade. Behavior then depends on the **mode**:

- **mode=report (default)** — present the graded findings report and stop. No files are modified.
- **mode=fix (opt-in)** — additionally run the Phase 10 remediation loop: fix, re-audit,
  and iterate until only trivial nitpicks remain.

> **Prerequisite:** None. Phase 0 gates the audit on required tools.

---

## Mode Selection — Resolve BEFORE Phase 10

The skill takes one parameter, `mode`. Resolve it from the user's request before running
the audit, and state the resolved mode in one line at the start of the run.

| mode | Behavior | Triggered when the user says |
| -------- | ----------- | ------------------------------ |
| `report` **(DEFAULT)** | Audit + graded findings report. Stop. No code changes. | "review this repo", "audit this project", "health check", "quality gate", "analyze this codebase", or any audit request without remediation intent |
| `fix` | Audit + report + Phase 10 remediation loop (fix → re-audit → iterate until only NITPICKs remain). No confirmation gates. | "fix findings", "remediate issues", "auto-fix everything", "fix everything you find", or an explicit `mode=fix` |

Rules:

- **Default to `report` when the request is ambiguous.** Never silently escalate to `fix`.
- **Never downgrade to `report` when the user clearly asked for fixes.**
- After a `report`-mode run, the user can trigger remediation in a follow-up ("now fix
  these findings") — reuse the synthesized findings file instead of re-running the audit.

```
AUDIT (Phases 0-9) ──► SYNTHESIZE ──► CLASSIFY ──► GRADE ──► REPORT ──► done (mode=report)
                                                                │
                                                mode=fix only   ▼
                                                10.3 FIX ──► 10.4 RE-AUDIT ──► LOOP UNTIL NITPICK ──► 10.5 REPORT
```

---

## Critical Constraints

### MUST DO (both modes)

- **Run PHASE 0 before all other phases** — abort if any required tool is missing
- **Resolve `mode` before Phase 10** and state it in one line at the start of the run
- Run actual scanners/tool commands — do not speculate about outcomes
- Operate on committed HEAD (preserve original commit, never mixed working tree + staging)
- **Outdated libraries, packages with known CVEs, and insecure code patterns are CRITICAL severity** — never downgrade them to MEDIUM or HIGH; in mode=fix they MUST be addressed in the remediation loop

### MUST DO (mode=fix only)

- **Phase 10 is the remediation pipeline (classify → fix → re-audit → loop)** — do NOT stop after synthesis. Classification, fix execution, re-audit, and loop are all mandatory parts of Phase 10.
- **Re-audit after each remediation round** within Phase 10 — loop until exit condition met (CRITICAL=0 AND HIGH=0 AND MEDIUM=0 AND FAILED_TESTS=0 AND LINT_ERRORS=0 AND LSP_ERRORS=0 AND ACTIONABLE(LOW)=0)
- If a fix introduces a regression (new CRITICAL/HIGH finding), **revert via fix-rollback.sh** and skip that fix

### MUST NOT DO (both modes)

- Never suppress type errors with `as any`, `@ts-ignore`, or `@ts-expect-error`
- Never delete failing tests to make a build pass
- Never treat an N/A dimension as a failure — document rationale

### MUST NOT DO (mode=report)

- Never modify, create, or delete any file — the audit is read-only
- Never run fix scripts with write access (no `fix-*.sh` outside `--dry-run` / `--check`)

### MUST NOT DO (mode=fix)

- Never present an advisory action plan without executing the remediation steps in Phase 10.3-10.4
- Never stop after Phase 10.1 (Synthesize) — that is only the first of five sub-steps
- Never ask "do you want me to fix these?" — the user already opted in via mode=fix
- Never commit changes (leave uncommitted for user review)
- Never edit any symbol without understanding its callers first

---

## Phase Reference

| # | Dimension | Subskill |
| --- | ----------- | ---------- |
| 0 | Environment Readiness (Gate) | `repo-health--phase-0-environment` |
| 1 | Project Discovery | `repo-health--phase-1-discovery` |
| 2 | Code Quality | `repo-health--phase-2-code-quality` |
| 3 | Technical Debt | `repo-health--phase-3-tech-debt` |
| 4 | Documentation | `repo-health--phase-4-docs` |
| 5 | OpenSpec Specifications | `repo-health--phase-5-specs` |
| 6 | Test Suite Health | `repo-health--phase-6-tests` |
| 7 | Security Review | `repo-health--phase-7-security` |
| 8 | SBOM & License Audit | `repo-health--phase-8-sbom` |
| 9 | 12-Factor App Compliance | `repo-health--phase-9-12factor` |
| 10 | Remediation Loop (**mode=fix only** — delegated to subagent; fixes, re-audits, loops) | `repo-health--phase-10-remediate` |

---

## Fix Scripts Reference

Fix scripts run only in mode=fix (or manually by the user after a report-mode run). Six
fix scripts live under `skills/repo-health/scripts/`:

| Script | Purpose | Finding Types |
| -------- | --------- | --------------- |
| `fix-doc-links.sh` | Check + report broken external/internal links in docs | Broken links |
| `fix-env-example.sh` | Generate/update .env.example from code-scanned env vars | Missing .env.example |
| `fix-lint.sh` | Run linters with --fix (ESLint, Ruff, gofmt, etc.) | Lint violations |
| `fix-rollback.sh` | Snapshot rollback + regression detection | Safety net |
| `lib/fix-common.sh` | Shared library (sourced by all fix scripts) | — |

---

## Phase A — Audit: Phases 0-10

### Step A1 — Prerequisite & Helpers

1. Load the helpers subskill: `skill(name="repo-health--helpers")`
3. Load PHASE 1 subskill: `skill(name="repo-health--phase-1-discovery")`
   (Do NOT load all phase subskills — only Phase 1 runs first. The composite
   subagent loads the phase subskills it needs internally.)

### Step A2 — Phase 0 (Gate + Auto-Install)

From handbrianc/skill-library, MIT.

More from handbrianc/skill-library