self-review

# Self-Review Skill

You are helping a medical researcher check their own manuscript before journal submission.
The goal is to anticipate reviewer comments by applying the same critical lens used in
peer review across medical journals.

This is NOT about writing a review. It's about producing an actionable list of
anticipated reviewer comments with specific fix suggestions, so the manuscript can be
strengthened before reviewers ever see it.

## Optional Flags

- `--fix`: After generating the review report, automatically apply fixes for all issues where `fixable_by_ai` is true. Edits the manuscript in place, then reports a diff summary. Does NOT fix issues marked `fixable_by_ai: false` (e.g., missing data, design flaws). Maximum 2 fix-and-re-review iterations.
- `--json`: Output the structured JSON block (see Phase 3c below) in addition to the markdown report. Default when called from `/write-paper` Phase 7.
- `--panel`: Run the multi-agent panel review (Phase 2.6) — several domain-expert reviewers in parallel plus an editor synthesis — instead of the single-pass review. Opt-in and **off by default** (a panel spawns N reviewer agents + 1 editor, so it costs several times more tokens). Reserve it for a high-stakes pre-submission final pass on a top-tier target. Do **not** combine with `--fix`: a panel diagnoses and prioritizes; run `--fix` as a separate follow-up pass once the author has triaged the panel's findings.

## Severity Framing

When flagging issues, classify severity:
- **Fatal**: Fundamental design flaw that cannot be fixed with existing data (e.g., data leakage
  that invalidates all results, absence of any reference standard, label-feature circularity).
  The manuscript likely needs redesign. Submission would likely result in Reject.
- **Fixable**: Significant but addressable with existing data (e.g., missing calibration analysis,
  unclear exclusion criteria, absent CIs, incomplete reporting). These are the most actionable findings.

Most issues are Fixable. Reserve Fatal for true design-level problems.

## Two Objectives: the Floor and the Ceiling

A submission-ready manuscript optimizes **two** things at once, and most of this skill (and
the gate stack behind it) only optimizes the first:

- **Floor — minimize rejection-for-cause.** Fabricated citations, numbers that do not
  reconcile, overclaims, missing checklist items, leakage. Categories A–K and the
  deterministic gates (Phases 2.5–2.5f) do this, and they are right to. Many of them raise the
  floor by **adding** material: a hedge, a caveat, a disclosure, an audit trail, a checklist row.
- **Ceiling — maximize editorial-championing.** Will a handling editor read a *confident
  narrative* (problem → design → result → meaning) and want to send it out, or a *defensive
  audit* and bounce it? Nothing in the floor stack pushes here, and several floor gates push the
  other way. Iterated, a manuscript over-hardens: every individual gate finding is correct, yet
  the **accumulated** product reads as a rebuttal letter — over-hedged, audit-trail-heavy,
  Abstract buried under caveats, the strongest sensitivity result hidden in Limitations, too long.

These objectives can conflict, so the order matters: **the floor gates run first and secure
accuracy; then the ceiling pass (category L / Phase 2.5g) reads the accurate manuscript as a
whole and recommends SUBTRACTION — REMOVE, MOVE, or TIGHTEN — so the same content is read
confidently.** The ceiling pass is advisory and never blocks; it cannot relax a floor gate.
Without it, repeated self-review monotonically over-defends. Surface the ceiling findings as
their own first-class output (Phase 3), not folded silently into the "add this" comments.
**Phase 2.5i (the loop controller)** then reads the floor + ceiling state to declare when
the loop is *done* — including a zero-edit PASS — so an accurate draft is not over-hardened
by a pass it does not need.

## Workflow

### Phase 1: Intake

1. Get the manuscript -- PDF, Word doc, or pasted text.
2. Ask the user:
   - Target journal? (affects reporting standards and scope expectations)
   - Manuscript type? (original research / review / perspective / technical note / letter / meta-analysis / case report)
   - Anything they're already worried about?
   - **Review depth?** The default is a single-pass review. For a high-stakes pre-submission final pass, a multi-agent **panel** (`--panel`, Phase 2.6) is available — several domain-expert reviewers run independently, then an editor consolidates them (more thorough, but it spawns several agents so it costs several times more tokens). On an interactive run, surface this option **once** in one line and offer it; then proceed with the single-pass review unless the user opts in. Do **not** surface or auto-apply the panel when invoked with `--json` or from `/write-paper` — those stay single-pass.
3. Read the full manuscript.
4. **SSOT gate — confirm there is one manuscript, not several.** Self-review reads a single
   input file, so a divergence between a legacy working copy and the live submission copy is
   structurally invisible to it. Before a `--panel` run (or any pre-submission pass), check for
   multiple copies and reconcile first:

   ```bash
   find . \( -path '*manuscript*' -o -path '*main_document*' \) -name '*.md' | grep -v node_modules
   ```

   If more than one manuscript-like file exists, confirm which is the SSOT and run
   `/sync-submission`'s divergence gate before reviewing — a `STALE_COPY` (an SSOT numeric claim
   or heading that did not propagate to the other copy) is a P0 that must clear first:

   ```bash
   python3 "${MEDSCI_SKILLS_ROOT:-$HOME/workspace/medsci-skills}/skills/sync-submission/scripts/detect_copy_divergence.py" \
     --ssot <ssot>.md --copy <other-copy>.md
   ```

   Review the SSOT copy; do not review a stale copy and pass it.

   **In `--panel` mode this is a blocking precondition, not advice.** A panel spawns N reviewer
   agents + an editor, so reviewi