[KatalKavya96]

Summary

• Add a first-run welcome guide for the Repository Health family, covering all seven skills and helping newcomers discover CI runner, workflow security, dependency, license compliance, flaky-test, and audit-finding remediation workflows through natural-language requests.
• Document configuration requirements, personal setup versus project adoption, and safety boundaries: six audit skills remain read-only, while audit-finding-fix follows an explicit approval process for changes and draft PR creation.
• Integrate the guide into docs/repo-health/README.md using the standardized family README layout, add regression tests and a new first-run evaluation fixture, regenerate affected welcome reports, and update evaluation counts.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other: Setup-preflight welcome guide, regression tests, and evaluation fixture

Test plan

• prek run --all-files passes
• For Python packages touched: uv run pytest / ruff check / mypy passes
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other:
  • All 61 setup-preflight welcome regression tests passed.
  • render-preflight-fixtures.py --check passed with no fixture drift.
  • Added case-16-repo-health-first-run using the actual ci-runner-audit surface hash.
  • Verified the rendered Repository Health guide is 63 lines, within the 70-line limit.
  • git diff --cached --check passed.
  • Repository-wide pytest, Ruff, mypy, documentation synchronization, skill validation, and other hooks passed through prek.

RFC-AI-0004 compliance

• HITL — the guide distinguishes read-only auditing from remediation and documents explicit user confirmation before draft PR creation.
• Sandbox — no new unrestricted host access, runtime permissions, or network access introduced.
• Vendor neutrality — existing project configuration and placeholder conventions are preserved.
• Conversational + correctable — includes natural-language example requests and guidance for configuring audit policies and customizing workflows.
• Write-access discipline — audit skills remain read-only; remediation follows the existing review and confirmation workflow.
• Privacy LLM — not affected by this change.

Linked issues

Closes #1660

Refs #1654

Notes for reviewers (optional)

• Follows the welcome-guide pattern established in feat(setup): first-run welcome guides, general and for the security skills #1653 and feat(setup): first-run welcome guide for the utilities family (#1663) #1669, including the standardized README introduction used by the recently merged family guides.
• Reuses the existing shared welcome footer and rules without changing production skill behavior.
• Covers all seven Repository Health skills:
  • audit-finding-fix
  • ci-runner-audit
  • dependency-audit
  • dependency-license-audit
  • flaky-test-triage
  • license-compliance-audit
  • workflow-security-audit
• Adds case-16-repo-health-first-run with surface_hash: sha256:c6da72e64ac4808d and updates the setup evaluation count from 135 to 136.
• Updates the existing OTHER_SKILL test helper from ci-runner-audit to rc-cut, since Repository Health now has a welcome guide. This preserves coverage for families without welcome guides. The helper will need another adjustment when the Release Management guide is introduced.
• All local repository-wide checks passed.

AI assistance disclosure: AI assistance was used for repository analysis, implementation drafting, and review. Changes were applied and validated locally by the contributor.

[KatalKavya96]

Hi @potiuk,

I've completed the Repository Health family welcome guide for #1660, following the established pattern from the recently merged welcome-guide PRs.

It covers all seven skills, their configuration requirements, example workflows, and safety boundaries. I've also included the standardized README integration, first-run evaluation fixture, and regression tests.

All repository-wide checks passed locally with prek run --all-files.
Thanks!

[potiuk]

Thanks for the repo-health guide. It fits the existing family-guide pattern, its config claims match the skills' requires_config frontmatter, and the new test covers all seven skills' family membership and the general → family → general sequencing.

#1673 merged after this was opened and edits the same eval counts and the case-9 report, so rather than send it back I rebased the branch onto main and pushed two commits:

• your commit, rebased, with the counts taken from main (139 cases total, 19 for preflight-floor, and your repo-health description appended to main's row) and case-9 re-rendered with tools/dev/render-preflight-fixtures.py;
• a fixup (9fbe65bd):
  • the eval case is renumbered to case-19-repo-health-first-run, after main's case-16–case-18;
  • guides/repo-health.md now says audit-finding-fix asks before every write and commit, not only before the draft PR;
  • the license audit gets its own prompt in the flow, and the sentence that repeated it is gone;
  • "make it yours" now names what a request becomes, as the other family guides do.

One note for later: once the setup and release-management guides land, every family will have a guide, and the "family without a guide" tests in test_welcome.py will need a synthetic guide-less family instead of rc-cut.

Thanks!

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.