prose-style-guide

Before and during chapter writing, autonomously maintain a readable academic style for reviewers and general readers. Prevents exposure of internal identifiers, ensures first-use definitions of techni

SKILL.md

GitHub

Prose Style Guide Skill

Purpose

This skill provides principles for AI to autonomously maintain readable academic prose when writing manuscript chapters (docs/<paper-id>/chapters/). Unlike post-hoc checks (reviewer-readability-check), this skill activates before and during writing to prevent problems from occurring.

Reader level: If the research plan defines the intended readers, prioritize that definition. Next, follow the expectations of the target venue. If neither specifies readers, assume readers with general university-level reading ability but no specialist education in the paper's field. For papers that address practical application, include practitioners in this audience. Do not assume that practitioners know the field's theories or research methods.

Explain technical terms and research methods in plain language when needed so non-specialists can follow the argument and its practical implications. At the same time, retain evidence, citations, methods, and qualifications required for specialist review.

Trigger Timings

  • Before starting to write a chapter file (confirm principles)
  • During writing when uncertain about style (reference as needed)
  • When the author points out "hard to understand" or "readers won't follow" (record as friction signal)

Principles

  • Readers do not know internal identifiers: Do not expose design-memo IDs (D2, T-4, CA-10) or research-program numbers (種①, seed 4) in the manuscript. Replace with language readers can understand
  • Match explanations to non-specialists while retaining reviewable grounds: Simplify wording and explanatory order, not qualifications, falsifiability, sources, or methodological conditions. Add the explanation needed to reach specialist content rather than simplifying the content itself
  • Define technical terms at first use: Make the text understandable even to readers unfamiliar with the field
  • Keep sentences short: Place subjects and predicates close together; avoid chains of modifying clauses
  • Avoid chains of abstract nouns: Write with concrete verbs and nouns
  • Separate quotation from interpretation: After a quotation, explain its meaning in the author's own words
  • State the conclusion at the start of paragraphs: Allow readers to anticipate the paragraph's purpose

Style Checklist

1. Eliminating Internal Identifiers

Bad example:

However, D2 is a secondary review, and this paper does not rely on it as a sole foundation.

Timing of removal is deferred to seed 4.

Good example:

However, the source referenced here is a secondary review, and this paper does not rely on it as a sole foundation.

When to remove the scaffold is outside the scope of this paper.

Targets: Literature IDs (A1–F6), task IDs (T-1 to T-6), counter-argument IDs (CA-1 to CA-13), research-program seed numbers (種①, 種④, seed 1, etc.), program-map component numbers, and other design-memo or research-program identifiers. Do not treat them as ordinary nouns. Do not introduce them with a definition in the manuscript; remove them from prose.

2. Defining Technical Terms at First Use

Bad example:

This is a coupling-constitution fallacy.

Good example:

The fact that a person uses a tool (coupling) does not mean the tool constitutes part of the mind (constitution) — these are separate claims.

Targets: Philosophical terms (coupling, constitution, internalism, externalism, etc.), cognitive science terms (offloading, scaffolding, etc.), and other terms readers may not know

3. Sentence Conciseness

Bad example:

Adams and Aizawa (2001) argue that from the fact that tools and people are coupled, it does not follow that tools are part of the mind.

Good example:

Adams and Aizawa (2001) argue that the mere fact that a person uses a tool does not mean the tool is part of the mind.

Targets: Sentences over 40 words, sentences with two or more consecutive modifying clauses

4. Concretizing Abstract Nouns

Bad example:

The philosophical formalization of the legitimacy of externalization

Good example:

The philosophical grounds for recognizing externalization as legitimate

Targets: Expressions with consecutive abstract nouns ("-ity", "-tion", "-ism", etc.)

5. Separating Quotation from Interpretation

Bad example:

"The brevity of our life and the multitude of things we are now obliged to know do not permit us to do all of ourselves" — this is an explicit formulation of the necessity of externalization.

Good example:

"The brevity of our life and the multitude of things we are now obliged to know do not permit us to do all of ourselves." This sentence explicitly states that externalization is necessary.

Targets: Expressions connecting quotations to interpretations with dashes (——)

6. Stating Conclusions at Paragraph Start

Bad example:

What Blair shows is that responses to anxiety turned not only to memory enhancement but to external devices.

Good example:

Responses to anxiety turned not only to memory enhancement but to external devices.

Targets: Paragraphs beginning with "What X shows is..." (delays the subject)

7. Matching the Reader Level

  • Are technical terms explained at first use in language understandable to readers outside the field?
  • Is the reason for moving from one statement to the next conclusion explicit?
  • When the paper addresses practical application, does it show how theoretical concepts connect to practical judgments or actions?
  • Has any qualification, counterargument, evidence, or methodological caution been dropped merely to make the prose easier?

Do not decide readability solely by a fixed readability score or sentence length. Prioritize whether readers receive the necessary premises and can trace the argument.

8. Metaphors Readable in Their Source Domain

Do not use a word that readers can understand entirely in the metaphor's source domain (accounting, exchange, medicine, machinery, and the like) unless the paper actually argues in that domain. Replace it with observable wording: what can happen, what to check, how much work is required.

Bad example:

Leaving the frame in place incurs a cost: the frame may answer on the user's behalf. If you choose to keep it, that cost is the price you must accept first.

Good example:

If the frame remains, it may answer on the user's behalf. If you choose to keep it, acknowledge these outcomes in advance.

Targets: cost, price, trade-off, debt, side effect, diagnosis, breakdown, and their equivalents. Terms defined as field-specific technical vocabulary, and used for that field, are out of scope.

Procedure

[Step 1: Confirm principles before writing] → [Step 2: Reference as needed during writing] → [Step 3: Revise when author points out issues] → [Step 4: Record friction signals]

Step 1: Confirm Principles Before Writing

Before starting to write a chapter:

  1. Check research-plan.md, venue notes, and the paper overview for the primary readers and whether practical application is in scope
  2. If no reader level is specified, use this skill's default reader level
  3. State in one sentence what specialist knowledge may be assumed of the reader
  4. Review the Style Checklist and identify technical terms introduced in the chapter and places where practical meaning needs explanation
  5. Check domain-concepts.md for the same surface word appearing in two or more concept entries. If it does, use distinct, observable wording in the manuscript. If a judgment label is kept (for example, operating effort as a stop reason), do not reuse it for a different concept such as the downsides of leaving a scaffold in place

Step 2: Reference as Needed During Writing

When uncertain about style during writing, reference the relevant principle.

Step 3: Revise When Author Points Out Issues

When the author points out "hard to understand" or "readers won't follow", revise the relevant passage according to the principles.

Step 4: Record Friction Signals

Record the author's feedback as a friction signal following the friction-driven-skill-improvement skill.

Related Skills

  • Post-hoc check: reviewer-readability-check (mechanical detection of internal identifiers)
  • Terminology consistency: terminology-consistency (standardizing term usage)
  • Sensitive expressions: sensitive-expression-guard (detecting absolute quantifiers, deficit model vocabulary)
  • Friction signals: friction-driven-skill-improvement (filing improvement proposals)

Outputs

  • Revised manuscript (docs/<paper-id>/chapters/)
  • Friction signal log (docs/<paper-id>/design/logs/friction-log.md)