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:

Where am I? (Section structure, signposting)
Why am I here? (Connection to the research question)
What should I take away? (The point of this section)
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