Community寫作與編輯github.com

report-review

Review a technical or scientific report, thesis, lab report, design report or technical document as a whole before submission or release - structure and logic, completeness, clarity for a reader without project knowledge, figures and tables, citations and reference list, formulas and notation, terminology consistency, cross-references, open TODO markers and output quality - using a mechanical AsciiDoc/LaTeX linter plus a checklist, and produce a prioritized findings report with concrete fixes. Use this whenever someone asks to review, check, audit, assess, give feedback on, "look over", or do a final/pre-submission/QA pass on a report or thesis (AsciiDoc, LaTeX, Markdown, PDF or Word), asks "is this ready to hand in?", or wants supervisor-style feedback on a draft chapter.

report-review 是什麼?

report-review is a Claude Code agent skill that review a technical or scientific report, thesis, lab report, design report or technical document as a whole before submission or release - structure and logic, completeness, clarity for a reader without project knowledge, figures and tables, citations and reference list, formulas and notation, terminology consistency, cross-references, open TODO markers and output quality - using a mechanical AsciiDoc/LaTeX linter plus a checklist, and produce a prioritized findings report with concrete fixes. Use this whenever someone asks to review, check, audit, assess, give feedback on, "look over", or do a final/pre-submission/QA pass on a report or thesis (AsciiDoc, LaTeX, Markdown, PDF or Word), asks "is this ready to hand in?", or wants supervisor-style feedback on a draft chapter.

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/larsw/report-writing-skills/tree/HEAD/skills/report-review

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Report review

The reviewer stands in for two readers: the fictive reader (technically educated, no knowledge of the project, cannot ask the author) and the assessor (supervisor, customer, referee), who looks first at title, contents, introduction and summary, and who tends to criticize exactly the passages the author was unsure about. When the content is sound, assessors pick on formal details instead, so formal correctness is worth securing.

Method follows H. Hering, How to Write Technical and Scientific Reports (3rd ed., Springer 2025), Sects. 1, 2.4, 3.8 and the report checklist.

1. Scope and rules

  • What is under review: the whole report or one chapter; draft feedback or final check before submission? A draft review emphasizes structure and argument; a final check also covers every formal item.
  • What governs: template, institution or customer rules, journal guidelines, page limit, required parts, citation style, style sheet (style-sheet.adoc). These override the defaults in the checklist; note any conflict instead of silently applying the default.
  • Find the master file and all included files.

2. Mechanical pass

For AsciiDoc and LaTeX, run the linter on the master document (it follows include:: and \input/\include/\subfile; the format comes from the extension):

python3 scripts/lint_report.py path/to/report.adoc          # this skill's directory
python3 scripts/lint_report.py path/to/main.tex
python3 scripts/lint_report.py main.tex --json               # machine-readable
python3 scripts/lint_report.py report.adoc --known-abbrev FEM,CAD   # abbreviations defined in a list

For LaTeX it also reports \label placed before \caption (the reference then prints the section number), figure captions above the graphic and table captions below the tabular, \includegraphics with both width and height (distortion), "Figure \ref" without a tie, straight double quotes, citation keys missing from the .bib files, and leftover \todo notes or \#\#\# gaps. Abbreviations defined through glossaries/acronym (\newacronym, \acro) count as defined.

For AsciiDoc and LaTeX alike it reports, with file:line: headings swallowed into the previous paragraph (missing blank line, typically between include:: lines), table header rows Asciidoctor will not recognize, unresolved cross-references and citations, uncited reference entries, figures/tables without caption, ID or text reference, figures shown before they are mentioned, figures/tables/lists directly after a heading, lone subsections, level skips, too-deep nesting, hand-typed section numbers (and typed numbers that contradict the heading level), heading punctuation, all-caps or one-word headings, text that continues a heading, number–unit spacing, inconsistent percent style, repeated words, spelling variants of compounds, undefined abbreviations, overlong sentences, and open ###/TODO markers (also inside comments). Every finding is a heuristic: confirm it in context before reporting it.

