# Writing Judgment Framework

A cognitive framework for making writing decisions. Complements the procedural `writing_quality_check.md` with judgment heuristics.

## The Clarity Test

For every paragraph, ask: "If I remove this paragraph, does the paper still make sense?"

- **Yes, and nothing is lost** → Delete the paragraph
- **Yes, but context is lost** → Keep, but it's a supporting paragraph — keep it short
- **No, the argument breaks** → This is a load-bearing paragraph — it deserves the most careful writing

**Judgment heuristic**: Most AI-generated academic text fails the clarity test because every paragraph is given equal weight. Vary your investment: load-bearing paragraphs get multiple drafts; supporting paragraphs get one.

## The Reader's Journey

Academic writing is a guided tour. At any point, the reader should be able to answer:

1. **Where am I?** (Section structure, signposting)
2. **Why am I here?** (Connection to the research question)
3. **What should I take away?** (The point of this section)
4. **Where am I going next?** (Transition logic)

If ANY of these is unclear, the writing needs revision — regardless of how accurate the content is.

## Discipline-Specific Voice

| Discipline | Typical Voice | What Makes It Credible |
|-----------|--------------|----------------------|
| Hard sciences | Impersonal, passive, hedged | Precision of measurement and method |
| Social sciences | Semi-personal, active, qualified | Transparency about limitations |
| Humanities | Personal, argumentative, interpretive | Depth of engagement with sources |
| Engineering | Direct, specification-oriented | Reproducibility of results |
| Medical | Structured, protocol-focused | Adherence to reporting guidelines |

**Judgment heuristic**: If you're writing "We argue that..." in a physics paper or "The data indicates..." in a humanities essay, you've adopted the wrong voice for the discipline.

## The "So What" Hierarchy for Sections

| Section | The reader's "So What?" | Your job |
|---------|------------------------|----------|
| Introduction | Why should I care about this topic? | Hook with a real-world consequence or knowledge gap |
| Literature Review | What's missing from what we know? | Build to the gap, don't just summarize |
| Methodology | Can I trust these results? | Show rigor, acknowledge limitations upfront |
| Results | What did you actually find? | Lead with the finding, not the statistical test |
| Discussion | What does this mean for the field? | Connect back to the gap; state the delta clearly |
| Conclusion | What should I remember? | One sentence that captures the contribution |

## Revision Decision Matrix

When revising based on reviewer feedback:

| Reviewer Says | Your Options | Decision Framework |
|--------------|-------------|-------------------|
| "Unclear" | Rewrite for clarity | Always do this — it costs nothing |
| "Missing reference" | Add if relevant | Check if it genuinely fills a gap or is self-citation promotion |
| "Wrong method" | Evaluate, justify, or change | If your method is defensible, justify with evidence; if not, this may require Major changes |
| "Not novel enough" | Strengthen framing | Reframe contribution, don't add unnecessary analyses |
| "Too long" | Cut ruthlessly | Apply the Clarity Test paragraph by paragraph |
