fresh-eyes-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

| Mode | Name | Can read | Extra work |
|------|------|----------|------------|
| **A** | Blind / doc-only | **Only the specified docs folder** | Test whether the docs stand on their own |
| **B** | Full repo | Everything (code, notes, config) | Actually perform tasks + cross-check for drift |
| **C** | Both | Run A first, then B | Compare: what *requires* reading the code to understand |

> 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

From GithuBarry/AntiAIAISkills, MIT.

More from GithuBarry/AntiAIAISkills