Repo health sweep
The self-review owns the agent's own surface. This sweep owns the rest of the
repository: the published docs, the skills that describe the package, the
repo's own conventions, and the runnable examples. Where they overlap, this
skill covers the parts the self-review does not.
The failure mode is the same as self-review: a confident claim that is quietly
out of date, and the expensive version is claiming something does not exist.
Every check in this sweep is grounded in the current main before it is
written down. This is the source-research procedure over the whole repo, not
anything recalled.
The rule that never bends
A finding names the file and the rule or source it contradicts, or it is
dropped. A claim that an option, export, adapter or page is missing is proven
by enumerating the real surface, never by the absence of a memory. Load
source-research and follow it before drawing a conclusion about any package
behavior.
The four lenses
Skills vs reality
Every SKILL.md, internal and published, checked against the package surface it
describes.
- Internal:
.agents/skills/* (create-adapter, create-enricher,
create-framework-integration, create-map-rule) and apps/evi/agent/skills/*.
- Published:
skills/* (analyze-logs, build-audit-logs,
review-logging-patterns).
- What to check: every API name, option, default, or adapter the skill shows.
An
evlog.X option must exist under that name; a function signature must be
the real one (a curried call shown where the API is two-arg is a bug); a
framework must export what the skill claims it does or does not.
- Bar: a skill that describes old behavior is worse than no skill (
AGENTS.md).
When a code change fixed a skill in this repo, that fix is the evidence the
skill used to drift.
Docs quality
The published docs are the contract, so a wrong page costs real users.
- Pages that are unclear, stale, or inconsistent with each other. A page that
contradicts a sibling page about the same API is a finding even when both are
wrong the same way.
- A feature that shipped without a docs page, or an option documented with the
wrong default.
- A table (adapters, env vars, exports, flags) that lists sources the code does
not read, or omits ones it does. Cross-check against source, not against an
older page.
- Anything
source-research could not answer because no page covers it.
Convention drift
Places where the code or prose violates the repo's own rules.
- Root
AGENTS.md: export registration in all three of package.json#exports,
package.json#typesVersions, tsdown.config.ts; no evlog/shared import
(evlog/toolkit is the public name); the style rules ("no as any", no silent
fallbacks, no speculative options) applied to new code.
- Changeset policy: a user-facing change merged with no changeset, or a
changeset shipped for a change confined to
apps/*.
- Test placement: logic under
agent/ or packages/*/src with no colocated
test, or the repo's testing rules (framework tests driving the real request
driver) violated.
- Consistency with its own stated convention, including the ones in
AGENTS.md
that the prose itself breaks.
Examples drift
examples/* must match the current API. The examples are the first thing a
user reads after the docs.
- A runnable example importing an option, export or signature that no longer
exists, or relying on a default that changed.
- A skeleton directory (the
community-*-skeleton dirs used by the create-*
skills) that no longer matches what the skill generates.
Grounding
- Run before you assert. Anything you claim about the package surface is
executed in
/workspace/repo on main or read from source. If it could not
be verified, it is written as a question, never as evidence in a PR body.
- Absence is proven by listing. Enumerate the exports map, the docs index,
the adapters directory, the connect registry before calling something
missing.
- One counter-example kills a finding. Grep the whole repo, not the
directory you were reading.
Dedupe
Before filing anything: linear__list_issues on the evlog team, and
github__searchIssues for an open issue, PR or draft on the same ground,
including your own earlier runs. A stale draft that still applies gets a rebase
and a comment, not a replacement. A finding Hugo closed once does not come
back.
Deliver
One report with concrete findings, each citing the file and the rule or source
it contradicts, plus proposed diffs for the easy ones. The report is the
deliverable; it goes to a Linear document, with a summary comment on the issue.
- Mechanical fix, checks green, no judgement needed → draft PR. One per
finding, never bundled. Follow
contributing: branch off main,
pnpm run lint, pnpm run typecheck, pnpm run test. An apps/evi or
apps/docs content change never needs a changeset; a change to a published
package does.
- Everything else → Linear issue via
linear__save_issue on the evlog
team, or a proposal in the report when it is a decision rather than a fix.
Name the problem, what it contradicts, where it is, and the decision to make.
- A proposal never ships as code on your own initiative. The report is the
deliverable; building it is Hugo's call.
Post one line per artifact to the thread, links inline.
When nothing is warranted
One line: the lenses ran and nothing came up. Never invent a finding to fill
the run, never file an issue to report that a lens was clean, and never open a
PR for a rule the repo does not actually state.
1---2name: repo-health-sweep3description: Bi-weekly pass over the whole evlog repository, not just the agent's own surface. Checks every SKILL.md against the real package surface, the docs tree for stale or self-contradictory pages, the repo's own conventions, and the examples against the current API. Load this when the repo-health-sweep schedule fires, or when Hugo asks for a repo health sweep, a docs audit, a skills-vs-reality check, or a convention drift review.4---5
6# Repo health sweep
7
8The self-review owns the agent's own surface. This sweep owns the rest of the
9repository: the published docs, the skills that describe the package, the
10repo's own conventions, and the runnable examples. Where they overlap, this
11skill covers the parts the self-review does not.
12
13The failure mode is the same as self-review: a confident claim that is quietly
14out of date, and the expensive version is claiming something does not exist.
15Every check in this sweep is grounded in the current `main` before it is
16written down. This is the `source-research` procedure over the whole repo, not
17anything recalled.
18
19## The rule that never bends
20
21A finding names the file and the rule or source it contradicts, or it is
22dropped. A claim that an option, export, adapter or page is missing is proven
23by enumerating the real surface, never by the absence of a memory. Load
24`source-research` and follow it before drawing a conclusion about any package
25behavior.
26
27## The four lenses
28
29### Skills vs reality
30
31Every SKILL.md, internal and published, checked against the package surface it
32describes.
33
34- Internal: `.agents/skills/*` (create-adapter, create-enricher,
35 create-framework-integration, create-map-rule) and `apps/evi/agent/skills/*`.
36- Published: `skills/*` (analyze-logs, build-audit-logs,
37 review-logging-patterns).
38- What to check: every API name, option, default, or adapter the skill shows.
39 An `evlog.X` option must exist under that name; a function signature must be
40 the real one (a curried call shown where the API is two-arg is a bug); a
41 framework must export what the skill claims it does or does not.
42- Bar: a skill that describes old behavior is worse than no skill (`AGENTS.md`).
43 When a code change fixed a skill in this repo, that fix is the evidence the
44 skill used to drift.
45
46### Docs quality
47
48The published docs are the contract, so a wrong page costs real users.
49
50- Pages that are unclear, stale, or inconsistent with each other. A page that
51 contradicts a sibling page about the same API is a finding even when both are
52 wrong the same way.
53- A feature that shipped without a docs page, or an option documented with the
54 wrong default.
55- A table (adapters, env vars, exports, flags) that lists sources the code does
56 not read, or omits ones it does. Cross-check against source, not against an
57 older page.
58- Anything `source-research` could not answer because no page covers it.
59
60### Convention drift
61
62Places where the code or prose violates the repo's own rules.
63
64- Root `AGENTS.md`: export registration in all three of `package.json#exports`,
65 `package.json#typesVersions`, `tsdown.config.ts`; no `evlog/shared` import
66 (`evlog/toolkit` is the public name); the style rules ("no as any", no silent
67 fallbacks, no speculative options) applied to new code.
68- Changeset policy: a user-facing change merged with no changeset, or a
69 changeset shipped for a change confined to `apps/*`.
70- Test placement: logic under `agent/` or `packages/*/src` with no colocated
71 test, or the repo's testing rules (framework tests driving the real request
72 driver) violated.
73- Consistency with its own stated convention, including the ones in `AGENTS.md`
74 that the prose itself breaks.
75
76### Examples drift
77
78`examples/*` must match the current API. The examples are the first thing a
79user reads after the docs.
80
81- A runnable example importing an option, export or signature that no longer
82 exists, or relying on a default that changed.
83- A skeleton directory (the `community-*-skeleton` dirs used by the create-*
84 skills) that no longer matches what the skill generates.
85
86## Grounding
87
88- **Run before you assert.** Anything you claim about the package surface is
89 executed in `/workspace/repo` on `main` or read from source. If it could not
90 be verified, it is written as a question, never as evidence in a PR body.
91- **Absence is proven by listing.** Enumerate the exports map, the docs index,
92 the adapters directory, the connect registry before calling something
93 missing.
94- **One counter-example kills a finding.** Grep the whole repo, not the
95 directory you were reading.
96
97## Dedupe
98
99Before filing anything: `linear__list_issues` on the evlog team, and
100`github__searchIssues` for an open issue, PR or draft on the same ground,
101including your own earlier runs. A stale draft that still applies gets a rebase
102and a comment, not a replacement. A finding Hugo closed once does not come
103back.
104
105## Deliver
106
107One report with concrete findings, each citing the file and the rule or source
108it contradicts, plus proposed diffs for the easy ones. The report is the
109deliverable; it goes to a Linear document, with a summary comment on the issue.
110
111- **Mechanical fix, checks green, no judgement needed → draft PR.** One per
112 finding, never bundled. Follow `contributing`: branch off `main`,
113 `pnpm run lint`, `pnpm run typecheck`, `pnpm run test`. An `apps/evi` or
114 `apps/docs` content change never needs a changeset; a change to a published
115 package does.
116- **Everything else → Linear issue** via `linear__save_issue` on the evlog
117 team, or a proposal in the report when it is a decision rather than a fix.
118 Name the problem, what it contradicts, where it is, and the decision to make.
119- **A proposal never ships as code on your own initiative.** The report is the
120 deliverable; building it is Hugo's call.
121
122Post one line per artifact to the thread, links inline.
123
124## When nothing is warranted
125
126One line: the lenses ran and nothing came up. Never invent a finding to fill
127the run, never file an issue to report that a lens was clean, and never open a
128PR for a rule the repo does not actually state.
evloghq