humanize

Files (32)

• SKILL.md
• ai_patterns.md · references/
• check_rewrite_fidelity.py · scripts/
• check_sentence_variety.py · scripts/
• skill.yml
• fidelity_assign_after_ineq.md · tests/fixtures/
• fidelity_assign_after_same.md · tests/fixtures/
• fidelity_assign_after_swap.md · tests/fixtures/
• fidelity_assign_before.md · tests/fixtures/
• fidelity_cite_after_keyswap.md · tests/fixtures/
• fidelity_cite_after_locator.md · tests/fixtures/
• fidelity_cite_after_moved.md · tests/fixtures/
• fidelity_cite_after_same.md · tests/fixtures/
• fidelity_cite_before.md · tests/fixtures/
• fidelity_reorder_after.md · tests/fixtures/
• fidelity_reorder_before.md · tests/fixtures/
• fidelity_swap_after.md · tests/fixtures/
• fidelity_swap_before.md · tests/fixtures/
• rewrite_after_bounded.md · tests/fixtures/
• rewrite_after_numdrift.md · tests/fixtures/
• rewrite_after_wholesale.md · tests/fixtures/
• rewrite_before.md · tests/fixtures/
• rewrite_direction_after_flip.md · tests/fixtures/
• rewrite_direction_after_minus.md · tests/fixtures/
• rewrite_direction_after_same.md · tests/fixtures/
• rewrite_direction_before.md · tests/fixtures/
• variety_long_within_bound.md · tests/fixtures/
• variety_mixed.md · tests/fixtures/
• variety_overlong.md · tests/fixtures/
• variety_uniform.md · tests/fixtures/
• test_rewrite_fidelity.sh · tests/
• test_sentence_variety.sh · tests/

SKILL.md (first lines)

# Humanize Skill

This skill only removes AI patterns; it does not perform general copy-editing, evaluate
scientific quality, check journal formatting, or translate.

Read `${CLAUDE_SKILL_DIR}/references/ai_patterns.md` at the start of every session, before
scanning: the definitions, watch words, examples, detection greps, per-pattern fixes and the
section-by-section priorities for all 27 patterns live only there.

---

## Workflow

### Phase 1: Scan

Scan the section(s) the user provides for all 27 patterns. For response-to-reviewers letters and
cover letters, prioritise Patterns 22-24. For a full manuscript, follow the per-section priorities
in `ai_patterns.md` (Section-Specific Application Guide). For each pattern found, record its number
and name, the count, the exact passage, and its location (paragraph number or line range).

**Output: Pattern Frequency Table**

```
## AI Pattern Scan Report

Section: {section name}
Word count: {N}

| # | Pattern | Count | Severity | Example from text |
|---|---------|-------|----------|-------------------|
| 1 | Significance inflation | 3 | HIGH | "...pivotal role in diagnostic imaging..." |
| ... | ... | ... | ... | ... |

Patterns not detected: 2, 4, 9, 14, 15

Total AI pattern instances: {N}
AI pattern density: {N per 1000 words}
```

### Phase 2: Report

- Severity per pattern: **HIGH** (>3 occurrences), **MEDIUM** (1-3), **LOW** (0, clean).
- Density: total instances across all 27 patterns per 1000 words. Target: < 2.0.

**Gate:** Present the report and ask the user which patterns to fix. Default: fix all HIGH and MEDIUM.

### Phase 3: Fix

Rewrite flagged passages with each pattern's fix from `ai_patterns.md`, under these rules:

1. **Preserve technical accuracy.** Every number, statistic, p-value, confidence interval, and
   clinical fact must remain identical.
2. **Preserve citations.** Never add, remove, or relocate a citation.
3. **Keep the formal academic register** of an experienced radiologist writing for peers in a
   top-tier journal. Never make the text casual or conversational.
4. **Keep domain-specific terminology intact.** "Convolutional neural network," "apparent diffusion
   coefficient," "Fleiss' kappa" stay as-is.
5. **Never introduce new claims, remove existing ones, or change a sentence's meaning** — rephrase,
   never reinterpret. If a passage cannot be fixed without changing its meaning, leave it and flag
   it for the user.
6. **Use active voice** where natural: "We analyzed" rather than "Analysis was performed."
7. **Vary sentence structure.** Mix short declarative sentences (8-12 words) with longer ones
   (25-35 words). A de-AI pass tends to *flatten* rhythm — it shortens the long sentences and pads
   the short ones toward a comfortable middle, which is itself a tell.
   `scripts/check_sentence_variety.py` verifies this rule in Phase 4.
8. **Thin out antithesis and cleft constructions (Pattern 27, the M2 heuristic).** For each "X
   rather than Y", "not X but Y" or "X, not Y", apply the negative-form test: delete the negative
   half and rewrite the clause in the positive. If a fact disappears, the contrast was functional —
   keep it; if nothing disappears, it was decoration — cut it. Judge by the manuscript's overall
   rate, not instance by instance, and keep two or three for emphasis. Rewrite clefts ("What … is
   …", "It is … that …") in plain subject-verb order ("What matters is X" → "X matters").
   `scripts/check_rhetorical_density.py` (in `/self-review`) measures this in Phase 4.

**Output:** Present the rewritten text with changes highlighted using diff format or tracked changes.

### Phase 4: Verify

**Keep the pre-rewrite text.** Before editing in place, copy the original somewhere the fidelity
check can read it (`cp manuscript.md /tmp/pre_humanize.md`). Without it Phase 4 can only re-scan
for patterns — it cannot tell whether the rewrite preserved numbers and citations.

Run both deterministic checks, then re-scan the rewritten text using the same 27 patterns.

```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/check_rewrite_fidelity.py" \
    --before /tmp/pre_humanize.md --after manuscript.md \
    --out qc/rewrite_fidelity.json --strict
python3 "${CLAUDE_SKILL_DIR}/scripts/check_sentence_variety.py" \
    --manuscript manuscript.md --out qc/sentence_variety.json
```

`NUMBER_DRIFT`, `NUMBER_REASSIGNED`, `CITATION_DROP` or `CITATION_MOVED` means the rewrite broke an
invariant — revert that passage, redo it, and flag it for the user. `EDIT_FOOTPRINT_HIGH` is advisory: Patterns 6 and 18 replace whole
paragraphs by design, so a correct pass over an inflated draft can exceed 60% of words changed.
Read the diff and confirm the author's argument survived rather than assuming the percentage is a
defect.

**Known limits:** the fidelity gate does not check an added or removed negation, a number written
in words, a changed unit, or a direction word next to a non-percentage. A clean exit does not
clear these; read the diff for them.

**Output: Verification Report**

```
## Verification Report

| Metric | Before | After |
|--------|--------|-------|
| Total instances | 23 | 4 |
| Density (per 1000 words) | 8.2 | 1.4 |
| HIGH severity patterns | 3 | 0 |
| MEDIUM severity patterns | 5 | 2 |

Remaining issues:
- Pattern 17 (hedging): 2 instances remain -- appropriate for the evidence level.

Verdict: PASS (density < 2.0)
```

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills