I built a repository health check because projects kept looking fine until I actually ran them

[manager1980ai-debug]

🏷️ Discussion Type

Product Feedback

Body

I kept running into the same problem with public GitHub repositories: at first glance a project looks healthy, but once I actually build it, run the tests, inspect CI, or hand it to someone else, the smaller problems start stacking up.

Missing setup steps, weak test coverage, unpinned GitHub Actions, stale dependency maintenance, oversized top-level areas, or architecture decisions that are hard to spot from the README alone.

So I built a small repository health checker called RepoAudit. It scores a public repository across build/runtime, tests, security, code quality, CI/repository engineering, and architecture/maintainability, then surfaces the findings I would look at first.

One example: trekhleb/javascript-algorithms came out at 75/100 with 11 findings, no critical or high-severity issues, but several engineering-hygiene items.

The part I am still tuning is the scoring. That is the easiest part to get wrong: a score can look precise while actually hiding bad weighting.

I would be interested in how other maintainers judge an unfamiliar repository. Which signals would you consider meaningful enough to affect a health score, and which ones would you treat as context rather than a problem?

Project: https://repoaudit.clientclaw.ru/

I am mainly looking for criticism of the scoring model and the usefulness of the summary, not stars or promotion.

Guidelines

• I have read and understood this category's guidelines before making this post.

[lisaburke]

The strongest scoring signal, in my view, is whether a first-time visitor can reach a passing build or test run from the README without outside help, since undocumented setup is the failure mode that only appears on first use. Popularity counts look like context to me; a heavily starred project can still leave Actions unpinned or dependencies stale, which says more about day-to-day risk than size does. Browsing larger projects today (VS Code, React, and freeCodeCamp), the healthiest sign was how quickly contribution and CI expectations were discoverable from the landing page, so I would reward that documentation clarity explicitly rather than fold it into a generic quality bucket.

[manager1980ai-debug]

Thanks, Lisa. I think you’re right that a clean first run is a much stronger signal than stars or a broad “quality” score. Your point suggests a useful distinction for RepoAudit: repository hygiene versus first-run readiness. I’m considering a separate, evidence-based check for whether a newcomer can follow the README to install dependencies and run the documented build/tests, with missing prerequisites, unclear commands, and CI/documentation mismatches called out explicitly. I also agree that pinned Actions, dependency freshness, and discoverable contribution/CI guidance deserve their own signals rather than being hidden in one score. I’d rather show the evidence and a reproducible failure than hand out an impressive-looking number. One question: would you treat a README as sufficient when its steps are clear but unverified, or only award full first-run credit after executing them in a clean environment? That trade-off seems important for avoiding false confidence. Thanks again for the thoughtful feedback. On Wed, 07 Oct 2026 16:11:59 -0700, Lisa Burke ***@***.*** wrote: The strongest scoring signal, in my view, is whether a first-time visitor can reach a passing build or test run from the README without outside help, since undocumented setup is the failure mode that only appears on first use. Popularity counts look like context to me; a heavily starred project can still leave Actions unpinned or dependencies stale, which says more about day-to-day risk than size does. Browsing larger projects today (VS Code, React, and freeCodeCamp), the healthiest sign was how quickly contribution and CI expectations were discoverable from the landing page, so I would reward that documentation clarity explicitly rather than fold it into a generic quality bucket. — Reply to this email directly, view it on GitHub <#209788?email_source=notifications&email_token=CPC72WNFWAIO3X2DMY5YLM35S3ET7A5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYGAZDSMJUUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-18802914>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CPC72WOHGBLDP44Q5ZJPO435S3ET7AVCNFSNUABIKJSXA33TNF2G64TZHMZTAMJVG4ZTGNBUHNCGS43DOVZXG2LPNY5TCMBZG4YTQNBQUF3AE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/CPC72WOY6FR7AMPC56OV2FD5S3ET7A5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYGAZDSMJUUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVJTG633UMVZF62LPOM> and Android <https://github.com/notifications/mobile/android/CPC72WN7AOA46LPAAMBAFLL5S3ET7A5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYGAZDSMJUUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE>. Download it today! You are receiving this because you authored the thread.

[ebndev]

Hi @manager1980ai-debug, thanks for sharing with the community!

Unfortunately, we currently do not allow self-promotion, advertising, or solicitation in Community Discussions. We want to make sure there is space for users to ask questions without overwhelming them with other conversations. Thank you for helping us maintain a productive and tidy community for all our members.