reviewer-readability-check
When a chapter draft is completed/revised or before manuscript build, verify with check_reviewer_readability.py that the prose is at reviewer-readable vocabulary level (internal codes, timestamps, ver
Файлы1
Открыть в GitHubSKILL.mdskills/en/reviewer-readability-check/SKILL.md
GitHubReviewer-Readability Check Skill
Purpose
Manuscript prose (docs/<paper-id>/chapters/) is the reviewer-facing academic layer. Internal symbols (PROP-*, SCAF-FAIL, RQ-*, PH-*, sentence-subject NC-xx, research-program 種① / seed 4) and careless exposure of JST timestamps or protocol version numbers impede comprehension. Section-number anomalies left over from drafting — branch suffixes (3.2b), gaps, duplicates, and dangling § cross-references — are editing traces that must not survive into the final build. This skill maps scripts/check_reviewer_readability.py output to known patterns, classifies each finding as must-fix / needs-review / acceptable, and presents a rationale-backed summary to the author. The goal is to remove dependence on manual read-throughs for readability assurance.
When to Use
- When a chapter draft is completed or revised (mandated by
rules/en/reviewer-readability-rule.md) - When
assemble_manuscript.pyaborts the build on FAIL - When the pre-submission gate reports WARN/FAIL for
reviewer-readability
Principles
- FAIL always blocks: never classify FAIL as acceptable. Rewrite with prose-gloss (Japanese/plain description + parenthesized ID) and re-run
- WARN requires intent check: subject-matter mentions (protocol versions, author-approved timestamps) may be acceptable, but only with author approval and logging
- Preserve the three-layer policy: tables, blockquotes, and code fences are reference layers (exempt). Appendices and the verification inventory keep full internal codes
Procedure
[Step 1: Run script] ➔ [Step 2: Match known patterns] ➔ [Step 3: Present triage summary] ➔ [Step 4: Author approval ➔ Log]
Step 1: Run the script
# Single chapter (on chapter completion)
python3 scripts/check_reviewer_readability.py docs/<paper-id>/chapters/<file>.md
# All chapters (pre-build / pre-submission)
python3 scripts/check_reviewer_readability.py docs/<paper-id>/chapters
If PASS with zero findings, report and stop. Otherwise proceed to Step 2.
Step 2: Match findings to known patterns
| Output pattern | Class | Criteria |
|---|---|---|
FAIL/code (bare PROP-* etc.) |
must-fix | Rewrite as description + parenthesized ID, e.g. "adopted the AI proposal (PROP-ADOPT)" |
FAIL/nc (NC-xx outside parentheses / as subject) |
must-fix | Rewrite as "a case of X (NC-xx)"; never make the ID the subject |
WARN/jst (timestamp in prose) |
needs-review | Consolidate into the audit index table by default; acceptable only for author-approved subject mentions |
WARN/version (v2.x in prose) |
needs-review | Acceptable where the protocol spec itself is the topic; otherwise use "after the protocol revision" etc. |
WARN/jargon (grounding, ingestion, stub, ...) |
needs-review | Parenthesized glosses of defined terms are acceptable; otherwise translate |
WARN/program-id (種①, seed 4, etc.) |
needs-review | Research-program internal numbers. Replace with reader-facing language by default; parenthesized gloss is acceptable |
WARN/density (3+ codes in one line) |
needs-review | Split the paragraph or translate to plain description |
FAIL/secnum-branch (branch suffix like 3.2b) |
must-fix | Insertion trace from drafting. Renumber to a plain sequence and update all in-text references |
FAIL/secnum-dup (duplicate section number) |
must-fix | Renumber the headings |
WARN/secnum-gap (missing section number) |
needs-review | Acceptable if intentional (e.g. planned split); otherwise renumber |
WARN/secnum-dangling (§ ref with no target) |
needs-review | References to external works' sections (three-level numbers like §2.1.1) are out of scope; fix if it is an internal reference error |
For deliberate exceptions, add <!-- readability:ignore --> to the line and record the rationale in the log (do not abuse).
Step 3: Present the triage summary
## Readability triage (<paper-id>, YYYY-MM-DD)
- Scan: FAIL=n / WARN=n
- Classification: must-fix n / needs-review n / acceptable n
| Target | Finding | Class | Rationale | Action |
| :--- | :--- | :--- | :--- | :--- |
| ch4 §4.1.2 | WARN/jst 15:32 JST | acceptable | Author approved keeping the timestamp | none |
| ch5 §5.1.3 | FAIL/nc NC-09 subject | must-fix | prose-gloss policy | rewrite as "the dependency claim (NC-09) ..." |
Step 4: Author approval and logging
- Present the summary and obtain approval, especially for "acceptable" classifications
- After approval, append the decision to
docs/<paper-id>/design/logs/reviewer-readability-log.md(same table format) - After fixing must-fix items, re-run the script and append the result to the same log
Related
- Detection script:
scripts/check_reviewer_readability.py - Enforcement:
assemble_manuscript.py(aborts build on FAIL;--forcebypasses), pre-submission gatecheck_pre_submission.pycheck #5 - General WARN/FAIL triage:
pre-submission-triageskill - Full code definitions: the paper's Appendix A.3 (glossary) and verification inventory §4.2
Outputs
- Readability triage summary (chat)
docs/<paper-id>/design/logs/reviewer-readability-log.md(audit trail of decisions)