Repository navigation
01 Why
A repository rarely fails on code. It fails on documentation: git push succeeds, the tests are
green, and a reader cannot find out how to start. The defect lives for years because nothing
reports it — neither the compiler nor CI.
| Defect | How it looks | Why it hurts |
|---|---|---|
| A README with no installation | architecture and philosophy first | the reader leaves at the second paragraph |
| A changelog with no dates |
## 1.1.0 and nothing else |
versions cannot be compared or linked |
| A wiki with no navigation | ten pages, no links | the pages exist and cannot be found |
| A link to nowhere |
[API](docs/api.md) when the file is docs/API.md
|
documentation "exists" and does not open |
| A three-word description | "panel", "tools" | search never shows the project |
| A repository with no picture | an empty link card | it reads as abandoned |
None of these is caught by running the code. All of them are caught by comparison: a file against a contract, a link against the tree, an anchor against a heading.
The checks are mechanical, but they need attention to details a human does not hold in mind: sixteen required files, anchor rules with Cyrillic, the order of change types, the twenty-topic limit in the API, the 1280×640 rule for a social preview. An agent with one command does this in seconds and does not forget the exceptions.
The other side of that coin: an agent without checks invents. It writes "fast panel" instead of a measured number, and "see the documentation" instead of a link. That is why the pack is built so that every claim is either verified or rejected.
| Situation | Why it is a failure |
|---|---|
| A check examined zero files and returned success | the green result means nothing |
| A link to a wiki page that does not exist | the reader believes the documentation exists |
| A wiki publication deleted a foreign page | data loss without a warning |
| A release with no entries | the changelog stops meaning anything |
| A number in the README with no source | it cannot be verified, so it cannot be trusted |
- Installation — install and verify.
- Platform traps — where GitHub behaves unexpectedly.
- File contracts — what exactly is checked.
репозиторий · релизы · MIT