oma-academic-writing

---
name: oma-academic-writing
description: Draft and revise academic prose against a rubric, evidence, and
  citation requirements. Use for essays, reports, literature reviews, or
  academic style audits.
---

# Academic Writing: Publication-Grade English Prose

## Scheduling

### Goal
Produce, revise, and audit publication-grade academic English prose so that every output simultaneously satisfies the Sentence Structure Protocol, Verb Protocol, Hedging Protocol, and Anti-AI Compliance Checklist, with every claim mapped to verifiable evidence.

### Intent signature
- "draft this essay / report / executive summary / conclusion / literature review"
- "rewrite this paragraph in academic English"
- "polish this draft to top-band quality" / "revise to match the rubric"
- "run an anti-AI audit on this prose"
- "check sentence structure variety" / "fix monotonous rhythm"
- "the prose sounds AI-generated, make it pass"
- "verify claims against evidence" / "reverse outline this section"

### When to use
- Drafting or revising academic reports, essays, or analysis sections
- Writing executive summaries, conclusions, or literature reviews
- Rewriting AI-sounding prose into natural academic English
- Polishing draft text to achieve top-band rubric quality (HD, A, top-band, etc.)
- Reviewing prose for sentence variety, verb quality, hedging, and anti-AI compliance
- Any task requiring formal academic English output bound by a rubric

### When NOT to use
- Translation tasks → use `oma-translation`
- Source discovery, citation gathering, or scholarly literature search → use `oma-scholar`
- Rubric / assignment-spec parsing and task decomposition → use `oma-pm`
- Code documentation, README, or API reference text → use the relevant domain skill (`oma-frontend`, `oma-backend`, `oma-mobile`, `oma-db`, etc.)
- Informal communication, chat, or marketing copy → no skill needed
- Non-English academic writing → call `oma-translation` for the target language after drafting in English

### Expected inputs
- `mode`: one of `draft` | `revise` | `review`
- Optional `rubric_or_constraint`: assignment brief, rubric file, or word/structure limits (path or inline text); draft-only revision/review does not require a rubric
- `existing_draft`: prior text to revise or audit (path or inline text); required for `revise` and `review`
- `source_data`: available evidence, figures, citations the writer may use
- `target_register`: defaults to formal academic English with American spelling (en-US)

### Expected outputs
- `draft` mode: section heading + drafted prose + Writing Notes (sentence mix, key verbs, anti-AI flags resolved, paragraph lengths) + Claim-Evidence Map
- `revise` mode: original block, revised block, list of specific changes (verb upgrades, structure variation, anti-AI fixes)
- `review` mode: PASS/FAIL Compliance Report across Sentence Structure, Verb Quality, Anti-AI, Specificity, Hedging, Paragraph Clarity, Rhythm/Burstiness, Claim-Evidence Alignment, plus recommended fixes

### Dependencies
- `../_shared/core/anti-ai-prose.md` and `resources/anti-ai-checklist.md`: common diagnostics and academic constraints; load together for prose audits
- `resources/sentence-structure-reference.md`: four sentence types, contextual rhythm guidance, common errors
- `resources/academic-verb-tiers.md`: meaning- and evidence-based verb guidance
- `resources/hedging-guide.md`: calibrated certainty expressions matched to evidence strength
- `../_shared/core/context-loading.md`: task-relevant resource loading
- `../_shared/core/quality-principles.md`: shared quality bar

### Control-flow features
- Mode branching: `draft` vs `revise` vs `review` produce different output formats and pass sequences
- Rubric constraints: quote supplied assignment requirements before applying them; draft-only revision/review can proceed without inventing a rubric
- Citation gap branch: when a claim lacks evidence, weaken or remove rather than fabricate; optionally hand off to `oma-scholar`
- Language branch: non-English target hands off to `oma-translation` after the English pass
- Iterative AUDIT: every fix loops back through the anti-AI checklist before emit

## Structural Flow

### Entry
1. Identify the mode (`draft`, `revise`, `review`) and the rubric source.
2. If assignment constraints were supplied, quote their exact text before applying them. Without a rubric, revise/review the draft using the requested register and evidence; do not invent assignment rules.
3. If revising or reviewing, read the existing draft in full first; if drafting, confirm available source data and citations.
4. Index `resources/` and identify any claims that need a more precise verb or hedge.
5. Apply the literal-first principle before any drafting: prefer direct statement over metaphor and flourish. When a literal phrase is available, use it.

