diff --git a/docs/research.md b/docs/research.md index eedc7ee..5b83dfd 100644 --- a/docs/research.md +++ b/docs/research.md @@ -682,6 +682,24 @@ passed; its commands, source commit, payload assertions, and outcomes are recorded in the [release checklist](release-checklist.md). The published result is distinct from, rather than inferred from, the local fixture result. +## Human-tone review pattern — CodeSigils/zensical-skill (2026-10-13) + +Reviewed the MIT-licensed +[article-review reference](https://github.com/CodeSigils/zensical-skill/blob/2580e8089c76c4514689c80c2964523255aa200a/zensical/references/article-review.md) +at commit `2580e80`. It is pattern evidence, not a source of Zola behavior: its +useful boundary is an explicit, author-led human-tone pass that characterizes +the draft's existing voice, treats formulaic or generic prose as a +cluster-level observation, and preserves direct reference prose when fast +retrieval is the page's purpose. + +**Adaptation decision (2026-10-13):** Add this boundary in newly written, +Zola-specific language to the existing editorial-review reference. Do not copy +Zensical text or import its generic site/publishing guidance, a de-slop-skill +dependency, phrase bans, a fixed prose rubric, or automated checks. The change +needs no Zola-version research and does not alter routing, fixtures, release +validation, or the source registry; it only improves an already explicit +article-quality review. + **Distribution-gate decision (2026-09-05):** The Codex/Claude Code clean package-install matrix is the authoritative Phase 7 distribution proof because it fetches the public source and verifies the full payload in each target host. diff --git a/docs/roadmap.md b/docs/roadmap.md index 212a2e4..b552b88 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -714,7 +714,10 @@ commit-message check, or add a skill self-version. review. It evaluates evidence/citation traceability, factual qualification, link/source accuracy, readability, and repository-specific editorial rules. It does not impose a language, voice, SEO formula, rhetorical-device quota, - or a generic custom-shortcode catalog. + or a generic custom-shortcode catalog. An explicitly requested human-voice + pass preserves the observed voice and reports only clusters of generic or + performative prose; direct reference writing, load-bearing distinctions, and + authorial judgment remain legitimate. 4. **Disclosure-aware content model.** Extend the content-model reference only when the target repository already has, or the user explicitly requests, an authorship or AI-assistance disclosure convention. The workflow records only diff --git a/docs/vision.md b/docs/vision.md index 3339ba9..5435880 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -345,6 +345,12 @@ review, and run the smallest applicable Zola validation. Git commits, pushes, pull requests, publishing, and changes outside the authorized repository remain separate, explicitly authorized actions. +An explicitly requested human-voice pass is a narrow part of the existing +editorial review: it preserves the observed voice, reports clusters of generic +or performative prose only when repository guidance permits the review, and +keeps direct reference writing where it serves retrieval. It does not create a +house voice, phrase ban, automatic rewrite, or publication gate. + It must not inherit site-specific voice rules, mandated languages, rhetorical quotas, custom shortcode catalogs, author identities, SEO formulas, branch names, signoffs, remote repositories, or bootstrap/clone instructions from an diff --git a/skills/zola/references/editorial-review.md b/skills/zola/references/editorial-review.md index 50848fe..803d7a1 100644 --- a/skills/zola/references/editorial-review.md +++ b/skills/zola/references/editorial-review.md @@ -19,6 +19,36 @@ links whose purpose is unclear in surrounding prose. Apply a language, tone, voice, SEO formula, rhetorical quota, or shortcode rule only when the target repository documents it. +## Optional human-voice pass + +Use this pass only when the user explicitly asks for voice or tone feedback and +the target repository's editorial guidance permits it. First identify the +draft's observed voice traits worth preserving, such as its register, rhythm, +punctuation, or genuine warmth. Improve that voice; do not replace it with a +house style. + +Look for clusters rather than isolated wording: unnecessary scene-setting, +headings or transitions that announce their own significance, emphasis without +new evidence, invented maxims, inflated moral stakes, exhaustive lists of what +something is not, precision that does not affect the reader's decision, or +forced all-or-nothing conclusions. Recommend a more direct statement only +where it preserves the author's meaning, evidence, and useful distinctions. + +Generic documentation-template prose is a concern only when it displaces an +author's observation, reasoning, or relevant reader context. Direct, +conventional prose is often the better choice for reference material and fast +retrieval. Likewise, retain a contrast, measurement, or strong judgment when +it does factual or argumentative work. Do not treat a single phrase as proof, +rewrite quoted or titled language, fabricate personality or experience, or +turn this review into an automatic rewrite or publication gate. + +For an article, field note, narrative technical guide, or explainer, also +consider whether a major transition leaves the reader without context. Suggest +one or two voice-consistent orienting sentences only when a new section changes +the reader's task, system layer, risk, or mode of work and the surrounding +prose does not already make that connection. Do not add connective prose to a +reference page merely to make it warmer. + ## Related review workflows - [Modify/review workflow](../workflows/modify-review.md) for the required diff --git a/tests/scenarios.md b/tests/scenarios.md index 1ed2c93..fd17304 100644 --- a/tests/scenarios.md +++ b/tests/scenarios.md @@ -21,6 +21,7 @@ remains reproducible. The scenario documents its minimal repair proposal. | Prompt | Expected selection result | Expected finding boundary | | --- | --- | --- | | “Review this Zola article for unsupported claims, inaccurate links, and unclear sentences; do not edit it.” | Match `zola`: explicit article-quality review in an existing Zola site. | Report concrete, evidence-based findings with severity, path, evidence, impact, remediation, and validation; do not impose a language/voice quota or invent sources. | +| “Give this Zola field note human-voice feedback, but preserve its technical tone and do not edit it.” | Match `zola`: explicit article-quality review in an existing Zola site. | Characterize the observed voice and report clusters of generic or performative prose only when local editorial guidance permits; keep direct reference prose and load-bearing distinctions, and do not impose a house style or phrase ban. | ## Phase 3 extended debug/build scenarios