fresh-eyes-review

Before you hand a document to your dev / QA / ops team, you want to know one thing: will a real person actually understand it?

This skill answers that. It role-plays several human readers (personas) and has each of them read your handover / onboarding / handbook docs the way a human actually reads — one file at a time, with limited memory, getting tired and lost like a person would — not like an AI that scans every file at once and remembers everything. It then reports exactly where the receiving team will get confused, give up, or bounce the document back to you.

Use it as a pre-flight check for any document set before it goes out.

Core principle — read like a human, report like an analyst. What counts as a problem is decided by a real human's sequential, limited-memory read — never an all-at-once AI scan. The report itself is clean and structured (AI-style: tables, impact/effort priority, verified file:line citations). The human voice stays only in the experiential parts: the running log, fatigue & flow, the 😤 gut-reaction column, and the verdict.

Advisory only. Everything this skill produces is guidance you act on yourself — it reports and recommends, it never fixes or rewrites the docs. Treat the output as a list of suggestions, not edits.

When to trigger

Invoke this skill when the user says things like:

• "blind test these docs" / "read this like a real person" / "fresh eyes"
• "review this onboarding / handbook / handover before I send it to the team"
• "I just finished the handover doc — is it ready to send?" / "about to hand this off to the team"
• "would a new hire actually understand this?"
• "will the team bounce this back?"
• "have a few team members read this and tell me what breaks"

Works on any folder of documents — it is generic and not tied to one repo.

Not for code review, writing software test cases, or finishing a coding task — this skill reviews documents only. If the "finish / about to send" moment is about code rather than a document, this is the wrong tool.

Operating principle — READ-ONLY (non-negotiable)

This skill only reads and reports. It never changes anything.

• ❌ Never edit, create, or delete files. Never propose a diff/patch. Never open a PR.
• ❌ Never run anything with side effects: no build, migrate, deploy, push, or tests that write to a database.
• ✅ Only read-style commands are allowed (ls, cat, grep, find, reading file:line) — used to "open files the way a real reader would open them."
• ✅ Output is a report in the conversation only. Do not write results to disk unless the user explicitly asks.

If the user wants the findings fixed, say that this skill reviews only — they should use a separate edit/authoring flow, then re-run fresh-eyes-review to confirm the fixes landed.

Cite only what you verified

Every file:line, heading anchor, and link in the report must be derived from the actual file content you opened — not from memory or a plausible guess.

• Never fabricate a heading anchor. Don't assume the GitHub/Markdown slug from the heading text. (Real example: a heading "Phase / Mini-Phase / M-prefix codes" produces the anchor #phase--mini-phase--m-prefix-codes, not §"M-prefix codes".) If you haven't confirmed the exact slug, cite the heading text in prose and mark the precise anchor as unverified — don't invent one.
• Verify line numbers and quoted text against the file before citing them.
• A wrong link or line number is worse than none: it sends the reader nowhere and makes them distrust the whole review. When unsure, say "around §X / near line N (verify)" instead of stating a fake exact target.

Output language

Write the report in the same language as the documents being reviewed — Thai docs → Thai report, English docs → English report.

Reason: flow, tone, and word-level ambiguity can only be judged in the reader's actual language. If the docs mix languages, report in the document's primary language and flag any place where the language-switching itself causes friction.

Workflow (follow in order)

Step 0 — Confirm the document scope

If not already given, ask the user: which folder / files should be reviewed? Record the path clearly. In Mode A (blind) this scope is the hard boundary you must not read outside of.

Step 1 — Ask for the reading mode (A / B / C)

Let the user choose before you start:

If the user doesn't choose, default to A (blind) — it best matches the core question "would a new reader understand this?"

Recommended flow for a large doc set: start with Mode A (blind) and iterate — review → the author fixes the docs based on the suggestions → re-run blind — until blind comprehension is solid (~80–90% across personas). Only then move to Mode B (full repo) to catch drift against the code. Don't jump to full-repo while the docs still fail the blind read: fix self-sufficiency first, accuracy second. (The skill only recommends — the author does the fixing between runs.)

• Mode A (Blind): Read only the files inside the specified docs folder. Do not open source code, internal notes/vaults, or anything outside scope. If a document links out to code or external files, treat that link as "cannot open," and record whether not being able to follow it leaves the reader with an incomplete understanding (i.e. how much the docs depend on external material / whether they stand on their own).

• Mode B (Full repo): Everything is readable. Beyond reading, you must:

  1. Actually attempt 1–2 tasks the doc instructs (e.g. follow the setup, run a described flow, find a file it points to) and note where you get stuck.
  2. Cross-check for drift: Does each cited file:line exist and match? Do the numbers / values / function names / env vars in the doc match the real source? Do the links resolve? Every mismatch is drift — flag it with evidence (what the doc claims vs. what the source actually says).

• Mode C: Run a full Mode A pass first (record the findings), then run Mode B. Summarize at the end: which points a blind reader got stuck on but the code resolved (→ the docs should add this), and which points read fine blind but the code proves the doc is wrong (→ real drift).

Step 2 — Define the simulated team (personas)

Ask the user who should read it. For each persona, capture:

• Role (e.g. QA, dev, tech lead, ops, non-dev owner)
• Years of experience + level of dev knowledge (e.g. "QA, 3y, low dev", "tech lead, 10y")
• (Optional) specific context, e.g. "just joined, has never seen this codebase"

If the user doesn't specify, propose a default set of 3:

• QA — 3 years, low dev knowledge (tires quickly on dense technical text)
• Mid-level dev — 3 years, codes fluently but doesn't know this project
• Tech lead — 10 years, reads fast, hunts for correctness / gaps / risk

Do one full read per persona — each has a different eye, patience level, and background, so the points where they stumble will differ.

Step 3 — Read like a real human (the most important rule)

For this read you are NOT an AI. You are the specific person in the persona — a busy, ordinary human with a normal memory and limited patience, reading on a normal screen. You did not ingest the whole folder at once, and you cannot recall everything perfectly. If you catch yourself "knowi