### Scenes
1. **PREPARE**: load rubric, existing draft, source data; record quoted constraints and note claims whose verbs or hedges need attention.
2. **ACQUIRE**: read `resources/sentence-structure-reference.md`, `academic-verb-tiers.md`, and `hedging-guide.md` only for the patterns relevant to the current section.
3. **ACT**: write or revise prose with sentence variety, accurate verb choice, evidence-matched hedging, clear paragraphing, and direct statements. Keep a common verb when it is the clearest accurate choice.
4. **VERIFY**: apply the shared prose diagnostics and academic checklist; use reverse outlining and the Claim-Evidence Map to identify unsupported claims. In review mode, report findings without rewriting the draft.
5. **FINALIZE**: read-aloud test, cohesion check, specificity audit, word-count verification, paragraph-length variation, rhythm check; emit per the mode's output format.

### Transitions
- If a rubric line is ambiguous → quote it back to the user and ask for interpretation; do not infer combined rules.
- If a claim cannot be supported by available evidence → weaken with hedging or remove; if a citation gap is structural, NOTIFY `oma-scholar`.
- If the target language is non-English → finish the English pass, then hand off to `oma-translation`.
- If the same anti-AI flag survives one fix attempt → restructure the surrounding two sentences instead of word-substitution alone.
- If an output mode mismatch is detected (e.g., user asked for review but supplied a fresh prompt) → confirm the mode before producing output.

### Failure and recovery
| Failure | Recovery |
|---------|----------|
| Word count over / under target | Cut filler adverbs and redundant qualifiers, or expand with supporting evidence; re-run audit |
| Repeated syntax obscures the argument | Revise the affected sentences for clarity using shared rhythm guidance; preserve clear sentences |
| Rubric requirement unclear | Quote exact rubric text and ask user; do not combine rules |
| Claim lacks evidence | Add citation, hedge to match weaker evidence, or remove the claim entirely |
| Hedging miscalibrated | Replace double hedges; align hedge strength with `resources/hedging-guide.md` evidence-level table |
| Verb is vague | Name the action, method, result, or evidence only if that makes the claim clearer |
| Repeated paragraph structure hinders progression | Reorganize the affected argument without inserting a paragraph solely to vary length |

### Exit
- Success: every protocol PASSes, the Claim-Evidence Map has no unsupported entries, word count complies, and the mode-specific output format is fully populated.
- Partial success: emit prose with explicit `needs evidence` / `pending citation` markers and report which protocol items remain at risk; flag handoff candidates.
- Failure: report a material blocker such as required source data being unavailable or contradictory supplied constraints. The absence of an optional rubric alone does not block draft-only revision/review.

## Logical Operations

### Actions
| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Read rubric / constraint and quote literal text | `READ` | Rubric file or assignment brief |
| Read existing draft (revise/review modes) | `READ` | Draft file or inline text |
| Index resources for the current section | `READ` | `resources/{anti-ai-checklist,sentence-structure-reference,academic-verb-tiers,hedging-guide}.md` |
| Select sentence mix and evidence-appropriate wording | `SELECT` | Sentence-structure and verb guidance |
| Plan paragraph as Topic-Support-Conclude | `INFER` | Outline notes |
| Draft / revise prose under all four protocols | `WRITE` | Generated prose |
| Audit prose against anti-AI checklist | `VALIDATE` | `resources/anti-ai-checklist.md` |
| Reverse outline + build Claim-Evidence Map | `VALIDATE` | Mapping table |
| Weaken or remove unsupported claims | `WRITE` | Revised claim line |
| Compare original vs revised (revise mode) | `COMPARE` | Diff block |
| Hand off non-English target | `NOTIFY` | `oma-translation` |
| Hand off citation gap | `NOTIFY` | `oma-scholar` |
| Hand off ambiguous rubric / spec | `NOTIFY` | `oma-pm` |
| Emit per mode output format | `WRITE` | Final artifact |
| Report compliance status | `NOTIFY` | PASS/FAIL summary or Writing Notes block |

