self-review

# Self review Two halves, run together, because they fail in opposite directions. **Coherence** is what drifted: two halves built at different times that never met, a rule the code stopped obeying, a description that outran its tools. Nothing is broken, no test fails, nobody files it. **Reach** is what is missing: a capability the platform now offers and this agent never adopted, a step you have done by hand three weeks running, a hole in evlog that users keep walking into. Nothing is wrong, so nothing prompts it. Skipping the second half turns this run into a regression sweep. Skipping the first turns it into a wishlist. Run both. ## Two kinds of output, two bars A **finding** contradicts something written down or something declared: a rule in a guide, a capability the app announces, a description that promises behavior the tools do not deliver. Name the prose or the declaration it contradicts, or drop it. A **proposal** is a capability worth having that nothing yet argues for. It needs an observation, not a contradiction: the friction you hit, the tool that shipped, the request that came back a third time. Name what you observed and when, or drop it. Neither bar is met by taste. "I would have written this differently" is not a finding, and "this would be cool" is not a proposal. Both are refusals to do the work of grounding. --- # Part one: coherence ## A. Wiring gaps Something is produced and nothing consumes it. For each connection, extension and channel under `agent/`, ask what it puts into a session or returns to the model, then grep for a consumer. - Context blocks eve injects, session `state`, channel metadata. `issue_identifier` sat in every delegated Linear session for weeks before anything read it (#555). - Values computed in `agent/lib/` and returned to no one. - The inverse: an `agent/lib/` module with a colocated test and no import outside that test. ## B. Guides the code stopped obeying | Guide | Check | | --- | --- | | Root `AGENTS.md` | A new entrypoint registered in all three of `package.json#exports`, `package.json#typesVersions`, `tsdown.config.ts`. No `evlog/shared` import (`evlog/toolkit` is the public name). No HTML comment in a Vue `<template>`. | | Root `AGENTS.md` | Every framework integration exposes the same contract: `evlog()`, `useLogger()`, `log.fork()`. `evlog/workers` is the documented exception. | | `apps/evi/docs/capability-placement.md` | The two-layer rule: a file under `agent/` outside `agent/lib/` holding logic instead of wiring, an `agent/lib/` module with no colocated `*.test.ts`, or a caller check written inline instead of going through `agent/lib/trust.ts`. | | `packages/evlog/test/README.md` | A framework test driving the app by hand instead of through its real request driver. | | Root `AGENTS.md` | A behavior change whose matching `.agents/skills/` or `skills/` SKILL.md still describes the old shape. | ## C. Prose that outran the tools Read the strings the model actually sees against the tools it actually has. - Each `agent/connections/*.ts`: does the `description` name a capability the `tools.allow` list omits? - Each `agent/skills/*/SKILL.md` and `agent/instructions.md`: every tool name mentioned must exist. A skill pointing at an unreachable tool fails silently at the worst moment. - Every output destination `instructions.md` names must be writable from the posture that reads it. ## D. Production signals Read-only, and these become issues, never PRs. - `telemetry-stats`: an error code climbing week over week, a command whose success rate is falling. - CI on `main`: a job failing intermittently is a finding even when the reruns go green. - `vercel__get_runtime_errors` (production): a runtime error cluster growing week over week, or one whose route has no docs page explaining it, is a docs proposal with a number attached. - Evi's own production runs: `vercel__list_agent_run_projects` to find the eve service project, then `vercel__list_agent_runs` for sessions that ended badly or never answered and the failed tool calls inside them. Drill into a failure with `vercel__get_runtime_logs`. --- # Part two: reach ## E. Capability the platform gained The frameworks under this agent ship faster than it adopts them. - `eve registry search <query>` and `eve registry list`: integrations that exist and are not installed. Read one with `eve registry view <item>` before proposing it. The repo rule is to check the registry before building an integration by hand, so a hand-rolled tool duplicating a registry item is both a proposal and a finding. - Connections already wired whose server grew: a Linear, Vercel or telemetry tool that did not exist when the allowlist was written. - `upstream-sync` owns version bumps and workaround removal. This lens is about capabilities never adopted, not versions behind. When the two overlap, leave it to that skill. ## F. Surface already paid for and unused The cheapest new capability is one already connected. - A tool in a `tools.allow` list that no skill and no instruction ever tells Evi to call. Either a workflow is missing or the entry is, and both are worth saying out loud. - Objects a connected service offers that Evi never touches: Linear milestones and status updates, Vercel analytics dimensions, telemetry breakdowns that no skill reads. - A schedule that could carry work it does not: the digest already gathers numbers that another skill re-fetches. ## G. The step that keeps repeating The strongest proposals come from your own friction, and it is only visible from the inside. - A sequence you have run by hand more than twice across sessions is a skill waiting to be written. That is the cheapest capability in `capability-placement.md` and needs no code. - A question Hugo asked in three different weeks is a skill or a schedule. - A turn where you lacked a tool and worked around it, or read fifteen files to answer one question, is evidence for a tool or a subagent. `capability-placement.md` states the observed trigger for a subagent; cite it or do not propose one. ## H. Where evlog itself falls short Look outward, not only at the agent. - `telemetry-adoption`: a flag or custom field nobody uses two releases in is a deprecation candidate; a custom field spreading on its own is a workflow worth making first-class. - The top error code from `telemetry-stats` with no docs page covering it is a docs proposal with a number attached. - Community issues and discussions asking for the same integration, adapter or option a third time. - A docs lookup that came up empty during a session: it usually means a page is missing. ## I. Ideas already written down and never filed The repo carries proposals nobody turned into work. - `apps/evi/docs/notes.md`, section **Open**. - `apps/evi/docs/observability.md`, section **Proposals**. These are pre-grounded: someone already did the reasoning. An entry that still holds and has no issue is the easiest proposal of the run. One that no longer holds should be deleted from the doc, which is a finding. --- # Grounding The failure mode of this run is a confident output that is wrong, and the expensive version is claiming something does not exist. - **Absence is proven by listing, never by recall.** Before writing that a tool, option, field or export is missing, enumerate the real surface: `connection_search` for a connection's tools, the file for an exports map, the docs index for a page, `eve registry list` for an integration. A name you do not remember seeing is not a name that is absent. - **Never describe a check you did not run.** If you could not verify something, say so in those words and file it as a question. It never enters a PR body as evidence. - **One counter-example kills a finding.** Before filing "nothing consumes X", grep the whole repo for X, not just the directory you were reading. - **A proposal names its cheapest form.** Walk `capability-placement.md` in order and say which rung it lands on and why not the one above. A proposal that arrives as "we should build a tool for this" without that walk is not ready. ## Dedupe Before filing anything: `linear__list_issues` on the evlog team, and `github__searchIssues` for an open issue or PR on the same ground, including your own drafts from earlier runs. A stale draft that still applies gets a rebase and a comment, not a replacement. A finding or proposal Hugo closed once does not come back: the decision was made. ## Deliver **Mechanical fix, checks green, no judgement needed → draft PR.** One per finding, never bundled. Follow `contributing`: branch off `main` in `/workspace/repo`, run `pnpm run lint`, `pnpm run typecheck` and `pnpm run test`, add a changeset when the change touches a published package (an `apps/evi` change never needs one). The PR body names the guide or the declared capability the code contradicted. **Everything else → Linear issue** via `linear__save_issue` on the evlog team. A finding states the problem, what it contradicts, where it is, and the decision to make. A proposal states the observation that triggered it, what the capability would do, the rung of `capability-placement.md` it lands on, and what it costs. Label the two apart so the backlog stays readable. **A proposal never ships as code on your own initiative.** The repo forbids speculative code, and an unrequested capability is exactly that. The issue is the deliverable; building it is Hugo's call. Cap a run at three draft PRs and two proposals: the two you would defend, not everything that came to mind. Anything past the cap is named in the summary with a count, so a heavy week is visible rather than silently trimmed. Then 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. A quiet week is a real result, and both halves are allowed to be quiet.