Also, where available:

  • asciidoctor -v --failure-level=WARN … (with the project's -r extensions) and read the warnings (missing includes, unresolved references, diagram errors). Rendering shows what the assessor will actually see; problems such as headings swallowed into paragraphs or table headers rendered as data are invisible in the source. If the toolchain is not available, say so, rely on the linter's structural checks, and never praise or vouch for output you have not seen.
  • LaTeX: build with latexmk -pdf -interaction=nonstopmode main.tex (or the project's build) and read main.log: undefined references and citations, multiply defined labels, "Overfull \hbox" (text running into the margin), float-too-large warnings, missing figures. If installed, chktex adds LaTeX typography checks (spacing after abbreviations, dashes, ties). The same caveat applies: without a build, say so.
  • For a PDF deliverable: pdfinfo (title metadata, page count), pdffonts (all fonts embedded), and a look at the bookmarks and a few pages at 100 % zoom (sharp figures, no overflowing tables, no lone headings at page bottoms).
  • For other input (PDF, Word, Markdown), extract the text (e.g. pdftotext -layout) and do the checks below by reading.

3. Read as the fictive reader

Read the report front to back once without fixing anything; note every place you stumble, guess, or would have to ask. Then check the frame:

  • Title: right keywords, accurate, no wrong expectations; consistent between title page, header and metadata.
  • Contents: does the outline alone show the backbone? Equal-weight siblings, at least two children per subdivision, specific headings, ≤ 3 numbered levels.
  • Introduction: starting situation, relevance, task/goal, route through the report.
  • Summary/conclusions: answers the task stated in the introduction; says what was achieved, what was not and why; no new material. Numbers in abstract, results and conclusions agree.
  • The three clarities: is it clear (1) what the technical statement is, (2) what was known before and what is new, (3) what the author did personally?
  • Argument: each claim supported by data, derivation or citation; doubtful statements either verified or removed ("what is not written cannot be wrong"); no unexplained jumps; no repeated content.
  • Reproducibility of methods and tests (equipment, settings, specimens, instruments, formulas with sources).

4. Checklist pass

Go through references/report-checklist.md area by area. Mark each area pass / issues / not applicable. Skip areas that do not apply (e.g. technical drawings), and say so.

5. Consistency sweep

Across all files: terms against the style sheet (or the dominant variant), abbreviations, notation, capitalization of headings and captions, caption punctuation, citation format, cross-reference wording ("Fig." vs "Figure"), numbering of variants/requirements/sub-functions (same number, name and order everywhere).

6. Report

Rank findings by severity:

  • Critical — fix before submission: wrong or contradictory results, unsupported or doubtful claims, borrowed material without citation, broken cross-references or citations, missing required parts, reproducibility gaps, open ###/TODO markers, violations of mandatory venue rules.
  • Major: outline logic, introduction or summary not doing their job, figures/tables without caption, reference or interpretation, inconsistent terminology, unclear actor or meaning, evaluation-table logic errors.
  • Minor: notation, typography, wording, layout details.

Each finding: location (file:line, section or page), the problem, why it matters for the reader or assessor (one clause), and a concrete fix (a rewritten heading or sentence, or an exact instruction). Group repeated mechanical issues into one finding with a count and the locations rather than listing each.

Format:

# Review: <report title> (<date>)

Scope: <whole report | chapters>, <draft feedback | final check>. Rules applied: <template/style sheet/defaults>.

## Verdict
<2–4 sentences: ready / ready after critical fixes / needs another draft; the biggest lever for improvement.>

## Fix first
1. <change> — <where> — <effort>

## Critical
1. **<short title>** — `file.adoc:123` (Sect. 4.2). <problem>. <why>. **Fix:** <concrete fix>.

## Major
…

## Minor
…

## What works
<2–4 specific strengths to keep.>

## Checklist status
| Area | Status | Note |
|---|---|---|

## Open items for the author
<questions only the author can answer>

Keep the review usable under deadline pressure:

  • Open with Fix first: the 3–7 changes that matter most, in the order to do them, each with a rough effort ("5 min", "needs your data"). Lead with what the assessor will see broken.
  • Group repeated or minor items ("12 number–unit spacings, see list") instead of listing each; a review with 30 equal-looking findings hides the five that matter.
  • In the conversation, print the verdict, Fix first, and the critical and major findings. When there are more than about 15 findings, write the full report to review-YYYY-MM-DD.md next to the master document and say where it is.

Then offer to fix: mechanical issues (spacing, heading punctuation, captions, IDs, cross-references) can be applied directly; language-level problems go to report-copyedit; missing content needs the author. Do not edit the report during the review unless asked; the review is the deliverable.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

report-copyedit

Copyedit and line-edit technical and scientific writing (reports, theses, lab reports, papers, specifications, design docs, technical documentation) for clarity, precision, consistent terminology and correct notation, without changing the technical content. Use this whenever someone asks to copyedit, proofread, line-edit, tighten, simplify, polish the language of, improve the readability or flow of, or "fix the English in" a technical text, AsciiDoc, LaTeX or Markdown file; to make terms, units, abbreviations, hyphenation or capitalization consistent; or to build a style sheet from an existing draft. For a whole-document pre-submission review (structure, figures, references, checklist) use report-review instead.

report-drafting

Draft the content of technical and scientific reports - introduction, state of the art, methods/test setup, results, discussion, summary/conclusions, abstract, appendices - together with their figures, tables, PlantUML diagrams, charts, formulas, computations and citations, in AsciiDoc, LaTeX or plain prose. Use this whenever someone asks to write, draft, expand, or turn notes, data, measurements, code or bullet points into a section of a report, thesis, lab report, design report, project report or technical documentation; to create or improve a figure, diagram, chart, caption, table or evaluation/decision matrix for one; to set up equations or a load calculation; or to add citations and a reference list - even if they just say "write up these results".

report-outline

Plan a technical or scientific report before and while drafting it - analyze the assignment, write and test title variants, condense the core message into one sentence, grow a 4-point then 10-point then detailed outline, pick a structure pattern for the report type (lab/test report, design report, project report, thesis, manual, research paper), and set up a style sheet and an AsciiDoc or LaTeX skeleton. Use this whenever someone is starting or reorganizing a report, thesis, lab report, design report, project report or technical documentation and asks for an outline, structure, table of contents, chapter plan, section order, working title or title ideas, or asks "how should I organize this?" - and also to check an existing outline or ToC for logic (lone subsections, unequal siblings, vague headings).

report-presentation

Turn a technical report, thesis or project into a talk and slide deck, review and polish existing slides or a talk script, and prepare rehearsal, delivery and Q&A - including thesis defenses, project status talks, conference talks and 3-10 minute short statements. Builds decks in asciidoctor-reveal.js (AsciiDoc) or LaTeX Beamer with PlantUML diagrams and speaker notes, and checks them with a deck statistics script. Use this whenever someone asks to make slides, a deck, a presentation or a talk from a report or results, to review, critique or improve slides or speaker notes, to fit a talk into N minutes, to plan a defense or a status update, or to prepare for questions after a talk.

相關技能