### Tools and instruments
- `Read` / `Edit` / `Write` for draft and rubric files
- `resources/anti-ai-checklist.md`, `sentence-structure-reference.md`, `academic-verb-tiers.md`, `hedging-guide.md`
- Topic-Support-Conclude paragraph template (inline)
- Claim-Evidence Map (inline 3-column table: Claim / Evidence / Status)
- Output-format blocks per mode (Draft / Revision / Review)

### Canonical workflow path
1. **READ** the draft and any supplied rubric; quote actual assignment constraints and pin their requirements. If no rubric is supplied, use the requested revision/review scope without inventing constraints.
2. **PLAN** each paragraph as Topic-Support-Conclude; identify where evidence strength or a vague claim calls for a more precise verb.
3. **DRAFT** prose with sentence variety, clear verb choice, hedging, and Topic-Support-Conclude structure.
4. **AUDIT** with `../_shared/core/anti-ai-prose.md` and `resources/anti-ai-checklist.md`. Fix supported defects in draft/revise mode; in review mode, quote the passage, identify the defect, and recommend a local fix without a full rewrite or AI-authorship estimate.
5. **REVERSE-OUTLINE** the section and build the Claim-Evidence Map; weaken or remove any unsupported claim.
6. **POLISH** with read-aloud, cohesion, specificity, word-count, rhythm, and paragraph-length-variation checks; emit in the mode's output format.

### Resource scope
| Scope | Resource target |
|-------|-----------------|
| `LOCAL_FS` | Rubric, existing draft, generated prose output |
| `CODEBASE` | `resources/` 4 reference files, `_shared/core/{context-loading,quality-principles}.md` |
| `MEMORY` | Mode, quoted constraints, wording decisions, anti-AI flags resolved, Claim-Evidence Map |

### Preconditions
- A rubric / constraint or an existing draft (or both) is provided.
- The target register is academic English. If the final deliverable is non-English, the user has agreed to a downstream `oma-translation` handoff.
- The source data needed to support claims is available, or unsupported claims are explicitly allowed to be weakened or removed.

### Effects and side effects
- Writes drafted, revised, or reviewed prose to the user's working location (file or inline).
- Does not modify `resources/` reference files.
- Does not fetch external citations; defers to `oma-scholar` when discovery is required.
- May NOTIFY adjacent skills but does not auto-spawn them; user or workflow drives the actual handoff.

### Guardrails
1. Every sentence must be verifiable; never fabricate data, statistics, or citations.
2. Quote supplied rubric constraints before judging compliance. Without a rubric, explain prose/evidence findings against the requested scope rather than inventing assignment criteria.
3. Never combine distinct rules to invent a new constraint; apply rules exactly as written.
4. Choose verbs for their exact meaning and support. Keep common verbs when they are accurate and natural; replace a vague verb only when the new wording states a relevant distinction without inflating the claim.
5. Review repeated structure and sentence length in context. Change rhythm where it improves clarity or emphasis; do not force sentence-type quotas or rewrite clear prose merely to vary it.
6. Match hedge strength to evidence strength per `hedging-guide.md`; never use absolute claim words (`definitely`, `clearly`, `obviously`) outside mathematical facts; never first-person `I think` / `I believe`.
7. Apply common prose diagnostics with the academic checklist's evidence and register exceptions. Vocabulary counts trigger contextual review, not automatic replacement of precise terms.
8. Em dashes ≤ 1 per paragraph; semicolons ≤ 2 per 1000 words; sentence-case headers; no didactic disclaimers (`It is important to note`) or summary phrases (`In summary`, `Overall`).
9. Every claim must map to evidence in the Claim-Evidence Map; weaken or remove unsupported claims rather than emit them.
10. Read aloud before emit; if a sentence does not flow naturally, restructure it.
11. Apply the shared mannered-prose guidance with the academic checklist's literal-statement requirement.

## References
- Common prose diagnostics: `../_shared/core/anti-ai-prose.md` (load with the academic checklist for prose audits)
- Academic audit constraints: `resources/anti-ai-checklist.md`
- Sentence-structure reference: `resources/sentence-structure-reference.md`
- Academic verb tiers: `resources/academic-verb-tiers.md`
- Hedging guide: `resources/hedging-guide.md`
- Shared context loading: `../_shared/core/context-loading.md`
- Shared quality principles: `../_shared/core/quality-principles.md`

More agent context in first-fluke/oh-my-ag

69 other files this repository gives its agents, the first 60 shown.