# Writing guide

Version 32. Use Sol high for manuscript writing unless the author changes this preference. The user only needs to identify a passage and say to follow writing_guide.md. Gather the context yourself.

**Author review before manuscript edits.** Draft the exact proposed manuscript wording in chat first and discuss it with the author. Do not change manuscript prose in the builder or HTML or save a revised manuscript version until the author explicitly confirms the draft. An explicit request to undo an earlier edit authorizes restoring that earlier wording through the versioning workflow.

1. **Read and plan in context.** Read the section heading, its opening, neighboring paragraphs, and any figure or equation needed for the passage. For Paper 2, read paper2.md for context and paper1.md for terminology. Check relevant sources when a technical claim is uncertain. Identify what the section must establish, what the paragraph adds, and what the next sentence needs to make clear.
2. **Connect the task to what it requires.** At a methods-section opening, establish the immediate task and the prerequisite that motivates the next operation. Ask whether the reader can explain why that operation is needed. For example, “Identifying the closed-loop transfer function requires ...” connects identification to the spectra needed for it. “The closed-loop transfer function is identified from ...” states a procedure but can weaken that connection. Preserve the task–prerequisite relation when it already works. A gerund subject such as “Identifying ...” is impersonal and does not need to be made passive. The preference for passive voice must not override explanatory purpose. Use this relation where needed, not the same opening formula in every paragraph. Introduce inputs over subsequent sentences if listing them burdens the opening. At later boundaries, establish a need only when context has not already done so. Keep claims within the method or branch being explained. Avoid a generic roadmap and give only the detail needed to assess or repeat the work, as recommended by the [MIT Communication Lab](https://mitcommlab.mit.edu/broad/commkit/journal-article-methods/).
3. **Develop a connected explanation.** Transitional words and phrases are strongly encouraged. Before drafting the next sentence, identify its relationship to the preceding one and make that relationship visible. Use “additionally” or “also” for a further requirement, “therefore” or “consequently” for a consequence, “however” for a contrast, and “alternatively” for a genuine alternative. Purpose phrases such as “To estimate these spectra” and references such as “Within each window” can connect a new operation to what is already established. Choose the transition for its meaning, not simply for variety. Do not imply causation, contrast, or an alternative that the method does not contain. Carry a specific quantity, operation, or need forward so the connective links identifiable ideas. A new paragraph should also connect to the preceding explanation. Preserve these links when shortening sentences to meet the length guidance. Read consecutive sentences together: if they sound like separate facts, repair the relationship through a transition, reordered information, or a combined sentence. Do not mechanically prefix every sentence with an adverb. Give each point the evidence or equations it needs, and let endings convey a result, interpretation, or next dependency rather than a recap. Let the reasoning determine length and paragraph count. These checks follow [Gopen and Swan](https://www.cs.tufts.edu/comp/150FP/archive/george-gopen/sci.html) and the [Harvard Writing Center](https://writingcenter.fas.harvard.edu/transitions).

Preserve supported facts, qualifications, notation, equations, and relevant attribution. Use the impersonal engineering-paper voice of Paper 1. State methodological choices declaratively, usually with natural passive voice. Avoid first-person phrasing and instructional imperatives, including sentences that introduce symbols with "Let" or "Define". Keep a physical component active when it performs the action. Keep the core subject and verb close. If the subject bundles several technical labels, use an established shorter referent and give the remaining relation after the verb or in the next sentence. Remove redundant labels, but retain distinctions the science needs. Use established engineering terms; define any unfamiliar label that is necessary. Preserve a grammatical “where” continuation that defines symbols after an equation instead of changing it mechanically to “Here”. [Paper 1 paragraphs 22, 52, 122, 130, and 245](../.agent/paper1_paragraphs.json) illustrate useful rhetorical moves, not required templates or transferable engineering claims. Keep the prose clear, with few commas, no semicolons, and no “whose”. Avoid suspended hyphens: write complete terms such as autospectra and cross spectra. Ordinary internal hyphens such as short-time remain acceptable.

For manuscript prose, aim for no more than 25 words per sentence, following [published journal-writing guidance](https://www.cdc.gov/pcd/issues/2018/18_0085.htm). Apply the [first-seven-words check](https://www.bu.edu/teaching-writing/resources/sentence-clarity-characters-and-actions/): the main subject and a meaningful verb should appear by about word seven, apart from a brief necessary introduction. If a long noun phrase delays the verb, use a shorter established subject and move the detail after the verb or into the next sentence. [Digital.gov](https://digital.gov/guides/plain-language/writing/style) recommends unpacking strings of three or more nouns that hide their relationship. Count during review and revise sentences that miss these checks while preserving equations, technical terms, and necessary qualifications.

**Connect the cited contribution to the present analysis.** Before drafting a citation, establish three things from the source: what it found or supplied, which present calculation or choice uses that contribution, and which conditions limit that use. Build the explanation around the local need, the relevant finding or adopted equation, and its use here. These may span neighboring sentences in the order the argument needs. Name the author with the reference number beside the name. The reader must be able to identify the specific contribution being used and why it helps this analysis. State explicitly whether a formula, construction, result, or recommendation is being used, and connect it to the local quantities and operation. Verify that relationship against both equations before calling a formula identical or adopted unchanged. An accurate report of what an author did is insufficient when that connection is missing. Adding “following,” “described by,” or “for this averaging” does not by itself supply the missing relevance.

**Default citation style: numbered by first appearance.** Cite in the text as “Wu and Wang [8]” when the authors are part of the sentence, or as “[8]” otherwise. Use “et al.” for three or more authors. Number the reference list in order of first citation, with each entry in this format: Wu, H., and Wang, X. (2020), “Title,” *Journal*, 8(2), 1034–1049. DOI: 10.1109/JESTPE.2020.2976791. In the builder, write `{citet:key}` for the named form and `{citep:key}` for the bare number. Each entry in `REFS` holds the in-text name, the year and the formatted reference.

**Never cite with a bare reference number.** Every citation states what the source did and how this work uses it. Prefer attribution verbs that match what the source actually contains: “introduced by,” “proposed by,” “presented by,” “discussed in,” “recommended by,” “found that,” or “showed that.” For a very well-known tool, a short attribution such as “presented by [Author] [ref]” is enough. Choose the verb from the verified content of the paper or textbook. Never guess it. Before drafting any attribution, open the source, find the passage, and quote it to the author. If the source cannot be opened, say so and propose no attribution verb. Avoid possessive attributions such as “the estimator of [Author].” Build each citation in one of two ways:
1. **Our work first.** State what is done in this work, then attribute the method with one of the verbs above, for example: “The samples of each window are weighted by the Hann window presented by [Author] [ref].” Explain what the source based it on only when the reader needs it. Omit the explanation for a very well-known tool, such as an established method from before about the 1980s.
2. **Their work first.** State the source's conclusion, meaning what they found or showed, not merely what they did. Then show how this work uses that finding, for example: “[Author] [ref] found that [method] [result]. Therefore, [method] is used here to [purpose].” Report the conclusion only after verifying that the source reaches it.

These are examples, not templates. Choose the pattern that suits the argument.

Avoid generic constructions such as “the method of Bendat and Piersol.” State what the authors actually did in the source, using a precise verb such as “discussed,” “derived,” “showed,” or “recommended” only when supported. When a source finding motivates the present choice, prefer to lead with that finding and follow it with the specific use here. For example: “[Author] [ref] showed that [verified finding]. Therefore, [specific method] is used here to [purpose].” Do not imply that an author introduced or recommended a method merely because the source describes it.
**Explain from what the reader already knows.** Assume an engineering reader has read the preceding manuscript but has not read the cited paper. Source terminology is not automatically familiar: an unexplained term such as “modified periodogram” cannot carry the explanation. If a source term is necessary, explain it briefly through the quantities and operations used here. Otherwise omit it and describe the required operation in established local terms. Map a source's terminology to the manuscript explicitly when the correspondence matters, rather than switching from “windows” to “record sections” without explanation. Keeping the source's meaning takes priority over copying its vocabulary. The reader should understand the calculation without opening the reference.

**Use concise, consistent scientific names.** Prefer established two- or three-word names when they identify the concept clearly. After “Hann-windowed discrete Fourier transforms” has been defined, “Fourier transforms” is a readable reference to the same operation; “the transforms” is too generic. Give the full specification when introducing the operation, then retain extra qualifiers only where needed to distinguish its meaning. Use the same short scientific name consistently instead of inventing synonyms for variety. A clearly defined symbol may also be used when unambiguous. The two- or three-word preference is not a hard limit: preserve a longer established name when shortening it would change or obscure the meaning. Do not attribute the manuscript's particular window choice to a cited source without evidence.

Before using a backward reference such as “this method,” locate its exact antecedent in the current text. Keep notation consistent and identify the relevant equation when needed. An equation number alone does not explain what its output represents. When a generic expression produces the particular quantities used next, make that correspondence clear if the reader would otherwise have to infer it. Keep definitions and their immediate use together so a literature summary does not interrupt the calculation. If a reader reports an undefined quantity, check the actual preceding text: supply a missing definition or repair a distant or ambiguous reference without incorrectly claiming that an existing definition is absent.

When justifying a choice, look for the source's relevant result, discussion, or conclusion. State the specific benefit or finding rather than generic praise such as “useful,” “efficient,” or “accurate.” For a quantitative improvement, verify the metric, value, baseline, and conditions. Include a percentage only when it is supported and relevant. When adopting an equation or definition, identify what it calculates here and link it to the present equation or operation. Do not force a performance claim onto a citation whose contribution is the mathematical relation itself. Preserve the source's established terms and the precise meaning of its wording. Paraphrase ordinary prose, distinguish exact quotations, and respect quotation limits. Use “showed,” “derived,” “recommended,” “introduced,” or “proved” only when verified. Identify adaptations and do not transfer a source's performance guarantees to changed conditions. If the evidence supports only a narrower claim, narrow the wording. If it contributes nothing to this step, omit or relocate the citation rather than inventing a connection.

**Citation examples — structures to adapt, not factual claims.** Bracketed fields below must be replaced with verified information. They are not permission to invent authors, percentages, conclusions, or equation numbers.

- **An equation used for a calculation:** “To calculate [quantity], the deflection relation derived by [Author] [ref] is used. Under [applicable assumptions], this gives Equation [number].” Verify the derivation and compatibility of the assumptions. This tells the reader what is borrowed and what it calculates.
- **A finding that supports a method:** “[Author] [ref] reported a [verified percentage]% reduction in [error metric] relative to [baseline] under [conditions]. Accordingly, [method] is adopted in Equation [number] to [specific purpose].” Use the numerical result only if it supports this choice. If conditions differ, explain the relevant adaptation instead of implying the same improvement here. Omit the percentage when the source supports only a qualitative result.
- **A property used in an adaptation:** “To [specific purpose], [method] is adapted from [Author] [ref], who established [relevant property or finding]. Here, [specific change] gives the update in Equation [number].” Verify both the property and the adaptation. Do not add “Here” mechanically when the connection is already clear.

For example, “Welch [3] averages modified periodograms” only reports an activity. A paragraph motivating spectral averaging should explain the relevant variance result and its role in the present choice. It must also distinguish Welch's averaging rule from any recursive adaptation. Do not import an unrelated result merely to make the citation sound stronger. Explain a need as the reason for choosing a method, not as the cause of a property that the method has regardless. Check that a property borrowed from a source still holds for the equation and initialization used here.

**Five examples from published engineering papers.** These are exact short excerpts, followed by paraphrases of the surrounding explanation. Learn the connection between evidence and application, not every stylistic choice of the source. Retain this guide's impersonal voice. Full metadata and verification records are in [archive_reference.md](../.agent/archive_reference.md). These examples establish how the papers use citations, not whether their predecessors' findings apply to Paper 2.

1. **A reported benefit leads to adoption — Shrestha, Hao, and Bi (2013).** [AEES conference paper, Section 3, PDF p. 6](https://www.aees.org.au/wp-content/uploads/2015/06/3-Shrestha-Bipin-Pounding.pdf): “less or even no iterations are needed in the latter approach (Bi and Hao, 2012)”. The surrounding paragraph compares ground-motion simulation methods, identifies the computational advantage, and then adopts Bi and Hao's method for the earthquake inputs. The citation explains why that method is chosen.
2. **A cited method supplies a quantity needed for the test — Gálmez and Fermandois (2020).** [Frontiers in Built Environment, Section 3.2, p. 6](https://www.frontiersin.org/journals/built-environment/articles/10.3389/fbuil.2020.00134/pdf): “an estimation of the critical delay is obtained with the method proposed by Gao and You (2019).” The authors then give the calculation and use its critical-delay value as a reference for their simulations. The borrowed method has a specific output and purpose.
3. **A borrowed model represents the required physical behavior — Ou et al. (2020).** [Frontiers in Built Environment, p. 4, immediately before Section 3.1](https://www.frontiersin.org/journals/built-environment/articles/10.3389/fbuil.2020.00103/pdf): “In case I, specimen nonlinearity is modeled with a Bouc-Wen-Baber-Noori model proposed by Baber and Wen (1981) and Baber and Noori (1985).” Section 3.1 immediately explains that the model captures pinching and degradation, then presents its equations. Attribution is tied to the behavior represented in the analysis.
4. **A limitation justifies the method selected — Nugroho et al. (2021).** [Journal of Fluid Mechanics, accepted manuscript Section 2.6, p. 8](https://eprints.soton.ac.uk/444123/1/nugroho_et_al_2020.pdf): “In this instance the method of Monty et al. (2011) is preferred due to the aforementioned limitations in making the Clauser estimate.” The preceding discussion explains why the rough-wall measurements make the alternative estimate uncertain. The preferred method is connected to those experimental conditions rather than praised as universally superior.
5. **An existing analysis is adopted to answer a new question — Rees (2011).** [Transport in Porous Media, Section 1, p. 460](https://people.bath.ac.uk/ensdasr/PAPERS/TOAPPEAR/ReesChannel-personal.pdf): “we adopt the method used by Gill (1969) in order to study the effect of local thermal nonequilibrium”. The next sentence identifies Gill's energy analysis and stability finding. Rees extends that analysis to a changed thermal assumption. The reader can see both the borrowed reasoning and the question it will address.

Before using a citation, open and read the actual paper or PDF. Check its abstract, introduction, and conclusion, then inspect the relevant derivation, method, or results. Prefer a supporting quotation from those overview sections when available, but verify technical details in the body. For a book, read the relevant chapter. Trace references to the original source of the particular method or result and read that source before crediting it. Do not claim someone was first unless this is verified. Search snippets and secondary summaries are discovery aids, not verification. If the original is unavailable or does not support the claim, flag the citation as unverified and revise or withhold the claim.

For each source cited in a passage being written or reviewed, add or verify its evidence in [archive_reference.md](../.agent/archive_reference.md): author, title, year, DOI or source link, PDF link or local path, verification date, and sections actually read. Include a short exact quotation with the printed page and section, preferably from the abstract, introduction, or conclusion. Record the specific claim it supports, its role in the manuscript, relevant equation or result, limits, and the origin check. Mark omitted words explicitly and verify quotations against the PDF rather than trusting OCR. Keep quotations within permitted excerpt lengths. The archive stores evidence only. All writing instructions remain in this file.

Reread the preceding context, revision, and following paragraph together. Apply the checks to every sentence in the target, including wording retained from the original. Preserve mathematical definitions and their meaning without treating the surrounding prose as fixed unless the author explicitly protects it. Check whether each new point arrives after its need is clear, each paragraph advances one point, and sentence endings carry the intended emphasis. Compare the original and revision for lost explanations of purpose or prerequisites. Losing such a link is a regression even when the new sentence is grammatical or more passive. Retain the original when the alternative gives no clear improvement. Remove repeated phrases and restated relations while retaining necessary causal links. Check technical roles, symbol definitions, and qualifications. Match each citation to its archive evidence and confirm both what the source establishes and why it belongs here. Preserve approved wording, including grammatical equation continuations, when it remains clear and correct.

Return the proposed passage in chat for author review. After the author confirms it, edit the manuscript through its versioning workflow. Before editing manuscript HTML, check its review-workflow flag and follow the version instructions in paper2.md and REVIEW_WORKFLOW.md. If the flag is absent, follow paper2.md's instruction to ask before editing. For a controlled trial, use its supplied context and output format.

**Optional independent review**

After presenting the revised passage, ask: “Would you like an independent review by a fresh GPT-6 Sol agent at high effort?” Complete the normal self-review before presenting it. The independent review is optional and does not delay delivery. Run it only when requested or accepted. If it was already requested, perform it without asking again. Do not repeat the offer for a revision the author has already declined to review. Adding or discussing this procedure alone does not request a review.

1. **Use a separate reviewer.** Spawn a new subagent with `model: "gpt-6-sol"`, `reasoning_effort: "high"`, and `fork_turns: "none"`. Do not reuse the writer or an earlier trial agent. This separates the drafting context, but is not a claim of statistical independence or guaranteed correctness. If that model is unavailable, report this rather than silently substituting another model.
2. **Supply a fixed review package.** Include the complete proposed passage and original passage, clearly labeled. Supply the author's intended message and explicit constraints, the section title and opening, preceding and following paragraphs, and any earlier definitions needed to check repetition. Include relevant figures, captions, equations, parameter settings, and the mapping from reference numbers to sources. Supply the current `writing_guide.md`, `paper1.md`, `paper2.md`, and relevant source or implementation paths. Preserve the latest user edits in this package. Equations and mathematical meanings are protected when requested, but prose introducing symbols remains editable unless explicitly protected. Do not pass the writer's rationale, self-review, previous trial drafts, reviewer verdicts, or suggested scores. Do not tell the reviewer which candidate is preferred.
3. **Read in context before judging.** The reviewer first reads the proposed passage with its neighbors to assess whether the explanation can be followed. It then compares the original and revision for changed or missing meanings. It reads the supplied guidance and checks each sentence, including retained wording. Relevant Paper 1 examples may inform voice and transitions, but cannot supply unsupported claims about Paper 2.
4. **Check meaning and evidence.** Verify technical roles, definitions, qualifications, numerical settings, equation preservation, and consistency with the relevant implementation. Check whether the reader understands why each operation is introduced. For every citation, identify the exact finding or relation borrowed and the present calculation or choice that uses it. Reject an accurate but disconnected source summary. Verify the author, contribution, conditions, and claimed application against the actual original document and `archive_reference.md`. Do not treat the archive or a search snippet as independent source verification. Report inaccessible sources or unsupported claims as unresolved. Return any needed archive corrections to the main agent without editing files.
5. **Check the complete prose.** Assess section purpose, progression between sentences, transitions, endings, repetition across neighboring paragraphs, and unfamiliar word combinations. Read each adjacent sentence pair and each paragraph boundary. Check both whether the relationship is clear and whether the chosen transition expresses it accurately. Flag disconnected sequences even when each sentence is individually correct. For each imported technical term, verify a local explanation or an earlier definition. Check that repeated scientific names remain recognizable and consistent: prefer concise names such as “Fourier transforms,” reject vague replacements such as “the transforms,” and retain qualifiers only when the distinction is needed. For each backward reference, identify the actual antecedent and confirm its meaning and notation. Ask whether the calculation and the use of the citation can be understood without reading the cited paper. Apply this guide's voice, punctuation, sentence-length, early-verb, and noun-string checks. Count each inline mathematical expression as one token for the prose word count and exclude reference numbers. Record any justified exception instead of splitting a sentence mechanically. Do not force the original length, introduce new claims, or invent faults to produce a longer review.
6. **Return an actionable review.** Give a verdict of “ready,” “needs revision,” or “cannot fully verify.” List required corrections separately from optional preferences and unresolved evidence. For each finding, quote the exact affected wording, explain the reader's difficulty or technical error, identify the relevant rule or source, and suggest the smallest useful correction. Report which checks passed and which sources were actually opened. Do not return only a score, a blanket approval, or an unsolicited full rewrite. The reviewer must not edit files or create trial artifacts.
7. **Resolve and report.** The main agent checks each finding against the passage and evidence before accepting it. Correct supported problems within the authorized scope and return the revised passage with a brief account of material changes and remaining uncertainties. If required corrections change the passage, this review includes one fresh Sol-high recheck using the same procedure and the corrected passage, without earlier verdicts. If problems remain after that recheck, report them rather than claiming success or starting an unlimited cycle. Apply manuscript changes only when authorized and through the existing version workflow. Keep this procedure in `writing_guide.md` and citation evidence in `archive_reference.md`.

When refining this guide, freeze a target passage with its heading, neighbors, equations, and technical facts. Give each fresh Sol-high writer the current guide and that same context, without earlier drafts or critiques. Compare the full candidate with the original for technical accuracy, section purpose, pre-verb load, sentence length, noun strings, repetition, and flow. Do not rely on the agent's self-review alone. Record a concrete failure, change as few guide words as possible, and repeat with a new writer. Keep trial agents read-only and apply accepted manuscript wording only through the version workflow.