| name | prose-style-review |
| description | Review and improve gllvmTMB prose in README files, vignettes, pkgdown articles, after-task reports, release notes, design docs, and manuscript-style text for clarity, concrete claims, stable terminology, citations, and reader fit. |
Prose Style Review
Use this skill for substantial prose, especially public documentation
and after-task reports. It is a compact gllvmTMB adaptation of
the upstream prose-style discipline; do not vendor external
prose-style projects.
Reader First
Before editing, name the reader:
- applied ecology, evolution, or environmental-science user;
- adjacent-field graduate student;
- statistical method developer;
- R package contributor;
- reviewer of a paper, grant, or release.
Write for that reader's current knowledge. Explain a term when the
reader would otherwise have to infer it from context.
Review Checklist
- Lead with purpose before mechanics.
- For model docs, pair symbolic equation, R syntax, and
interpretation. The 5-row alignment table from the
add-simulation-test skill is the canonical form when an article
exposes the multi-tier covariance structure.
- Replace vague nouns with concrete functions, parameters, files,
equations, checks, or numerical results.
- Use active voice when the actor matters.
- Delete filler phrases such as "it is important to note that",
"in order to", "various factors", "significant improvements",
and "leverages".
- Do not over-bullet. Use bullets for genuine lists; use prose for
one or two connected ideas.
- Keep terms stable:
Sigma, Lambda, psi / Psi,
latent(), unique(), indep(), dep(), phylo_*(),
spatial_*(), animal_*(), meta_V(value, V = V),
traits(). meta_known_V() is only a deprecated alias. The
decomposition mode is latent + unique paired
(Sigma = Lambda Lambda^T + Psi, with Psi = diag(psi^2));
standalone latent is the no-residual subset and standalone
unique is the marginal/independent mode -- describe these
correctly.
Notation convention (per decisions.md, 2026-05-12):
the unique-variance diagonal in math is always Psi / psi,
never U, S, or s. The string "two-U" is OK as a task label / function
nickname (it matches existing function names and file paths),
but in user-facing math prose write Sigma_phy = Lambda_phy Lambda_phy^T + Psi_phy, Omega = Sigma_phy + Sigma_non,
etc. A diag(U), diag(S), or diag(s) in roxygen or article
body is a drift to flag unless it is explicitly historical.
- Two-shape data framing: teach long
(
gllvmTMB(value ~ ..., data = df_long, ...)) and wide
data-frame formula
(gllvmTMB(traits(...) ~ ..., data = df_wide, ...)). The
legacy matrix wrapper gllvmTMB_wide(Y, ...) remains exported
as a soft-deprecated migration path and should not be the
primary user-facing route.
- Support factual, statistical, or literature claims with citations,
local evidence, check outputs, or a clear "design assumption" label.
- For tutorials and error-message docs, tell the reader what to do
next when a model or syntax is unsupported.
- Define each technical term at first use. The 4 x 5 keyword grid
(correlation source x mode) is the most-glossed concept; treat
it as new every time.
- End paragraphs with the point the reader should carry forward.
- Avoid repeated sentence openings and repeated paragraph-summary
closers.
Role Guidance
- Pat checks whether an applied user can follow the prose, run the
example, and interpret the output.
- Rose checks stale wording, unsupported claims, duplicated summaries,
and contradictions with code, docs, tests, roadmap, or after-task
notes.
- Documentation writers (Boole + Pat in the team table) check
examples, headings, equations, citations, and pkgdown navigation as
one learning path.
Output
For a review-only task, return:
- blocking confusion;
- important friction;
- small polish;
- suggested wording for the highest-impact fixes.
For an edit task, make the smallest prose edits that fix the problem,
then record what changed in the check log or after-task report when
the task is meaningful.
