repo-health

What this skill does

# repo-health

The repository-cornerstone skill. Owns the canon for the **community-health files** that bootstrap any code repository:

- `README.md` — the front door (Standard Readme spec).
- `LICENSE` — the legal contract (routed to choosealicense.com; doc-master does not pick).
- `CONTRIBUTING.md` — how external contributors propose changes.
- `CODE_OF_CONDUCT.md` — behavioral norms (Contributor Covenant 3.0 default; 2.1 fallback).
- `SECURITY.md` — vulnerability reporting policy.
- `SUPPORT.md` — where users go for help (often optional for small repos).
- `.github/` templates — issue / PR / CODEOWNERS / FUNDING / CITATION.
- REUSE 3.3 + SPDX — per-file copyright and license metadata.

Each cornerstone has a reference file with the structure, common failure modes, and routing notes. This SKILL.md is the lean entry point — load the references on demand.

## Diagnostic first — do not auto-create

doc-master applies the **four-question diagnostic** to every cornerstone before recommending creation:

1. **Audience** — who reads this, in what situation? (Drive-by contributor? Security researcher? Confused user? Compliance auditor?)
2. **Does it exist already?** — many repos already have an equivalent under a different name or location. Find first, write second.
3. **Where does it go?** — top-level, `.github/`, `docs/`? Each cornerstone has a conventional home.
4. **Who owns it?** — a named human or alias. "The team" is not an owner. CODEOWNERS exists because ownership matters.

If any answer is "no" or "we don't know," **do not create the file yet.** Most small repos do not need `SUPPORT.md`, do not need `FUNDING.yml`, do not need a per-file REUSE header. Cargo-culting cornerstones produces docs nobody reads and nobody updates — the same anti-padding rule that governs ADRs.

## What to recommend by default

For any code repository visible outside the originating team:

| Cornerstone               | Default                                                                                                                       |
|---------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `README.md`               | **Yes** — required. Use the Standard Readme structure. See `references/readme-canon.md`.                                      |
| `LICENSE`                 | **Yes** — required for any code that will be reused. doc-master routes to [choosealicense.com](https://choosealicense.com/); does not pick. See `references/license-routing.md`. |
| `CONTRIBUTING.md`         | **Yes** if external contribution is accepted. Skip if the repo is read-only. See `references/contributing-canon.md`.          |
| `CODE_OF_CONDUCT.md`      | **Yes** if any external participation. Default to **Contributor Covenant 3.0**; 2.1 is the still-valid older fallback. See `references/code-of-conduct-canon.md`. |
| `SECURITY.md`             | **Yes** if the code processes untrusted input, handles secrets, ships to production, or has any user-visible attack surface. See `references/security-canon.md`. |
| `SUPPORT.md`              | **Probably not** for most small repos. Add only when the issue tracker is being misused for support questions. See `references/support-canon.md`. |
| Issue / PR / CODEOWNERS / CITATION / FUNDING | **Case by case.** Each has a real trigger. See `references/templates-canon.md`.                                  |
| REUSE 3.3 / SPDX headers  | **Yes** for any repo that aggregates code under multiple licenses, ships to environments that require SBOM, or wants machine-verifiable license metadata. See `references/reuse-spdx-canon.md`. |

## How to run a bootstrap or audit

When the user asks to **set up** repository docs:

1. Inventory what already exists (`README*`, `LICENSE*`, `CONTRIBUTING*`, `CODE_OF_CONDUCT*`, `SECURITY*`, `SUPPORT*`, `.github/`).
2. For each cornerstone, run the four-question diagnostic.
3. Recommend create / merge / leave-alone, one file at a time. Do not bulk-generate.
4. For files that should be created, load the matching reference; produce a draft with placeholders the user fills in. Never invent maintainer names, contact aliases, license choices, or SLA windows.
5. License selection is **routed**, not made. The skill names common defaults (MIT, Apache-2.0, BSD-3-Clause, GPL-3.0, MPL-2.0) and points to [choosealicense.com](https://choosealicense.com/); the human decides.

When the user asks to **audit** repository docs:

1. Same inventory.
2. For each cornerstone present, compare to the canon and flag drift / missing sections / stale dates / single-maintainer contact lines.
3. For each cornerstone absent, ask whether the four-question diagnostic answers it into existence — most "missing" `SUPPORT.md` and `FUNDING.yml` cases should stay missing.
4. Produce a numbered KEEP / REWRITE / CREATE / DELETE list. Do not bulk-rewrite.

## Hard rules

- **doc-master does not pick a license.** Routing to [choosealicense.com](https://choosealicense.com/) is mandatory. The skill names common defaults; the human chooses.
- **Code of Conduct contact is a shared alias, never a single email.** `[email protected]`, `community@…`, a moderation team — never a personal inbox. Bus factor of one is a refusal condition.
- **SECURITY.md contact is a shared alias or coordinated channel** (GitHub Security Advisories, a named program, `security@…`). Refuse a single-maintainer email.
- **Anti-padding.** Every recommended file passes the four-question diagnostic. If the four questions cannot be answered, the file should not exist.
- **One finding per turn.** When auditing, the skill mirrors `adr-critique` / `markdown-style`: line-referenced, verbatim quote, named rule, proposed rewrite, per-finding approval.

## Routing — what this skill does not own

- **Markdown form** — once a cornerstone exists, lint it via `markdown-style` (`/doc-lint`).
- **ADRs for architectural decisions** — `doc-diagnostic` / `adr-drafting`. "We adopted REUSE" *may* be an ADR; the per-file REUSE headers themselves are not.
- **Changelog** — `../doc-diagnostic/references/changelog-canon.md`.
- **Runbooks / postmortems / open-questions register** — `../doc-diagnostic/references/{runbook,postmortem,open-questions}-canon.md`.
- **AGENTS.md** for AI-agent context — `../doc-diagnostic/references/agentic-docs-canon.md`.

## Examples

<example>
<user_query>I just started a new open-source project. What docs do I need at the repo root?</user_query>
<response>The opensource.guide four-file canon: README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md. Add SECURITY.md if the code processes untrusted input. SUPPORT.md is usually overkill for a new project. Loading `repo-health`; we'll go file by file with the four-question diagnostic. License selection routes to choosealicense.com — I do not pick.</response>
</example>

<example>
<user_query>Should I write an ADR for "we adopted the Contributor Covenant 3.0"?</user_query>
<response>No — that's a CODE_OF_CONDUCT.md adoption, not an ADR. Default to Contributor Covenant 3.0 (four-rung Enforcement Ladder); 2.1 is the older still-valid fallback. Contact line must be a shared alias, not a single maintainer. Loading `repo-health` reference `code-of-conduct-canon.md`.</response>
</example>

<example>
<user_query>Audit our community-health files.</user_query>
<response>Loading `repo-health`. Inventory first, then four-question diagnostic per file, then a numbered KEEP / REWRITE / CREATE / DELETE list. I'll flag single-maintainer contact lines in SECURITY.md / CODE_OF_CONDUCT.md as refusal conditions.</response>
</example>

<example>
<user_query>Do I need a CITATION.cff?</user_query>
<response>If the repo is research software or expects academic citation: yes — CITATION.cff is the converged format. Otherwise no. `references/templates-canon.md` for the schema.</response>
</example>

## References

- `references/readme-canon.md` — Standard Readme spec; nine