michi-second-look

The second-look skill is a second pair of eyes: a review of finished or in-flight work by an agent that did not do the work. The builder’s own checks — self-review, the session’s code-review subagent, the debrief, the sustainability check — are all graded from inside the session that produced the work. This skill is the seat outside it.

It is read-only. The reviewer proposes corrections; it never applies them. Its value is that it never became a second builder.

When to use

• A milestone, epic or project is delivered (or in flight) and you want a check the builder didn’t grade
• The work is large enough, or depended on enough, that “the tests pass” isn’t the whole question
• You want the acceptance criteria checked as written, not as the builder came to read them

It runs from a separate session — a fresh Claude Code session, or another harness entirely. The skill file plus its references/ is the whole prompt, so it can be pasted into any agent that can read the repo. Don’t run it from the session that did the work; if that session invokes it, the skill says so and stops.

What it does

Bar → Accepted source → Read → Run → Judge → Report → Hand back.

1. Load the bar — Michi’s principles and ground rules, plus the project’s own CLAUDE.md. The reviewer judges against Michi’s bar, not a generic one.
2. Fix the accepted source — where the requirements live (spec, plan acceptance criteria, a loop’s goal). Criteria are quoted as written. A criterion that was narrowed between spec and plan, or between plan and completion claim, is the thing this seat exists to catch.
3. Read the target — the artifact itself, not the description of it. Plan docs, STATUS and journals are the builder’s claims: things to check, not facts to repeat.
4. Run what you can — the project’s tests, build, lint and the plan’s own verification commands, in a scratch copy. Read the output. What can’t be run is recorded as not run, never as passed.
5. Judge on four lenses — requested vs observed (per criterion: met, unmet, unverifiable, with evidence); claims (spot-check the builder’s counts and “all pass”); design (against Michi’s bar, using the sustainability checklists); process (do the decisions match the artifact; did anything get written under the human’s name that they didn’t say).
6. Write one report — for two readers. The human reads it cold: tl;dr, findings table, requested vs observed, detail, what was examined and judged sound, open questions. The builder acts on it by ID. Severity is low / medium / high / critical. A verdict names only what was examined.
7. Hand back a pointer — the path and the severity counts, not the report.

Audit mode

/michi-second-look audit [scope] asks a different question from the same seat. The review asks did we build what was accepted? The audit asks what should change?

• Dependencies — the ecosystem’s own tools (npm outdated, npm audit or their equivalents) run read-only in a scratch copy, then judged: which updates matter, why, and which are deliberately left alone.
• Architecture and design — the project’s stated intent (ARCHITECTURE.md, PROJECT.md, CLAUDE.md) against the tree: drift, accretion, leaking boundaries, what the design can no longer express.
• Test-suite health — the suite run and read: duration, flakiness, skipped tests, plus mocks at the wrong boundary and tests that assert on mechanism rather than outcome.
• Patterns and libraries — hand-rolled code a well-maintained library handles better, and idioms the project should now be using.

Output is a recommendations table rated on Michi’s S / M / L / XL scale for effort and benefit — not a severity — so the tradeoff is visible before anything is decided. Every recommendation names the problem in this codebase it solves; “this is what people do now” is not a reason. Accepting a recommendation means planning it, not doing it in the dispositions pass.

When the report reaches the builder

The human reads first, then presents the report to the building session. Every finding gets a disposition, written by ID:

• accept — and the disposition names the measurement that confirmed it. Reproduce before you accept; a disposition written from the report rather than from the tree is the same defect the report is about.
• contest — only with evidence: a file, a run, a source the reviewer missed. Reasoning alone is not a contest.
• defer — the human’s call, named as such.

“Noted” is not a disposition. The disposition list is what keeps a review from being rationalized away.

Key things to know

• Independence is about the brief, not the files. The reviewer has full read access. What it doesn’t get is a summary, a scope, or an explanation from the session that built the work.
• A focus hint may only add attention. It cannot remove a criterion or declare anything out of scope. The criteria stay whole, because the invocation may have been drafted by the builder.
• Corrections are before/after quotes. Typos, broken links, wrong counts go in the report; you or the builder apply them.
• A documented gap is not a met criterion. Naming a miss does not close it.
• What it found beats how it would have built it. Design findings are against the bar, not the reviewer’s taste.

For the full agent instructions, see the SKILL.md source.