diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 69db026..2438194 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "writing-method", - "version": "0.4.1", + "version": "0.5.0", "description": "Reader-oriented writing, documentation workflows, local PDF delivery and narrated tutorial videos, plus an experimental story-writing family kept separate from them.", "author": { "name": "Peter Hense" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 71e0061..4b87233 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "writing-method", - "version": "0.4.1", + "version": "0.5.0", "description": "Reader-oriented writing, documentation workflows, local PDF delivery and narrated tutorial videos, plus an experimental story-writing family kept separate from them.", "author": { "name": "Peter Hense" diff --git a/FEATURES.md b/FEATURES.md index 20b1317..299d998 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -15,11 +15,11 @@ This inventory records implemented, changed, and historically removed capabiliti - Summary: One local PDF from Markdown with a single-sided layout for short documents and a book layout for long manuals. - Related backlog: `WM-002` - + ## `F-003` Narrated tutorial videos - Status: available -- Summary: Script, production and review skills with a project template and tools for a presentation video voiced by a speech provider. The production playbook passed two content reviews; it has not been rehearsed end to end and no person has done the listening check. +- Summary: Script, production and review skills with a project template and tools for a presentation video voiced by a speech provider. The production playbook has a Ready content review after five rounds and one end-to-end rehearsal on one machine with Azure speech, including the owner's listening check. The render-machine and ElevenLabs branches and a story video have never been executed. - Related backlog: `WM-001` @@ -35,3 +35,10 @@ This inventory records implemented, changed, and historically removed capabiliti - Status: available - Summary: An accepted chapter becomes a video script, verbatim or as a listening edition that leaves the manuscript unchanged; the form skills voice and render it without restyling. No story video has been produced. - Related backlog: `WM-004` + + +## `F-006` Writing rule #1: natural prose + +- Status: available +- Summary: One rule file lists the patterns by which readers recognize machine-written text, the reasons, what to write instead and the scope by writing mode. Every documentation, didactic, video-script and story skill refers to it; a short standalone text loads human-prose-drafting. Carried by skills; produced text is not measured. +- Related backlog: `WM-005` diff --git a/README.md b/README.md index e8756aa..4e61c8b 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ --- type: reference audience: Authors and maintainers familiar with their coding assistant and Git -version: 0.4.1 +version: 0.5.0 --- # Writing Method @@ -9,6 +9,12 @@ Writing Method provides reader-oriented writing, documentation planning, review, The three repositories remain under `phense`, share the `agent-methods` topic and have independent Issues and pull requests. Report a writing behavior here, an engineering behavior in Engineering Method, and shared adapter/state/playbook behavior in Method Core. +## Writing rule #1: natural prose + +No text written with this method may read as machine-written. The rule comes before every other writing rule and covers replies, documentation, messages, video narration and story manuscript. [Writing rule #1](shared/policies/natural-prose.md) explains why readers recognize such text, lists the patterns in five groups (staged insight, even rhythm, inflation in place of fact, formatting as decoration, leftovers from a chat) and states what to write instead. Every documentation, didactic, video-script and story skill refers to it, the story skills through the story rules. The skills from the shared core (playbooks, code review, backlog, verification, worktrees, parallel agents) do not. For a story, the voice sheet decides first and the rule applies where the sheet is silent. + +The rule is carried by the skills. A reply for which no skill of this method loads is not reached by it, and whether a host follows it is not measured. + ## Included skills | Purpose | Skills | @@ -75,7 +81,7 @@ The rule set is chosen for each piece of text, not for the session or the subjec | Text | Mode | Governed by | |---|---|---| -| Story prose, in-world text such as a letter or manual inside the story, afterword and blurb, a listening edition, the narration of a story video | manuscript | The story's voice sheet, then the story rules. Nothing from the documentation skills. | +| Story prose, in-world text such as a letter or manual inside the story, afterword and blurb, a listening edition, the narration of a story video | manuscript | The story's voice sheet, then the story rules, which include writing rule #1 for prose. Nothing from the documentation skills. | | Any other note in a story vault or study vault: brief, world entry, chapter card, review, study note | working note | The story skills. Plain notes without the story's voice and without didactic structure. | | Everything else: every reply to you, a vault's `README.md`, documentation, tutorial videos | reader-oriented | The rules of the sections above, unchanged | @@ -124,7 +130,7 @@ claude plugin install writing-method@writing-method For a session-scoped Claude test use `claude --plugin-dir /absolute/path/to/writing-method`. For OpenCode, run `python3 scripts/install-opencode --check` from this checkout, inspect the proposed path, then repeat without `--check`. It installs an owned `writing-method.js` loader pointing to this retained directory. Gemini support is deferred until its adapter is verified. -Restart the assistant session after installation and inspect its plugin inventory for `writing-method` 0.4.1. An installed listing proves discovery; a live authoring request is separate behavior evidence. With both methods installed, use the invoking method's namespace for shared support, such as `writing-method:playbook-authoring`, and run one copy. +Restart the assistant session after installation and inspect its plugin inventory for `writing-method` 0.5.0. An installed listing proves discovery; a live authoring request is separate behavior evidence. With both methods installed, use the invoking method's namespace for shared support, such as `writing-method:playbook-authoring`, and run one copy. ## Project state and updates diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index ceeddec..31e6604 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -30,9 +30,10 @@ Revision: `9862685f575c65a8247f90369951df1b3416e3d6` Copyright (c) 2025 Siqi Chen -Reframed the after-the-fact rewrite procedure as drafting-time constraints for medium and large documentation, condensed the 25 patterns into constraint groups, removed pasted-text and voice-matching modes, and added the chunk check and documentation voice rules. +Reframed the after-the-fact rewrite procedure as drafting-time constraints, condensed the 25 patterns into five groups and moved them into a rule file that applies to every text, extended them from further sources named in that file, removed pasted-text and voice-matching modes, and added the delivery check, the scope by writing mode and the documentation voice rules. - `SKILL.md` -> `skills/human-prose-drafting/SKILL.md`: adapted +- `SKILL.md` -> `shared/policies/natural-prose.md`: adapted MIT License diff --git a/docs/specs/WM-001-presentation-video/playbook-review.md b/docs/specs/WM-001-presentation-video/playbook-review.md index c6d510f..9230d9b 100644 --- a/docs/specs/WM-001-presentation-video/playbook-review.md +++ b/docs/specs/WM-001-presentation-video/playbook-review.md @@ -205,8 +205,74 @@ Independent, read-only, same method as the second review. PS-01 to PS-14: all re PT-01 to PT-07 were applied as the exact edits above in the following revision. That revision has not been reviewed again. -## State after three reviews - -- Content review: 43 findings in three rounds (1 Critical, 20 Important, 22 Minor), all applied. The last applied edits are unreviewed, so no `Ready` verdict exists. -- Rehearsal: stale and partial. The record in `rehearsal.md` describes the earlier playbook text. Never executed in any version: gate 2 (P9), P8b, delivery (P10 to P11), R1 to R4 and R6, the ElevenLabs branch of P4, the take rule, a per-scene correction and a story video. -- The criterion "rehearsed once end to end on the sample video" is not met. It needs a machine with `ffmpeg`, a configured speech provider and a person for the listening check. +## Fourth review at `1a80caa` + +- Reviewers: two independent assistant reviewers with different tasks (the + whole procedure; agreement of the playbook with the tools and the edits + since the third review). Each finding was checked again by a further + independent reviewer who tried to refute it. Read-only; no provider call, no + render. +- Verdict at `1a80caa`: Changes required. 15 findings, all confirmed: 4 + Important (two describe the same gap), 11 Minor. + +| ID | Severity | Finding | Change applied | +|---|---|---|---| +| QA-01, QB-01 | Important | R4 checked for a running render only on the authoring machine, gave no action for a listed process and deleted the outputs before the check | R4 checks the machine that rendered, waits, has a limit and an escalation, and deletes afterwards | +| QA-02 | Important | R3 said the tool chooses the better take; it uses the highest word match, so a take that drops a short line can win over a complete one | R3 moves the rejected take to `takes/superseded/` first, and the printed line must name the new take | +| QB-02 | Important | A run of `split_takes.py` without a scene cuts every scene and removes every read-back word file, so a one-line correction transcribed the whole video again | Correction and interruption name `` | +| QA-03 | Minor | The removal of word files by `split_takes.py` had no test and no evidence for the operator | Unit test `TakeReplacement`; `ls` check before P4 | +| QA-04 | Minor | R5 did not lead back through P7 to P8, so an old joined file could be measured again | R5 states the return path | +| QA-05, QB-06 | Minor | P10b and Completion had no first-delivery case; P10b could be run twice | Guard on `.new`, first-delivery text, escalation | +| QA-06 | Minor | The order of pronunciation attempts existed only in the skill | P1 states the order and the stop | +| QB-03 | Minor | "No step deletes working files" contradicted the next sentence and R4 | Reworded | +| QB-04 | Minor | A file without sound ended `measure.py` with a Python error | `measure.py` prints `has no sound track or cannot be read` and `FAILED`; R5 recognizes it | +| QB-05 | Minor | A render that fails for another reason had no stop | Second failure: P6b once, then escalate | +| QB-07 | Minor | R3 quoted no literal message; two rejections and the missing word file were not listed | Literal messages; P2b names the missing word file | +| QB-08 | Minor | Resuming P5 as allowed reset every inspection mark | Interruption text names the per-scene command | +| QB-09 | Minor | `takes/superseded/` was not ignored | `.gitignore` | + +These edits are again unreviewed. Checked by execution after the edits: the +unit tests, and `measure.py file` on a one-second file without sound +(`has no sound track or cannot be read`, `FAILED`, exit 1). + +## Fifth review at `7196174` + +- Reviewer: one independent assistant reviewer; each finding checked again by + a further independent reviewer. Read-only; unit tests run (82, OK). +- All 15 findings of the fourth review are resolved and agree with the tool + source. Verdict at `7196174`: Changes required, 2 Important, 3 Minor, all + in text changed by the fourth round. + +| ID | Severity | Finding | Change applied | +|---|---|---|---| +| R5-01 | Important | The order of pronunciation attempts did not say that an entry takes effect through one field only; a language mark added beside a phonetic entry changes nothing and no tool reports it | P1 says to remove the earlier field and names the evidence (`new`) | +| R5-02 | Important | `split_takes.py` wrote the manifest once after all scenes, so a later rejected scene left earlier scenes cut on disk and absent from the manifest | The tool writes the manifest after every scene | +| R5-03 | Minor | The correction bullet named the cut before the new take | Reordered; prompt and transcription named | +| R5-04 | Minor | Three rejection messages do not name the take, so "the rejected take" could not be identified | R3 moves every earlier take of the scene; numbering counts `takes/superseded/` | +| R5-05 | Minor | `out/measure.json` is not written when the file cannot be read | Preserve list says so | + +Open observation, not verified: on Linux `pgrep -fl` may list the shell that +runs it when that shell's command line holds the pattern. + +## Confirmation at `9405899` + +An independent assistant reviewer confirmed R5-01 to R5-05 against the tool +source, ran the manifest change in a scratch copy with stubbed cutting, and +gave the content verdict **Ready**: no open Critical or Important finding. +Five Minor findings: R6-01 (preserve every take), R6-02 (take numbers count +`takes/superseded/`), R6-03 (R3 names the next step), R6-05 (`measure.json` +from P3) are applied; R6-04, a unit test of `split_takes.main` for the +manifest, is open. + +## State after five reviews and the confirmation + +- Content review: Ready at `9405899`; four Minor wording edits were applied + afterwards. +- Rehearsal at 0.4.1 (`rehearsal.md`): one end-to-end run through delivery, an + interrupted local render, the correction path, the pace probe, and the + listening check by the owner (passed). Stale for the steps changed since: + R3, R4, R5, P10b, the P1 failure path and the interruption text. +- Never executed: P6a and R4 after P6a, P2b, R2, R3 and the take rule + (ElevenLabs), R1 with a real limit, a checksum mismatch or failed rename in + P10 to P11, the R5 branches, a story video. A Ready review does not certify + these. diff --git a/docs/specs/WM-001-presentation-video/rehearsal.md b/docs/specs/WM-001-presentation-video/rehearsal.md index 0974626..975ea85 100644 --- a/docs/specs/WM-001-presentation-video/rehearsal.md +++ b/docs/specs/WM-001-presentation-video/rehearsal.md @@ -83,3 +83,62 @@ the corrected playbook. Still open, and not possible without a machine with `ffmpeg`, a configured speech provider and a person who listens: one end-to-end run through gate 2 and delivery, one provoked interrupted render, the correction path, and the listening check of the sample. + +## Rehearsal of the corrected playbook (2026-11-13) + +- Artifact revision: playbook and tools of Writing Method 0.4.1 (`4287ad2`), + copied to a project folder outside the repository. +- Environment: one macOS machine (Apple Silicon) as authoring and render + machine; Python 3.14, Node 26, ffmpeg 9.0; Azure AI Speech, voice + `en-US-AvaMultilingualNeural`, per-line mode. Transcription for the read-back: + Azure speech recognition through a helper written for this rehearsal (not + part of the template). Delivery location: a local folder; copy with `cp`, + checksum with `shasum -a 256`. +- Method: real execution, no simulation, by the assistant. The assistant was + operator and reviewer; no person listened. + +| Step | Action | Observed | +|---|---|---| +| Before starting | Profile, Python, script check, Node packages, media tools, transcription, delivery location | All as expected; `0 error(s), 0 warning(s)` | +| Before starting | Review gate 1 | Recorded in `review.md` by the assistant: sources, address, honesty, key term | +| Before starting | `tools/voice_azure.py --check` | `credentials accepted, 1015 voices available`, then the voice's languages; no `note:` line | +| Before starting | Scenes: `tools/timeline.py --draft`, `tools/stills.mjs out/draft-stills` | 8 draft stills; one per scene looked at; no `PLACEHOLDER`; `stills/` untouched | +| P1 | `--samples`, `voice_azure.py --only steps:2`, `verify_speech.py --only steps:2` | `steps:2 timeline`; `1 lines checked, 0 with an unrecognized key term`. Not listened to by a person | +| P2, P2a | Decision `azure`, `line`; `tools/voice_azure.py` | `8 lines, 37.5 s of speech, 7 new, 481 characters voiced` | +| P3 | `tools/timeline.py`, `tools/measure.py pace` | 167 to 177 wpm in a range of 140 to 180; `PASSED` | +| P4 | `tools/verify_speech.py` | `8 lines checked, 0 with an unrecognized key term, 0 below similarity 0.8` | +| P5 | Stills, every still opened, marks set, `tools/check_review.py` | Before the marks: `0 of 8`, exit 1. After: `8 of 8 stills inspected without finding` | +| P6, P6b | `render.host` empty; `tools/render.sh` | `rendered: out/sample-video.mp4` in under 25 s | +| R4 | Second render killed after 8 s | No last line; the earlier `out/sample-video.mp4` was still there with its old checksum, as R4 says. Render processes kept running for some seconds. Deleted the outputs, rendered again: passed | +| P7, P7a | A 3 s opening made for the rehearsal, with another stream format; `tools/prepend.sh`, `timeline.py --caption-offset 3.0` | `joined with one encode`, `opening length: 3.000000 s`; captions start at 3.35 s | +| P8 | `tools/measure.py all … --offset 3.0` | 1920x1080, 30 fps, −16.02 LUFS, true peak −2.26 dBTP, 44.579 s against 44.57 s, 5 gaps of 0.66 s; `PASSED` | +| P8b | Project record written | Seven items present | +| P9 | Gate 2 machine checks: stills, read-back, measurement, captions, chapters, record | All pass. Listening check: not done; see below | +| P10, P10b, P11 | Copy to `.new`, checksums, rename, check | Checksums equal; first delivery, so no `.previous` | +| Correction | Line `steps:1` changed; gate 1 note; Before starting again; P2 to P11 | Scenes check kept all 8 inspection marks; `8 lines … 1 new, 63 characters voiced`; `stills.mjs stills steps` reset 4 marks; render, opening, measurement `PASSED`; delivery kept the earlier file as `.previous` with its checksum | +| R6 | `tools/probe_settings.py rate=+10%` | `EFFECTIVE` (−9.3 %); the setting was not kept | + +A transcription of the delivered file's whole sound track gave every narration +word in order (similarity 1.0, first word at 3.44 s). That is a machine check +of the words, not a listening check. + +What the rehearsal changed: + +- R4 now asks the operator to make sure no render process is still running. +- A sound file that the voicing tools remove or replace takes its read-back + transcription along. The correction left the word file of the replaced line + behind; in per-scene mode an old word file could have been read as the new + sound's. The playbook no longer asks for a manual deletion. + +Observed and not changed: with an opening sequence the first chapter mark is +at 0:03 and nothing is marked at 0:00. + +Not rehearsed: P6a (no render machine), P2b, R2, R3 and the take rule (no +ElevenLabs connector in this run), R1 (the provider did not limit the run), a +checksum mismatch in P10, a story video. + +Listening check: passed on 2026-11-13. The owner heard the delivered sample +and the key-term line `steps:2` and judged pronunciation and timing good. Tone +was not commented on. In this rehearsal the check came after delivery; the +playbook asks for it before, in P9. Gate 2 is recorded in the rehearsal +project's `review.md`. diff --git a/docs/specs/WM-001-presentation-video/tasks.md b/docs/specs/WM-001-presentation-video/tasks.md index 2cc2a27..dcea9e3 100644 --- a/docs/specs/WM-001-presentation-video/tasks.md +++ b/docs/specs/WM-001-presentation-video/tasks.md @@ -97,7 +97,7 @@ Each slice writes its failing tests first and ends green. ### Slice S8: Convergence and final verification handoff -- [ ] T033 Run convergence, resolve every actionable finding, capture fresh verification, update `FEATURES.md` and the issue. +- [x] T033 Run convergence, resolve every actionable finding, capture fresh verification, update `FEATURES.md` and the issue. ## Playbook obligations diff --git a/docs/specs/WM-005-natural-prose/record.md b/docs/specs/WM-005-natural-prose/record.md new file mode 100644 index 0000000..44be925 --- /dev/null +++ b/docs/specs/WM-005-natural-prose/record.md @@ -0,0 +1,32 @@ +# WM-005: Writing rule #1, natural prose + +Maintainer requirement of 2026-11-13: no text this method produces may read as +machine-written, and this ranks first among the writing rules. + +## What was built + +- `shared/policies/natural-prose.md`: the rule, five causes, five pattern + groups, what to write instead, the delivery check, exceptions, scope by + writing mode, limits and sources. +- Every skill of the family map that writes or judges text refers to it. The + story skills reach it through `shared/story/rules.md`, below the voice + sheet; fragments and repetition stay devices of prose. +- `human-prose-drafting` holds the documentation additions and is selected + for a short standalone text that no other skill covers. + +## Evidence + +- `python3 -m unittest discover -s tests -t .`: 318 tests, OK. + `tests/test_natural_prose.py` derives the carriers from the family map. +- Two independent reviews with verification of each finding (13 findings, + then 8), all applied. The last edits were not reviewed again. +- Unscripted routing on Claude, coordinator model, 3 runs per case, at + `88f2b07`: 10 of 10 cases pass with 30 of 30 hits. The new case + `team-announcement` loaded `human-prose-drafting` in 3 of 3 runs. Codex + runs only against an installed copy and follows the release. + +## Limits + +- The rule is carried by skills. A reply for which no skill loads is not + reached; the shared-core skills do not refer to it. +- No check measures whether produced text is free of the patterns. diff --git a/docs/usage.md b/docs/usage.md index fda890f..9370879 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,7 +1,7 @@ --- type: reference audience: Authors using Writing Method -version: 0.4.1 +version: 0.5.0 --- # Writing examples @@ -16,8 +16,9 @@ The writing-depth policy places this at the medium scale. `documentation-authori runs in standalone mode: it defines the reader and version, uses the task skeleton from the chunk template, and applies `writing-procedures` (goal, prerequisites, blocks of three to five imperative steps, a check that it -worked). The draft is written under `human-prose-drafting` from the first -sentence, so no humanizing pass follows. A recorded self-review and fresh link +worked). The draft is written under writing rule #1 (natural prose), which +`human-prose-drafting` applies to documentation from the first sentence, so +no humanizing pass follows. A recorded self-review and fresh link check close the work. No plan directory is created. ## Build a documentation set @@ -124,7 +125,10 @@ reads the chapter card in `05-plot/chapters/` and writes prose only, into `06-manuscript/chapters/`. The voice sheet decides how the prose sounds. `explaining-concepts`, `writing-procedures`, `empathic-troubleshooting` and `human-prose-drafting` do not apply to it: a chapter gets no analogy, no -numbered steps and no smoothing of deliberate fragments. If one of the three +numbered steps and no smoothing of deliberate fragments. Writing rule #1 still +applies where the voice sheet is silent: among other things no staged insight, +no inflated wording and nothing left over from a chat. Fragments and +repetition stay the author's devices. If one of the three voice fields is still `unset`, no chapter is drafted and you are led to a voice trial first. The chapter is complete when `story-canon-review` has reviewed it at a named revision and you have accepted it; your acceptance is a diff --git a/evals/natural/cases/team-announcement.json b/evals/natural/cases/team-announcement.json new file mode 100644 index 0000000..7bdcedc --- /dev/null +++ b/evals/natural/cases/team-announcement.json @@ -0,0 +1,7 @@ +{ + "id": "team-announcement", + "prompt": "Schreib mir eine kurze Ankündigung für unseren Team-Newsletter: Ab Montag läuft die Zeiterfassung über das neue Portal, das alte wird am Freitag abgeschaltet.", + "files": { + "README.md": "# Notes\n\nScratch repository.\n" + } +} diff --git a/evals/natural/expected.json b/evals/natural/expected.json index e7f2599..c1ed040 100644 --- a/evals/natural/expected.json +++ b/evals/natural/expected.json @@ -98,5 +98,15 @@ "story-voice-review", "story-video-scripting" ] + }, + "team-announcement": { + "any": [ + "human-prose-drafting" + ], + "prohibited": [ + "story-drafting", + "story-voice-review", + "story-video-scripting" + ] } } diff --git a/method.json b/method.json index aa380f3..0d9c9c0 100644 --- a/method.json +++ b/method.json @@ -1,7 +1,7 @@ { "schema_version": 1, "name": "writing-method", - "version": "0.4.1", + "version": "0.5.0", "method_skills": [ "documentation-authoring", "documentation-pdf", diff --git a/pyproject.toml b/pyproject.toml index b07d4b9..1320bd0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "writing-method" -version = "0.4.1" +version = "0.5.0" description = "Shared method support." requires-python = ">=3.11" license = { text = "MIT" } diff --git a/shared/media/spoken-style.md b/shared/media/spoken-style.md index a03e3d9..cfd7105 100644 --- a/shared/media/spoken-style.md +++ b/shared/media/spoken-style.md @@ -3,6 +3,7 @@ Narration is heard once, at the speaker's pace, while the viewer also looks at a picture. Text that reads well on a page can fail here. These rules apply from the first draft, together with +[writing rule #1](../policies/natural-prose.md) and [human-prose-drafting](../../skills/human-prose-drafting/SKILL.md). ## One line, one thought diff --git a/shared/policies/lifecycle-selection.md b/shared/policies/lifecycle-selection.md index 9a873f2..98857c2 100644 --- a/shared/policies/lifecycle-selection.md +++ b/shared/policies/lifecycle-selection.md @@ -11,6 +11,9 @@ Decide scale using [writing depth](writing-depth.md). Use documentation-authorin for one standalone document and documentation-planning for a coherent set. Continue existing docs/writing work from its recorded phase. PDF delivery follows reviewed content through documentation-pdf. Small wording edits use focused editing. +A short standalone text below the medium scale, such as an email, an announcement or +a commit description, uses human-prose-drafting alone; nothing is recorded. +[Writing rule #1](natural-prose.md) applies to every text. A narrated tutorial video uses tutorial-video-scripting, then presentation-video-production, then presentation-video-review; a correction to an existing video starts at the phase diff --git a/shared/policies/natural-prose.md b/shared/policies/natural-prose.md new file mode 100644 index 0000000..4e16aac --- /dev/null +++ b/shared/policies/natural-prose.md @@ -0,0 +1,212 @@ +# Writing rule #1: natural prose + +**No text this method produces may read as machine-written.** The rule comes +before every other writing rule and covers every text a person reads: replies, +documentation, messages, commit and pull-request descriptions, review comments, +video narration and story manuscript. Its position as rule #1 is a maintainer +requirement of 2026-11-13. + +A reader who recognizes the patterns below stops trusting the text and often +stops reading it. The facts in it no longer count, because the reader assumes +that nobody checked them. + +This file is neutral: every skill family may link it, and it links into none. + +## Contents + +- Why readers recognize machine text +- The patterns +- What to write instead +- Check before delivery +- What is not a pattern +- Scope by writing mode +- Limits +- Sources + +## Why readers recognize machine text + +| Cause | Effect in the text | +|---|---| +| A language model continues with the most probable words. The result moves toward the average of everything it has read. | A specific fact gives way to a general statement that would fit any subject. Wikipedia calls this regression to the mean. | +| Training rewards answers that most people find agreeable. | Praise, inflated importance, caution in every sentence, and an opening that includes every possible reader. | +| A sentence form that promises insight is cheaper than an insight. | Contrasts with a position nobody held, lists of three, ranges "from X to Y", and a participle phrase that adds a meaning the fact does not have. | +| The same forms appear in every text and at an even rhythm. | A reader who has met them a few times recognizes them at once. A pattern marked weak alone proves little, and several in one paragraph prove much. | +| The text was written as an answer in a chat. | Greetings, offers of further help, and remarks about the request or about missing information stay in the text. | + +## The patterns + +A pattern is a defect on one occurrence. A pattern marked *weak alone* +counts only together with others. The word lists hold examples and +change with every model generation. + +### A. Staged insight + +- **Contrast with nothing.** "Not X, but Y", "not just X, it's Y", "not only X + but also Y", "Y rather than X" as a reveal, and the split form "This does not + mean X. It means Y." Keep a contrast only when the reader holds the belief + that the first half corrects. +- **False range.** "From small cafés to starred restaurants" names two ends to + suggest that everything between them was covered. +- **Opening for everyone.** "Whether you are a beginner or an expert, …" fits + any reader and tells none of them anything. +- **One-line closer.** A short last sentence that restates the paragraph or + gives it weight: "That is the real win." +- **Fragment row.** "No setup. No waiting. Just results." +- **Run-up.** "Here's the thing", "Let's dive in", "Here is what you need to + know", "It's important to note that". +- **Sayings as depth.** "At its core", "the real question is", "X is the + language of Y". +- **Arguing with no one.** "You might think", "To be clear", "This isn't + about". + +### B. Even rhythm + +- **Lists of three** where the meaning does not have three parts: three adjectives, or three examples and a lesson. +- **One sentence form repeated**: statement after statement of the same + length, or the same opening several times in a row. +- **A participle phrase at the end of the sentence**: "…, highlighting its + importance", "…, ensuring a smooth process", "…, reflecting broader trends". + It claims a consequence or meaning the sources do not show. +- **Formal connectors as glue**: "Moreover", "Furthermore", "Additionally", + "However" at the start of the sentence, or a semicolon followed by one. + *Weak alone.* +- **Dashes in chains.** *Weak alone.* Avoiding every dash and writing only + commas and short sentences has become a pattern of its own: choose + punctuation by meaning. +- **A synonym for every mention** of the same thing. One term per concept. + *Weak alone.* +- **Caution in every sentence**: "may", "often", "can potentially", "in many + cases" where the writer knows the answer. Keep a stated limit and a real + "we do not know". + +### C. Inflation in place of fact + +- **Stock vocabulary**: additionally, align with, crucial, cutting-edge, deep + dive, delve, embark, enhance, foster, garner, intricate, journey (figurative), + key (adjective), landscape (abstract), meticulous, nuanced, pivotal, realm, + robust (figurative), seamless, showcase, tapestry, testament, underscore, + valuable, vibrant. Keep the precise technical sense, glossary terms and + interface names. +- **Inflated importance**: "marks a pivotal moment", "plays a key role", + "stands as a testament", and a closing paragraph about challenges and a + bright future. +- **Fine words for "is" and "has"**: "serves as", "stands as", "features", + "boasts", "offers"; "authored" for "wrote". +- **Vague connection**: "associated with", "in connection with", "linked to" + where the actual relationship is known. +- **Borrowed authority**: "experts say", "observers note", "industry reports", + a list of outlets in place of what one of them said. +- **Sales language**: breathtaking, nestled, renowned, rich (figurative), + powerful, "in the heart of". Newer models produce it less; it stays a + defect. +- **Many words, no content**: a paragraph that can be deleted without the + reader losing a fact, a step or a decision. + +### D. Formatting as decoration + +- Bold for emphasis; a list in which every item is a bold label, a colon and + a sentence that repeats the label. +- Title Case In Headings, emoji before headings or list items, decorative + rules and arrows. +- A summary at the end of a section: "In summary", "Overall", "In conclusion". +- Markup that the destination does not render, such as Markdown asterisks in + a plain-text field. +- A list or headings where three sentences of prose would do. + +### E. Left over from the chat + +- "Great question", "Certainly!", "I hope this helps", "Let me know if", + "Would you like me to"; in a message, "I hope this email finds you well". +- Statements about missing information followed by a guess: "specific details + are limited", "based on available information", "likely"; a caution that + a source "does not by itself establish" something nobody claimed. +- In a commit message, pull-request description or review comment: an + assurance of compliance ("adheres to the guidelines", "carefully reviewed"), + a list of what was "preserved" or "retained", and a customer-service tone. + Say what changed and why. +- Traces of the tool: `utm_source=` parameters in links and citation markers + such as `oaicite`. +- An unfilled placeholder: `[Name]`, `2025-XX-XX`, `INSERT_URL_HERE`. +- Text about the previous version or about the request, outside release + notes, changelogs and migration guides. + +## What to write instead + +1. Write the fact that only this subject has: the name, the number, the place, + the command, the date. When no such fact exists, delete the sentence. +2. Use "is" and "has", the plain word, and the term the reader already uses. +3. Give a list as many items as the meaning has. Let sentence length follow + the content: a short sentence for a short thought. +4. State a limit once, where it applies. State what is unknown as unknown. +5. Begin with the point and end on the last fact. + +Removing a pattern never removes a fact, a step, a warning or a stated +uncertainty. Delete a sentence that is empty without its pattern. + +## Check before delivery + +Every pattern of the catalogue applies. As a last pass, read the finished +text once for seven of them: a contrast with nothing, a +one-line closer, a list of three, a participle phrase at a sentence end, a +stock word, a bold label, a line addressed to the person who asked. Correct +each one that the exceptions below do not cover. For a reply of a few lines +the check is one reading, with no record. + +## What is not a pattern + +- A watched phrase inside a quotation, a title, a product or interface name, + code, or a passage that discusses the phrase. +- Scope statements, legal and safety notices, real corrections of a belief + the reader holds, and a recap that a learner needs. +- Correct grammar, a formal register, or a transition word by itself. +- Three items when there are three. +- Bold for the statement of a rule, for an interface label, and for the first + words of a list item that the reader scans by. +- A structure that a template, a glossary, a source or the person's own + instruction requires. These take precedence over this rule's style + preferences. + +## Scope by writing mode + +| Mode | How the rule applies | +|---|---| +| Reader-oriented text, including every reply | In full | +| Working notes | In full; notes are short, so groups C and E matter most | +| Manuscript: story prose and in-world text | The story's voice sheet decides the voice. A device the voice sheet names, such as fragments, a repeated opening or a list of three used for rhythm, is the author's choice. Fragments, repetition, figurative language and humor are devices of prose: the fragment row of group A and the repeated opening of group B are no finding in manuscript unless the sheet excludes them. Where the sheet is silent, the other patterns of groups A, C and E are findings in narration, and group B is a finding where several of its patterns stand in one passage; a character may speak in any way that the character's voice card supports. Group D does not apply to prose. | +| Narration of a video | The mode of its script: tutorial narration in full, story narration as manuscript | +| Machine-read output, code, commands, data | Not covered | + +## Limits + +- The catalogue describes how text is recognized. A text without these + patterns can still be empty or wrong. +- People recognize machine text unreliably, and detection tools err in both + directions. The catalogue is a writing aid and no proof of who wrote a text. +- The patterns drift. Words and forms that marked one model generation fade, + and their replacements become the next markers. Reassess this file when + that shows. +- An invented reference, a dead link or a wrong number is a matter of + verification and is not covered here. +- The skills that come from the shared core do not refer to this file: the + two playbook skills, the two code-review skills, `project-backlog`, + `verification-before-completion` and the two skills for worktrees and + parallel agents. `documentation-pdf` and `presentation-video-production` + write no narration or document text and do not refer to it either; the + project record that production updates is not reached. +- Whether a host follows the rule is not measured. No host loads a policy file + before it selects a skill, so a reply for which no skill of this method + loads is not reached by it. + +## Sources + +Read on 2026-11-13. The grouping, the wording and the scope by writing mode +are this method's own. + +- Wikipedia, "Signs of AI writing" (WikiProject AI Cleanup): + https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing +- Stryng, "Common sentence structures in AI-generated text": + https://stryng.io/common-sentence-structures-in-ai-generated-text/ +- Michelle Kassorla, "Recognizing AI structures in writing": + https://michellekassorla.substack.com/p/recognizing-ai-structures-in-writing +- The pattern groups A to E were first adapted from Humanizer (MIT) in + `human-prose-drafting`; see the third-party notices. diff --git a/shared/policies/reader-oriented-output.md b/shared/policies/reader-oriented-output.md index 2129c4c..254200d 100644 --- a/shared/policies/reader-oriented-output.md +++ b/shared/policies/reader-oriented-output.md @@ -7,6 +7,14 @@ and pull-request descriptions, review comments, handoff notes and error reports. Apply them by default; skip them only when the reader has explicitly asked for terse expert output or the text is machine-consumed. +## Rule #1 for every text + +[Writing rule #1](natural-prose.md) comes first: no text may read as +machine-written. It applies to every row of the table below and to text that +fits none of them, such as a status note, a commit message or an +announcement. The didactic skills decide what to say and in what order; rule +#1 decides how the sentences may not be built. + ## Which rules apply to which reply | The reply is mainly | Apply | Not | diff --git a/shared/policies/writing-depth.md b/shared/policies/writing-depth.md index d174b84..42a8c6e 100644 --- a/shared/policies/writing-depth.md +++ b/shared/policies/writing-depth.md @@ -1,6 +1,7 @@ # Writing Depth -Prose deliverables follow the same rule as code: match the workflow to the +[Writing rule #1](natural-prose.md), natural prose, applies at every scale. +Beyond it, prose deliverables follow the same rule as code: match the workflow to the observable size, audience risk and lifetime of the text. Decide the scale first, record it, and select the writing lifecycle from that decision. Do not adopt documentation-set machinery for a paragraph, and do not write a manual one @@ -21,6 +22,7 @@ The scale table does not apply to story manuscripts; the | Observable conditions (any one moves the work to that scale) | Scale | Writing lifecycle | |---|---|---| | One sentence, paragraph, or section inside an existing text; wording, correctness or a single explanation; no new document structure; no new terms that other pages must share | Small | Native focused edit; the reader-oriented rules apply inline | +| A short standalone text that is no document: an email, an announcement, a post, a notice, a commit or pull-request description | Small | `human-prose-drafting` alone; nothing is recorded | | One self-contained document: a README section set, guide, tutorial, article, report, release note or reference page; one primary audience; expected length up to roughly 3,000 words or 40 procedure steps; no shared glossary or asset plan needed beyond the document | Medium | `documentation-authoring` in standalone mode, with the didactic and structural supporting skills its content type requires | | Several chapters or documents that must agree on terms, structure and images; more than one audience or reading path; a manual, handbook, course, knowledge base or product documentation set; expected length above roughly 3,000 words, more than five chapters, or contributors and reviews spread over multiple sessions | Large | `documentation-planning` → `documentation-authoring` (per chunk) → `documentation-review` → `verification-before-completion` | @@ -34,7 +36,7 @@ that recorded scale and phase instead of deciding again. | Scale | Required depth | |---|---| -| Small | Reader-oriented wording, terminology consistent with the surrounding text, focused check of the changed passage and its links; preserve the surrounding voice without loading an additional supporting skill | +| Small | Writing rule #1 (natural prose) applied inline, for a short standalone text such as an email or an announcement through `human-prose-drafting` alone with nothing recorded; reader-oriented wording, terminology consistent with the surrounding text, focused check of the changed passage and its links; preserve the surrounding voice without loading an additional supporting skill | | Medium | Content type chosen from the information architecture, one template-based document with frontmatter, explicit reader, prerequisites and validation for procedures, local glossary check, drafting under the `human-prose-drafting` constraints, self-review against the didactic rules, fresh link and rendering check | | Large | Documentation plan with audience, architecture map, chunk manifest and conventions; shared glossary; asset manifest with placeholders; per-chunk authoring under the `human-prose-drafting` constraints with checkpoints; set-wide consistency review including prose tells; convergence of findings; fresh verification | diff --git a/shared/policies/writing-mode.md b/shared/policies/writing-mode.md index c63be0c..0c1d6d4 100644 --- a/shared/policies/writing-mode.md +++ b/shared/policies/writing-mode.md @@ -14,6 +14,10 @@ quality claim for either family and rests on no pilot evidence. and `presentation-video-review` voice, time, render and check an accepted video script of either family and never restyle its narration. +Writing rule #1, natural prose, stands above the families: it is stored in +`shared/policies/natural-prose.md`, applies in every mode with the scope that +file states, and may be linked by all three families. + This file is the neutral hub and the authority for the mode rule. All three families refer to it; it links into none. The operative sentences that skills and vault files carry are stored in the policy block at the end and are tested @@ -55,8 +59,8 @@ order and stop at the first that holds. | Order | Condition | Mode | Governed by | |---|---|---|---| | 1 | The file is a reader-facing vault file (`README.md`, `START.md`, `AGENTS.md` or `CLAUDE.md`) or a reader-facing deliverable about the story or the vault, wherever it is stored: documentation or a tutorial-video script with its production files | `reader-oriented` | The reader family's rules | -| 2 | The text is story prose, in-world text or paratext: it goes into a manuscript location of a `kind: story` vault, or the author explicitly asks for story prose; or it is the narration `text` in `src/narration.json` of a video project whose `video.json` has `purpose: story`, wherever the project is stored: a segmented copy of manuscript text | `manuscript` | The voice sheet, then `shared/story/rules.md`. Nothing from the reader family. | -| 3 | The text is another file of a story or study vault, a research note, or another file of a story video project (`video.json`, a scene `message`, `script/script.md`, `pronunciation.json`), wherever it is stored | `working-note` | The story skills. Plain notes: neither the voice sheet nor didactic structure. | +| 2 | The text is story prose, in-world text or paratext: it goes into a manuscript location of a `kind: story` vault, or the author explicitly asks for story prose; or it is the narration `text` in `src/narration.json` of a video project whose `video.json` has `purpose: story`, wherever the project is stored: a segmented copy of manuscript text | `manuscript` | The voice sheet, then `shared/story/rules.md`, which carries writing rule #1 for prose. Nothing from the reader family. | +| 3 | The text is another file of a story or study vault, a research note, or another file of a story video project (`video.json`, a scene `message`, `script/script.md`, `pronunciation.json`), wherever it is stored | `working-note` | The story skills. Plain notes: neither the voice sheet nor didactic structure. Writing rule #1 applies. | | 4 | Everything else, including every reply to the author | `reader-oriented` | The reader family's rules, unchanged | The subject never sets the mode. A reply that talks about a story is still a @@ -125,7 +129,7 @@ read, and this file is what they are compared with. |---|---|---| | 1. Names | Every story skill starts with `story-`; no name equals a shared, reader or engineering skill name or contains `continuity` | The names are as stated | | 2. Descriptions and opening lines | Reciprocal exclusions and the precedence sentence | The sentences are present and equal the policy block. Whether a model follows them is statistical. | -| 3. Link firewall | Story files link only into `shared/story/`, `templates/story-vault/`, other story skills, this file, `shared/policies/proportionality.md` and `skills/verification-before-completion/SKILL.md`. For a story video they also link the video project template, the two form skills and `shared/media/speech-synthesis.md`. Reader files and form skills never link into the story directories. Links are not followed further: a form skill carries tutorial-only links that its Story scripts section sets aside for `purpose: story`. Backticked skill names are checked against the family map as well; form skills may be named by both families and may name skills of both. | A skill cannot pull the other family's rule files in through links | +| 3. Link firewall | Story files link only into `shared/story/`, `templates/story-vault/`, other story skills, this file, `shared/policies/natural-prose.md`, `shared/policies/proportionality.md` and `skills/verification-before-completion/SKILL.md`. For a story video they also link the video project template, the two form skills and `shared/media/speech-synthesis.md`. Reader files and form skills never link into the story directories. Links are not followed further: a form skill carries tutorial-only links that its Story scripts section sets aside for `purpose: story`. Backticked skill names are checked against the family map as well; form skills may be named by both families and may name skills of both. | A skill cannot pull the other family's rule files in through links | | 4. No lifecycle graph | No story skill appears in `shared/policies/lifecycle-handoffs.md` | The graph contains no story node | | 5. Vault kind | Only `kind: story` permits drafting, and only with the three voice fields filled | The starter and the skills state the rule | @@ -200,7 +204,7 @@ The entries under `sentences` are the exact text the carriers hold. "hub": "shared/policies/writing-mode.md", "story_link_allow": { "prefixes": ["shared/story/", "templates/story-vault/", "skills/story-", "templates/presentation-video/"], - "files": ["shared/policies/writing-mode.md", "shared/policies/proportionality.md", "skills/verification-before-completion/SKILL.md", "skills/presentation-video-production/SKILL.md", "skills/presentation-video-review/SKILL.md", "shared/media/speech-synthesis.md"] + "files": ["shared/policies/writing-mode.md", "shared/policies/natural-prose.md", "shared/policies/proportionality.md", "skills/verification-before-completion/SKILL.md", "skills/presentation-video-production/SKILL.md", "skills/presentation-video-review/SKILL.md", "shared/media/speech-synthesis.md"] }, "reader_link_deny_prefixes": ["shared/story/", "templates/story-vault/", "skills/story-"], "form_link_deny_prefixes": ["shared/story/", "templates/story-vault/", "skills/story-"], diff --git a/shared/story/rules.md b/shared/story/rules.md index efb8188..4673ec9 100644 --- a/shared/story/rules.md +++ b/shared/story/rules.md @@ -14,6 +14,12 @@ This is a structural check, not a requirement to repeat those words in manuscrip Attribution: Trey Parker and Matt Stone's NYU craft advice, as presented in the [excerpt recorded as CW06](https://www.youtube.com/shorts/2v3Z9OTC4dA). **Its position as rule #1 is a maintainer requirement of 2026-11-12.** The operational checks and long-fiction qualifications above are this method's synthesis; no empirical reader-quality result is claimed. See [CW06 in the source index](sources.md#cw06-inspected-scope) for inspected scope. +## #1 prose rule: natural prose + +**No manuscript sentence may read as machine-written.** [Writing rule #1](../policies/natural-prose.md) lists the patterns and why readers recognize them; its position is a maintainer requirement of 2026-11-13. The storytelling rule above governs how beats connect, this rule how sentences are built; neither replaces the other. + +The voice sheet stays the first authority. A device the sheet names, such as fragments, a repeated opening or a list of three used for rhythm, is the author's choice and no finding. Fragments, repetition, figurative language and humor are devices of prose: a row of fragments or a repeated opening is no finding unless the sheet excludes it. Where the sheet is silent, the other patterns of the rule's groups A, C and E are defects in narration: staged insight, inflation in place of a concrete perception, and anything left over from a chat. Group B, even rhythm, is a defect where several of its patterns stand in one passage. The word lists of the rule hold examples and are read in context. Working notes follow the rule in full. The rule is a writing requirement and makes no claim about detection. A character may speak in such a pattern when the character's voice card supports it. + ## Further craft heuristics 2. Build enough world to support the next meaningful story decision. Mark other questions open. Wrede's questionnaire is selective; completeness is not a prerequisite for prose. (WB01, WB12, WB14) diff --git a/shared/story/voice-and-tone.md b/shared/story/voice-and-tone.md index 9600171..72a7d97 100644 --- a/shared/story/voice-and-tone.md +++ b/shared/story/voice-and-tone.md @@ -17,7 +17,7 @@ The narration of a story video is manuscript, not an explanatory video: it is th | Voice sheet | [`00-project/voice.md`](../../templates/story-vault/00-project/voice.md) of the vault | How the narration sounds: the narration contract per viewpoint, tone palette, language conventions, anchor passages, deliberate exceptions, paratext register | | Character voice card | The voice card section of each [character note](../../templates/story-vault/90-templates/character.md) | How one character sounds in dialogue and, as a viewpoint, what the narration attends to | -For manuscript text the voice sheet comes first, then the [story rules](rules.md) and the defaults named in [story drafting](../../skills/story-drafting/SKILL.md). A default applies only where the sheet is silent, and a review that relies on one labels it "method default, not sheet". +For manuscript text the voice sheet comes first, then the [story rules](rules.md) with their #1 prose rule, and the defaults named in [story drafting](../../skills/story-drafting/SKILL.md). A default applies only where the sheet is silent, and a review that relies on one labels it "method default, not sheet". ## Lifecycle of the voice sheet @@ -58,6 +58,6 @@ Dialogue examples on a card reference accepted passages. A card distinguishes ch ## Checking the voice -The [story voice review](../../skills/story-voice-review/SKILL.md) skill judges a chapter or a range against the sheet and the cards and reports findings in four classes: unintended deviation, deliberate exception, sheet gap and candidate sheet change. It needs at least two anchor passages and a filled tone palette; without them it routes back to the trial, which can supply both. An anchor may be a trial passage. It uses no banned-word list and no universal style standard, and it does not edit accepted prose. +The [story voice review](../../skills/story-voice-review/SKILL.md) skill judges a chapter or a range against the sheet and the cards and reports findings in four classes: unintended deviation, deliberate exception, sheet gap and candidate sheet change. It needs at least two anchor passages and a filled tone palette; without them it routes back to the trial, which can supply both. An anchor may be a trial passage. Beyond the #1 prose rule of the [story rules](rules.md) it uses no banned-word list and no universal style standard, and it does not edit accepted prose. A voice review is one input to the author's acceptance of a chapter. It is not a measurement of quality, and passing it proves nothing about how readers will respond. diff --git a/skills/documentation-authoring/SKILL.md b/skills/documentation-authoring/SKILL.md index 1ef9bb1..839ec3e 100644 --- a/skills/documentation-authoring/SKILL.md +++ b/skills/documentation-authoring/SKILL.md @@ -8,6 +8,8 @@ description: "Use when reader-facing documentation must be written or revised: o Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every sentence written under this skill: no pattern that reads as machine-written. + Write the text readers will use. In a documentation set, author chunks according to the plan; for a standalone document, apply the same content-type discipline without the set-level machinery. @@ -118,8 +120,8 @@ ordinary continuation follows the existing plan directly. chunks, with blocks of three to five steps and a validation section; `empathic-troubleshooting` for troubleshooting chunks; consistent tables for reference chunks. Before writing the first sentence, read - [human-prose-drafting](../human-prose-drafting/SKILL.md) and apply its - guidance while drafting: direct statements, concrete facts, natural + [human-prose-drafting](../human-prose-drafting/SKILL.md), which applies + writing rule #1 to documentation, and follow it while drafting: direct statements, concrete facts, natural rhythm and useful formatting. Preserve its exceptions for source fidelity, required structure and technical terms. These constraints apply while writing; a separate humanizing pass afterwards is not part of this lifecycle. diff --git a/skills/documentation-planning/SKILL.md b/skills/documentation-planning/SKILL.md index 66f10b9..9d94326 100644 --- a/skills/documentation-planning/SKILL.md +++ b/skills/documentation-planning/SKILL.md @@ -8,6 +8,8 @@ description: "Use when a documentation set needs an initial plan or an explicit Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to the plan and to every text planned with it: no pattern that reads as machine-written. + Decide how large the writing project is before writing, record that decision, and give the authors one plan they can follow chunk by chunk across many sessions without losing consistency. diff --git a/skills/documentation-review/SKILL.md b/skills/documentation-review/SKILL.md index 85adf34..0eb49e9 100644 --- a/skills/documentation-review/SKILL.md +++ b/skills/documentation-review/SKILL.md @@ -8,6 +8,8 @@ description: "Use when drafted chunks of a documentation set under docs/writing Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) is a review criterion for every chunk: a pattern that reads as machine-written is a finding. + Read the set as its least experienced reader and as its glossary owner. Record findings with evidence, and return actionable findings to the author with the text they must change, not with a verdict alone. @@ -108,9 +110,10 @@ on the text rather than recollection: 7. Cross-references: every relative link and chunk ID resolves; no "see above". 8. Troubleshooting chunks: symptom first, causes ordered, first check, fix, confirmation, escalation. -9. Read [human-prose-drafting](../human-prose-drafting/SKILL.md) and assess - passages for staged contrasts, empty closers, dash chains, inflated wording - and chatbot residue. Apply its context and preservation exceptions; a +9. Read [writing rule #1](../../shared/policies/natural-prose.md) and + [human-prose-drafting](../human-prose-drafting/SKILL.md) and assess + passages for staged contrasts, empty closers, lists of three, participle + riders, stock words, bold labels and chatbot residue. Apply the rule's exceptions; a word match alone is not a finding. Return specific prose findings to the author within the existing review cycle; add no separate rewrite phase. diff --git a/skills/empathic-troubleshooting/SKILL.md b/skills/empathic-troubleshooting/SKILL.md index 91c2b99..1a8a3ae 100644 --- a/skills/empathic-troubleshooting/SKILL.md +++ b/skills/empathic-troubleshooting/SKILL.md @@ -10,6 +10,8 @@ Not for story manuscripts or in-world text: when the target is manuscript, stop Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every sentence written under this skill: no pattern that reads as machine-written. + The reader arrives with a symptom, not an error code, and often under time pressure. Troubleshooting text meets them at the symptom, tells them the most likely reason in plain words, and leads them through the cheapest check first. diff --git a/skills/explaining-concepts/SKILL.md b/skills/explaining-concepts/SKILL.md index 46bc02e..defeca9 100644 --- a/skills/explaining-concepts/SKILL.md +++ b/skills/explaining-concepts/SKILL.md @@ -10,6 +10,8 @@ Not for story manuscripts or in-world text: when the target is manuscript, stop Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every sentence written under this skill: no pattern that reads as machine-written. + Explain so that the defined reader could restate the idea in their own words. This is the Feynman technique applied to writing: if the explanation needs jargon to stand up, the writer has not understood it well enough yet. diff --git a/skills/human-prose-drafting/SKILL.md b/skills/human-prose-drafting/SKILL.md index 580c04c..b7406d1 100644 --- a/skills/human-prose-drafting/SKILL.md +++ b/skills/human-prose-drafting/SKILL.md @@ -1,6 +1,6 @@ --- name: human-prose-drafting -description: "Use within documentation-authoring for medium and large texts to apply Humanizer prose guidance from the first sentence, with a brief per-chunk check. Not a separate rewrite phase or a reason to change facts, code, quotations or required document structure. Not for story manuscripts or in-world text." +description: "Use whenever prose for people is written or revised and no other writing skill covers it: an email, announcement, post, notice, commit or pull-request description; and as a supporting skill within documentation-authoring for medium and large texts. Applies writing rule #1, natural prose without machine patterns, from the first sentence, with a brief check before delivery. Not a separate rewrite phase or a reason to change facts, code, quotations or required document structure. Not for story manuscripts or in-world text." --- # Human Prose Drafting @@ -10,15 +10,25 @@ Not for story manuscripts or in-world text: when the target is manuscript, stop Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. -Write for the defined reader and subject from the first sentence. Apply the -patterns below while choosing words and organizing each paragraph. The writing +Write for the defined reader and subject from the first sentence. Apply +[writing rule #1](../../shared/policies/natural-prose.md) while choosing words and organizing each paragraph. The writing lifecycle includes a short check of each chunk, with no separate humanizing phase. Adapted from blader/humanizer (MIT); patterns trace to Wikipedia's "Signs of AI writing" maintained by WikiProject AI Cleanup. See the third-party notices. +The pattern catalogue itself lives in writing rule #1, which applies to every +text; this skill applies it to documentation and to short texts that no +other skill covers. ## Trigger +Use for a short standalone text a person will read that no other writing +skill covers: an email, an announcement, a post, a notice, a commit or +pull-request description. For such a text read the rule, write, and run its +delivery check once; nothing is recorded. A document, also a release note, +belongs to `documentation-authoring`, and this skill supports it there. An +ordinary reply belongs to the didactic skills. + Use inside `documentation-authoring` for every chunk or standalone document at the medium or large scale, and inside `documentation-review` as one check. The didactic skills decide what to say and in what order; this skill decides @@ -43,88 +53,29 @@ how the sentences may not be built. 2. Choose for the defined reader. Vary sentence length as speech does; name the actor; use the number of items the meaning has; pick the plain word. -## Constraints by strength - -Use these patterns as contextual writing guidance, not a string blacklist. -The staged rhetoric in group A warrants attention on one occurrence. Weak -signals such as a dash or a three-item list need context before changing them. -User instructions, required templates, glossary terms, source fidelity and -project style take precedence over stylistic preferences here. - -### A. State instead of staging - -- **No "not X but Y".** Also not "not just X, it's Y", "X rather than Y" as a - reveal, or the split form "This does not mean X. It means Y." State the - point. Keep a contrast only when the negative half corrects a belief the - reader actually holds. -- **No one-line closers or fragment rows.** No "That is the real win.", no - sentence-long paragraph that restates the one before, no "No prior. No - nostalgia." Merge fragments into one sentence with a specific claim. -- **No sayings dressed as depth.** Not "at its core", "the real question is", - "what really matters", "X is the language of Y". Write the specific claim. -- **No run-up before the point.** Not "Let's dive in", "Here's what you need - to know", "Honestly?", "Here's the thing". Begin with the point. -- **No arguing with no one.** Not "This isn't about", "To be clear", "A - tempting approach would be", "You might think". Keep an objection only - when the text attributes it or the reader would actually weigh it. - -### B. Rhythm follows meaning - -- **No forced triads.** Three items only when the meaning has three; three - parallel examples plus a lesson is the same tell at paragraph scale. -- **No repeated sentence openings** in a row unless deliberate for rhythm. -- **Avoid dash chains.** Use periods, commas, colons or parentheses when they - make the sentence easier to read. Keep meaningful ranges, names and dashes - required by the project's style. *Weak alone.* -- **No stacked qualifiers.** "could potentially possibly" becomes "may". Keep - scope statements, safety notices and honest uncertainty. *Weak alone.* -- **Hyphenate only where grammar needs it**: "a high-quality report", "the - report is high quality". *Weak alone.* -- **Name the actor.** "You do not need a configuration file", not "No - configuration file needed". Procedures already require this. *Weak alone.* - -### C. Facts without inflation - -- **Avoid the stock words**: actually, additionally, align with, bolstered, - crucial, deep dive, delve, emphasizing, enduring, enhance, fostering, - garner, highlight (verb), interplay, intricate, key (adjective), landscape - (abstract), meticulous, pivotal, quietly, robust (figurative), showcase, - tapestry, testament, underscore (verb), valuable, vibrant. Keep precise - technical senses, glossary terms and interface names. This is a watch list, - not a ban on words that accurately describe the subject. -- **No inflated significance.** Not "marks a pivotal moment", "plays a key - role", "the future looks bright", and no closing send-off paragraph. End on - the last concrete fact. -- **No vague association.** Not "associated with", "in connection with" when - the subject shows the actual relationship; when it does not, keep the vague - wording rather than inventing a role. -- **No shallow -ing riders**: "highlighting", "ensuring", "reflecting", - "showcasing" bolted onto a fact. Keep the fact. -- **No sales language**: boasts, vibrant, rich (figurative), nestled, - renowned, breathtaking, seamless, powerful. State what the thing is. -- **No borrowed authority.** Not "experts believe", not a list of outlets. - Name the source and what it said, or leave the claim out. -- **Use is, are and has.** Not "serves as", "features", "boasts", "offers". - -### D. Formatting carries information +## The patterns -- **Bold only for interface labels** as `writing-procedures` requires, and - for the first words of a list item when the reader scans by them. No bold - for emphasis, no list where every item is a bold label with a colon and a - sentence that repeats the label. -- **Prefer sentence-case headings** and avoid decorative emojis, arrows and - rules. Preserve required headings, anchors and template title structure. -- **Straight quotation marks** unless the project's style guide says - otherwise. *Weak alone.* +Read [writing rule #1](../../shared/policies/natural-prose.md) before the first +sentence. It holds the patterns in five groups, the reasons readers recognize +them, the exceptions and the scope. Use it as contextual guidance, not as a +string blacklist: the staged forms of its group A are a defect on one +occurrence, and a pattern it marks as weak needs context before you change +anything. User instructions, required templates, glossary terms, source +fidelity and project style take precedence over its style preferences. -### E. Nothing left over from the chat +Documentation adds these to the rule: -- **No chatbot residue**: "Great question", "I hope this helps", "Let me - know", "Would you like", "Here is a". Documentation stands on its own. -- **No knowledge-limit disclaimers or guesses.** Not "details are limited in - available sources, it appears". State what the subject shows or leave it - out; never present a guess as a fact. -- **No heading repeated in the first sentence.** +- **Name the actor.** "You do not need a configuration file", not "No + configuration file needed". Procedures already require this. +- **Bold only for interface labels** as `writing-procedures` requires, and + for the first words of a list item when the reader scans by them. +- **Sentence-case headings.** Preserve required headings, anchors and + template title structure. +- **No heading repeated in the first sentence** below it. +- **Hyphenate only where grammar needs it**: "a high-quality report", "the + report is high quality". +- **Straight quotation marks** unless the project's style guide says + otherwise. - **No writing about the previous version** except in release notes, changelogs and migration guides. Describe current behavior. @@ -132,15 +83,16 @@ project style take precedence over stylistic preferences here. Concept, task, reference and troubleshooting text stays neutral and plain, addresses the reader as "you", and keeps the project's glossary terms. The -plan or project contract decides the language of the text; the tells above have +plan or project contract decides the language of the text; the patterns of the rule have equivalents in every language and are treated the same. Do not add opinions, humor or asides to documentation; those belong to personal writing. ## Chunk check -Before marking a chunk drafted, read it once for the five tells that most -often survive drafting: a not-X-but-Y contrast, a one-line closer, a dash, a -triad, a bold label. Assess each in context, including the exceptions below. +Before marking a chunk drafted, read it once for the seven patterns of the +rule's delivery check: a contrast with nothing, a one-line closer, a list of +three, a participle phrase at a sentence end, a stock word, a bold label, a +line addressed to the person who asked. Assess each in context, including the exceptions below. Correct unnecessary rhetoric within the chunk; retain useful structure. Confirm the fix dropped no fact, step, warning or claim. This check is part of authoring the chunk and adds no separate humanizing stage or extra output artifact. diff --git a/skills/presentation-video-review/SKILL.md b/skills/presentation-video-review/SKILL.md index 6c689b5..78de1b5 100644 --- a/skills/presentation-video-review/SKILL.md +++ b/skills/presentation-video-review/SKILL.md @@ -8,6 +8,8 @@ description: "Use when a finished script of a tutorial or a story video needs it Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) is a criterion at gate 1 for a tutorial script, and applies to the findings this skill writes. + Check a video as its least experienced viewer would meet it, and as the person who must stand behind every statement in it. Record findings; do not fix them. Corrections return to scripting or production. diff --git a/skills/story-architecture/SKILL.md b/skills/story-architecture/SKILL.md index c7cb462..6f36e51 100644 --- a/skills/story-architecture/SKILL.md +++ b/skills/story-architecture/SKILL.md @@ -9,6 +9,8 @@ Mode check first, under [writing mode](../../shared/policies/writing-mode.md): f No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to every note this skill writes: nothing in it reads as machine-written. + Outlines, arc notes, volume notes and chapter cards are working notes: plain notes that follow neither the voice sheet nor any instructional document structure. Read the story brief, accepted cast/world constraints and [workflow](../../shared/story/workflow.md). Use the [arc](../../templates/story-vault/90-templates/arc.md), [volume](../../templates/story-vault/90-templates/volume.md), [chapter card](../../templates/story-vault/90-templates/chapter.md) and [foreshadow](../../templates/story-vault/90-templates/foreshadow.md) templates. diff --git a/skills/story-bootstrap/SKILL.md b/skills/story-bootstrap/SKILL.md index dd1a84d..b8f0cc8 100644 --- a/skills/story-bootstrap/SKILL.md +++ b/skills/story-bootstrap/SKILL.md @@ -9,6 +9,8 @@ Mode check first, under [writing mode](../../shared/policies/writing-mode.md): f No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to every note this skill writes: nothing in it reads as machine-written. + Read [workflow](../../shared/story/workflow.md) and [rules](../../shared/story/rules.md). Read the [retrieval contract](../../shared/story/retrieval.md) only if a memory or retrieval tool is available. Paths in this skill resolve from its own folder; story paths resolve from the selected vault. For a minimal idea or a resumed development conversation, use [guided story development](../../shared/story/story-development.md). Read `00-project/development.md` and `00-project/decisions.md` when they exist; update them from the conversation rather than requiring the author to fill forms. Ask only the next consequential unresolved question and preserve prior delegation. diff --git a/skills/story-canon-review/SKILL.md b/skills/story-canon-review/SKILL.md index b78e436..0f9ffaa 100644 --- a/skills/story-canon-review/SKILL.md +++ b/skills/story-canon-review/SKILL.md @@ -9,6 +9,8 @@ Mode check first, under [writing mode](../../shared/policies/writing-mode.md): f No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to every note this skill writes: nothing in it reads as machine-written. + The review report is a working note. It never restyles manuscript, and it does not judge voice or tone; that belongs to `story-voice-review`. Read the relevant accepted notes, manuscript passages and the [review template](../../templates/story-vault/90-templates/review.md); read the [retrieval contract](../../shared/story/retrieval.md) only if a memory or retrieval tool is in use. Establish the exact chapters and revisions in scope. Summaries and retrieval hits locate evidence; original passages decide findings. diff --git a/skills/story-characters/SKILL.md b/skills/story-characters/SKILL.md index e89b160..8d4c15a 100644 --- a/skills/story-characters/SKILL.md +++ b/skills/story-characters/SKILL.md @@ -9,6 +9,8 @@ Mode check first, under [writing mode](../../shared/policies/writing-mode.md): f No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to every note this skill writes: nothing in it reads as machine-written. + Character notes are working notes: plain notes that follow neither the voice sheet nor any instructional document structure. Read the story brief, voice sheet, relevant world constraints and accepted cast notes. Use the [character template](../../templates/story-vault/90-templates/character.md) and [working rules](../../shared/story/rules.md). diff --git a/skills/story-craft-research/SKILL.md b/skills/story-craft-research/SKILL.md index f402ef8..3b12efd 100644 --- a/skills/story-craft-research/SKILL.md +++ b/skills/story-craft-research/SKILL.md @@ -9,6 +9,8 @@ Mode check first, under [writing mode](../../shared/policies/writing-mode.md): f No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to every note this skill writes: nothing in it reads as machine-written. + Research notes, source cards and study notes are working notes: plain notes that follow neither a voice sheet nor any instructional document structure. ## Where the work is kept diff --git a/skills/story-drafting/SKILL.md b/skills/story-drafting/SKILL.md index 776dfe4..196a3ae 100644 --- a/skills/story-drafting/SKILL.md +++ b/skills/story-drafting/SKILL.md @@ -40,6 +40,8 @@ For premise-to-pilot feedback or broad prose revision, use [story and prose qual Draft the requested unit, normally a scene or chapter. Let viewpoint determine attention, vocabulary, judgment and available knowledge. Maintain the agreed tense, distance and rules for viewpoint changes. A narrator may know more than a character only when the chosen narration permits it. Stay inside the sheet's tone palette: leave the baseline only for a permitted excursion, and return as the sheet describes. +Apply the [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) to every sentence: where the voice sheet is silent, its groups A, C and E are defects in narration, and group B where several of its patterns stand in one passage. + Apply [storytelling rule #1](../../shared/story/rules.md#1-storytelling-rule-therefore--but) while drafting and as the first structural revision check: each consequential beat follows through cause and consequence or a complication that changes the response. If the passage is only an "and then" sequence, repair the story connection before polishing sentences. The causal relationship must be present in the events; the manuscript need not use the literal words "therefore" or "but". Preserve purposeful quiet consequences and intentional delayed revelation. Ground action in concrete perceptions and decisions. Make dialogue purposeful through competing wants, omissions and subtext; distinguish speakers by experience and register, using their voice cards. Use action and reaction to show emotional change, with direct telling when it is clearer or deliberately part of the voice. Avoid explanatory lines that merely repeat what the scene already conveyed. @@ -58,7 +60,7 @@ These names let a draft note or a voice review point at one default. They apply | Name | Default | | --- | --- | -| Causal beats | Consequential beats connect through consequence or complication, not "and then" (rule #1). | +| Causal beats | Consequential beats connect through consequence or complication, not "and then" (storytelling rule #1). | | Viewpoint-bound attention | Attention, vocabulary, judgment and knowledge come from the viewpoint; the narrator knows more only where the narration permits it. | | Held narration | Tense, distance and the rules for viewpoint changes stay as agreed within the unit. | | Grounded action | Action rests on concrete perceptions and decisions. | @@ -66,10 +68,10 @@ These names let a draft note or a voice review point at one default. They apply | Distinct speakers | Speakers differ by experience and register, not by a swapped vocabulary or a catchphrase. | | No redundant explanation | No line merely repeats what the scene already conveyed; direct telling stays where it is clearer or part of the voice. | | Rhythm for the moment | Sentence and paragraph length serve this moment; no fixed ratio, no uniform scaffold. | -| Preserved devices | Deliberate fragments, repeated motifs, figurative language, humor, dialect and silence stay. | +| Preserved devices | Deliberate fragments, repeated motifs, figurative language, humor, dialect and silence stay; the #1 prose rule does not remove them. | | World-true detail | New detail belongs to this world and this viewpoint; nothing is added as fact merely to make prose vivid. | -There is no banned-word list and no universal style standard behind these names. +There is no banned-word list and no universal style standard behind these names; the word lists of the #1 prose rule hold examples and are read in context. ## Revision diff --git a/skills/story-video-scripting/SKILL.md b/skills/story-video-scripting/SKILL.md index b266561..18ed956 100644 --- a/skills/story-video-scripting/SKILL.md +++ b/skills/story-video-scripting/SKILL.md @@ -11,6 +11,8 @@ For manuscript text the story's voice sheet overrides explaining-concepts, writi No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to a listening edition as to any manuscript, and to every note this skill writes: nothing in it reads as machine-written. + This skill is experimental. It turns accepted story text into the script of a narrated story video: scenes, narration lines and plain picture descriptions. The story family owns the text; the form skills voice, time, render and check the accepted script and never restyle it. Nothing is voiced or rendered here. ## When to use diff --git a/skills/story-voice-review/SKILL.md b/skills/story-voice-review/SKILL.md index a7de2a7..a465793 100644 --- a/skills/story-voice-review/SKILL.md +++ b/skills/story-voice-review/SKILL.md @@ -1,6 +1,6 @@ --- name: story-voice-review -description: "Use when a drafted chapter, short piece or chapter range of a story vault must be judged against that story's voice sheet and character voice cards, including author or beta-reader feedback on how the prose sounds. Reports findings and never edits accepted prose. Not for canon or chronology checks, for drafting or revising prose, or for a general style check. Not for session replies, documentation or presentation videos." +description: "Use when a drafted chapter, short piece or chapter range of a story vault must be judged against that story's voice sheet and character voice cards, including author or beta-reader feedback on how the prose sounds. Reports findings and never edits accepted prose. Not for canon or chronology checks, for drafting or revising prose, or for a style check beyond the sheet, the cards and the #1 prose rule. Not for session replies, documentation or presentation videos." --- # Story voice review @@ -28,9 +28,10 @@ Read for the narration contract of each viewpoint, the tone palette with its exc Every finding cites the passage, with file and location, and one basis: - a clause of the voice sheet or of a character voice card, or -- a named default from [story drafting](../story-drafting/SKILL.md), labelled "method default, not sheet". +- a named default from [story drafting](../story-drafting/SKILL.md), labelled "method default, not sheet", or +- a pattern of the [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) in narration that neither the sheet nor a card supports, labelled "prose rule #1": groups A, C and E, and group B where several of its patterns stand in one passage. Class it as a sheet gap. -Drop an observation that has neither. There is no banned-word list and no universal style standard; a fragment, a repetition or a joke is a finding only where the sheet or a card says so. +Drop an observation that has none of these. Beyond that rule there is no banned-word list and no universal style standard. A fragment, a repetition or a joke is a finding only where the sheet or a card says so; the prose rule does not make it one. Class each finding as one of: diff --git a/skills/story-worldbuilding/SKILL.md b/skills/story-worldbuilding/SKILL.md index 82d6ff8..996e54d 100644 --- a/skills/story-worldbuilding/SKILL.md +++ b/skills/story-worldbuilding/SKILL.md @@ -9,6 +9,8 @@ Mode check first, under [writing mode](../../shared/policies/writing-mode.md): f No run state: this skill has no recovery preamble and hands off to no backlog or run-tracking skill. A story or study vault keeps no backlog and no run directory; its state lives in 00-project/development.md and 00-project/decisions.md. +The [#1 prose rule](../../shared/story/rules.md#1-prose-rule-natural-prose) applies to every note this skill writes: nothing in it reads as machine-written. + World notes are working notes: plain notes that follow neither the voice sheet nor any instructional document structure. For technically grounded fiction, read [science and institutions](references/science-and-institutions.md) when capability limits, scientific claims or institutional consequences affect the plot. diff --git a/skills/terminology-guard/SKILL.md b/skills/terminology-guard/SKILL.md index 0d16f91..02277a1 100644 --- a/skills/terminology-guard/SKILL.md +++ b/skills/terminology-guard/SKILL.md @@ -8,6 +8,8 @@ description: "Use as a supporting skill when a document or documentation set mus Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every definition and note written under this skill: no pattern that reads as machine-written. + Over hundreds of pages, readers lose trust when the same thing has three names. The glossary is the single authority for terms; text follows it, and checks are run against it rather than against memory. diff --git a/skills/tutorial-video-scripting/SKILL.md b/skills/tutorial-video-scripting/SKILL.md index b46aa62..7f53ef8 100644 --- a/skills/tutorial-video-scripting/SKILL.md +++ b/skills/tutorial-video-scripting/SKILL.md @@ -8,6 +8,8 @@ description: "Use when a narrated tutorial video must be scripted from source ma Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every sentence written under this skill: no pattern that reads as machine-written. + Write the script of a tutorial video: what is said, in which order, and what the viewer sees while it is said. The script is finished when a person has reviewed it and the script check passes. Nothing is voiced in this phase. diff --git a/skills/visual-placeholders/SKILL.md b/skills/visual-placeholders/SKILL.md index e32135f..22eeae2 100644 --- a/skills/visual-placeholders/SKILL.md +++ b/skills/visual-placeholders/SKILL.md @@ -8,6 +8,8 @@ description: "Use as a supporting skill when documentation needs screenshots, di Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every caption, alt text and instruction written under this skill: no pattern that reads as machine-written. + Text and image must say the same thing. A placeholder is a contract: it states what the reader must see, where in the text it belongs, and how to produce the image later so that it proves exactly that. diff --git a/skills/writing-procedures/SKILL.md b/skills/writing-procedures/SKILL.md index 97549d8..6023a25 100644 --- a/skills/writing-procedures/SKILL.md +++ b/skills/writing-procedures/SKILL.md @@ -10,6 +10,8 @@ Not for story manuscripts or in-world text: when the target is manuscript, stop Apply the shared [proportionality rule](../../shared/policies/proportionality.md) before adding work, delegating, or repeating verification. +[Writing rule #1](../../shared/policies/natural-prose.md) applies to every sentence written under this skill: no pattern that reads as machine-written. + Write for the reader's hands. A procedure tells one defined reader exactly what to do, where, in what order, and how to see that it worked. Passive descriptions of where something happens are not instructions. diff --git a/templates/presentation-video/.gitignore b/templates/presentation-video/.gitignore index 32459b3..3b4c625 100644 --- a/templates/presentation-video/.gitignore +++ b/templates/presentation-video/.gitignore @@ -2,5 +2,6 @@ node_modules/ out/ stills/ takes/*.mp3 +takes/superseded/ __pycache__/ env/*.env diff --git a/templates/presentation-video/playbook.md b/templates/presentation-video/playbook.md index 1b8b669..00ee6b0 100644 --- a/templates/presentation-video/playbook.md +++ b/templates/presentation-video/playbook.md @@ -112,12 +112,12 @@ step that changes a delivered file. | Step | Actor and target | Condition / action | Expected evidence | Failure / next step | |---|---|---|---|---| -| P1 | Author, project | `python3 tools/verify_speech.py --samples`. No line `voice them first:` printed: go to P2. Azure: `python3 tools/voice_azure.py --only `; a person listens to each of these lines (an assistant hands the file names under `public/audio/` to the author and waits); then `python3 tools/verify_speech.py --only `. ElevenLabs: no sample voicing exists; go to P2; P4 is the first key-term check | Each key term heard correctly; `0 with an unrecognized key term` | Wrong term: correct `pronunciation.json`, repeat P1. Lines `below similarity`: a person listens to each; wrong: correct `pronunciation.json`, repeat P1; right: note the line in `review.md` | +| P1 | Author, project | `python3 tools/verify_speech.py --samples`. No line `voice them first:` printed: go to P2. Azure: `python3 tools/voice_azure.py --only `; a person listens to each of these lines (an assistant hands the file names under `public/audio/` to the author and waits); then `python3 tools/verify_speech.py --only `. ElevenLabs: no sample voicing exists; go to P2; P4 is the first key-term check | Each key term heard correctly; `0 with an unrecognized key term` | Wrong term: correct its entry in `pronunciation.json`, one attempt each in this order, and repeat P1 after each: a phonetic entry (`ipa`) or a respelling (`speak`), then a language mark (`lang`); an entry takes effect through one field only, in the order `ipa`, `speak`, `lang`, so remove the earlier field when trying the next one (Azure: `voice_azure.py --only` then prints the line as `new`). Still wrong: another voice is an owner decision (`speech.voice` in the profile; every line is voiced and charged again; repeat Before starting). Still wrong with that voice: stop and escalate. Lines `below similarity`: a person listens to each; wrong: the same order of attempts; right: note the line in `review.md` | | P2 | Author, project | Decision: `python3 tools/profile.py --get speech.provider` and `python3 tools/profile.py --get speech.mode` | `azure` and `line`: P2a. `elevenlabs` and `scene`: P2b | Any other pair: stop; correct the profile; repeat Before starting | | P2a | Author, Azure | `python3 tools/voice_azure.py` | `N lines, … new` | Stops with `stopped at :`: go to R1 | -| P2b | Author, connector | `python3 tools/split_takes.py prompts`; for each scene without a stored take, generate the printed passage once through the connector with the profile's voice, wait until it is done, and store it at once as `takes/-take1.mp3`; transcribe each take to `takes/-take1.words.json` (a list of `{"word", "start", "end"}`) with ; `python3 tools/split_takes.py` | `: (match 0.90 or higher), N lines` per scene | Generation error or timeout: go to R2. Take rejected: go to R3 | +| P2b | Author, connector | `python3 tools/split_takes.py prompts`; for each scene without a stored take, generate the printed passage once through the connector with the profile's voice, wait until it is done, and store it at once as `takes/-take1.mp3` (a take under `takes/superseded/` counts: use the next free number); transcribe each take to `takes/-take1.words.json` (a list of `{"word", "start", "end"}`) with ; `python3 tools/split_takes.py` | `: (match 0.90 or higher), N lines` per scene | Generation error or timeout: go to R2. `.words.json is missing; transcribe the take first`: transcribe that take and run the command again; no new generation. Take rejected: go to R3 | | P3 | Author, project | `python3 tools/timeline.py && python3 tools/measure.py pace` | `PASSED` | `text changed after voicing` or missing sound: repeat P2. `OUT OF RANGE`: go to R6 | -| P4 | Author, project | `python3 tools/verify_speech.py` | `0 with an unrecognized key term` | Unrecognized key term: correct `pronunciation.json`, repeat from P2. Lines `below similarity`: a person listens to each; wrong: correct `pronunciation.json`, repeat from P2; right: note the line in `review.md`. ElevenLabs (P2b), instead of repeating from P2: the stored take keeps the wrong sound, and only a respelling (`speak` in `pronunciation.json` or in the line) changes the passage. After the correction and after the author agrees (it is charged), generate one new take of the affected scene from `python3 tools/split_takes.py prompts `, store it as `takes/-take.mp3`, transcribe it to `takes/-take.words.json`, run `python3 tools/split_takes.py ` (see the take rule under Correction of a delivered video), delete that scene's read-back word files `public/audio/-*.words.json`, then P3 and P4. Still wrong after that: stop and escalate | +| P4 | Author, project | `python3 tools/verify_speech.py` | `0 with an unrecognized key term` | Unrecognized key term: correct `pronunciation.json` in the order of attempts given in P1, repeat from P2 after each. Lines `below similarity`: a person listens to each; wrong: the same order, repeat from P2; right: note the line in `review.md`. ElevenLabs (P2b), instead of repeating from P2: the stored take keeps the wrong sound, and only a respelling (`speak` in `pronunciation.json` or in the line) changes the passage. After the correction and after the author agrees (it is charged), generate one new take of the affected scene from `python3 tools/split_takes.py prompts `, store it as `takes/-take.mp3`, transcribe it to `takes/-take.words.json`, run `python3 tools/split_takes.py ` (see the take rule under Correction of a delivered video), then P3 and P4 (`split_takes.py` removes that scene's read-back word files, so P4 transcribes the new sound; before P4, `ls public/audio/-*.words.json` lists no file). Still wrong after that: stop and escalate | | P5 | Author, project | `node tools/stills.mjs stills`; look at every still; set `"inspected": true` for it in `stills/stills.json`, or write the defect into its `"finding"`; `python3 tools/check_review.py` | `N of N stills inspected without finding` | Defect: correct the scene, `node tools/stills.mjs stills `, repeat P5 for it | | P6 | Author | Decision: `python3 tools/profile.py --get render.host` | Prints a host and the render-machine check of Before starting succeeded: P6a. Empty, or the check fails: P6b | | | P6a | Author, render machine | `tools/render-remote.sh` | `done in … s: out/.mp4` | Interrupted or unreachable: go to R4 | @@ -128,11 +128,10 @@ step that changes a delivered file. | P8b | Author, project | Update the project `README.md`: title, audience, length and date; chapters with time marks from `out/chapters.txt`; sources with the date read (story video: the edition and the manuscript revisions instead); what is evidenced, approximated and invented; voice, provider and mode; ; what makes the video stale | All seven items present | Item missing: complete it before P9 | | P9 | Reviewer | Gate 2 of `presentation-video-review` | `review.md`: `Gate 2: passed on ` | Picture, sound or file finding: return to the step P1 to P8 that owns it. Wording finding, tutorial: stop; `tutorial-video-scripting`; start again at Before starting. Wording finding, story: stop; the story scripting skill and the author, never `tutorial-video-scripting`; the changed line arrives from there; start again at Before starting | | P10 | Author, | Copy the file measured in P8 to `/.new` with ; compute on the local file and on the copy | Both checksums equal | Not equal: delete the `.new` copy and copy once more. Not equal again: stop and escalate; the delivered file is untouched | -| P10b | Author, | Rename an existing `` to `.previous`, then `.new` to `` | `` has the checksum from P10 | Rename fails: rename `.previous` back; stop | +| P10b | Author, | Only while `.new` exists (it is gone: P10b is done, go to P11). Rename an existing `` to `.previous`, then `.new` to `` | `` has the checksum from P10 | Rename fails: rename `.previous` back if the first rename was done (first delivery: nothing to restore, `.new` stays); stop and escalate | | P11 | Author, | Compute on `/` | Equals the local checksum | Not equal: restore `.previous` (first delivery, none exists: rename `` to `.failed`); stop and escalate | -No step deletes working files other than the read-back word files named in -the take rule. `public/audio/`, `src/audio-manifest.json`, +No step deletes a working file that a later correction reuses. The voicing tools remove sound that is no longer used, together with its read-back word file: `voice_azure.py`, run without `--only`, the files of changed lines; `split_takes.py` every file of each scene it cuts. R4 deletes render outputs under `out/`. `public/audio/`, `src/audio-manifest.json`, `src/timeline.json`, `takes/`, `out/captions.vtt`, `out/chapters.txt` and `review.md` are kept: a later correction reuses them. @@ -143,38 +142,44 @@ story: the story scripting skill and the author), and `review.md` records gate 1 for it. Run Before starting, then P2 to P11. - P2a requests only the changed line. -- P2b: after the author agrees, one new take of that scene, stored under the - next free number `takes/-take.mp3` with its own word file. Never +- P2b: after the author agrees, generate one new take of the changed scene + from `python3 tools/split_takes.py prompts `, store it under the + next free number `takes/-take.mp3` and transcribe it to its own + word file. Then run `python3 tools/split_takes.py ` for that scene + only: a run without a scene cuts every scene again and removes every + read-back word file, so P4 transcribes the whole video again. Never overwrite an existing take: its word file would no longer match the sound. The line `split_takes.py` prints for the scene must name the new take. If it names an older take, move that scene's older takes with their word files to `takes/superseded/` (the tool reads only `takes/-take*.mp3`) and - run `python3 tools/split_takes.py ` again. Before P4, delete that - scene's read-back word files `public/audio/-*.words.json`: an - unchanged line keeps its file name, and `verify_speech.py` does not - transcribe a sound file again while a word file with its name exists. + run `python3 tools/split_takes.py ` again. An unchanged line keeps its file name; the tool removes that scene's read-back word files with the old sound, so P4 transcribes the new sound (before P4, `ls public/audio/-*.words.json` lists no file). - P5: `node tools/stills.mjs stills ` and inspect that scene's stills. A run without a scene resets every inspection mark. ## Interruption, recovery and rollback Completed work is recognized by its files. P2a and P3 to P8 may be run again; -P2a requests only lines without a file. P2b is charged per generation: a +P2a requests only lines without a file. P5 is resumed with +`python3 tools/check_review.py` and `node tools/stills.mjs stills ` for +the scenes it names: a run without a scene resets every inspection mark and +finding. P2b is charged per generation: a scene with a file `takes/-take.mp3` is never generated again in a -rerun; repeat only the transcription and `python3 tools/split_takes.py`. +rerun; transcribe only takes that have no word file and run +`python3 tools/split_takes.py ` for each scene whose line +`: (match …)` was not printed. | ID | Situation | Recognize | Action | |---|---|---|---| | R1 | Voicing stopped | Message names the scene and line reached; finished files are in `public/audio/` | `still rate limited`: wait, run P2a again; finished lines are not requested again. `provider not reachable`: check the network, run P2a again. `the provider rejected the key` or `provider answered HTTP `: run `python3 tools/voice_azure.py --check`; still rejected: escalate. `credentials accepted`: run P2a once more; it stops again at the same line with the same message: stop and escalate with the output | | R2 | Connector generation failed or timed out | No file stored for the scene | Use to find the existing generation and fetch its result. Start a new generation only after the author agrees: each one is charged | -| R3 | Take rejected | `match` below the profile's threshold, or `line N was not heard` | The scene's existing sound is untouched. Listen to the take. After the author agrees (it is charged), request one new take, store it under the next free number as `takes/-take.mp3` (never overwrite a take) and transcribe it to `takes/-take.words.json` with ; `python3 tools/split_takes.py ` chooses the better one. Second take rejected too: stop and escalate. Do not lower the threshold to pass | -| R4 | Render interrupted | The command ended without its last line (`rendered: …` or `done in …`). An `out/.mp4` from an earlier render is not the result | Delete `out/raw.mp4` and any earlier `out/.mp4` and `out/-with-opening.mp4`, then run P6 again; after P6a, first repeat the render-machine check of Before starting (it fails: P6b). No partial file is a result | -| R5 | Delivery measurement failed | Last line `FAILED`; the failing row shows `FAIL` (file), `OUT OF RANGE` (pace) or `N outside ±` (pauses) | Pace: R6. Resolution or frame rate: correct `picture` in the profile, `python3 tools/timeline.py`, then P5 and P6. Duration or pauses: `python3 tools/timeline.py`, then P6 and P7. Loudness or peak: P6 once. Sound track: R4. With an opening: `python3 tools/measure.py all out/.mp4`. If `out/.mp4` passes and only the file with the opening fails, the opening sequence is the cause: correct that file, then P7. The same row fails a second time: stop and escalate; do not change a profile limit to pass | +| R3 | Take rejected | `split_takes:` followed by `matches the script only`, `was not heard in the take`, `no word recognized` or `no pause found` | The scene's existing sound is untouched. Listen to the take. After the author agrees (it is charged), request one new take, store it under the next free number as `takes/-take.mp3` (never overwrite a take) and transcribe it to `takes/-take.words.json` with ; Unless the message was `matches the script only`, first move every earlier take of that scene with its word file to `takes/superseded/` (these messages do not name the take; count the takes there too when choosing the next free number): the tool uses the take with the highest word match, and a take that drops a short line can score above a complete one. Then `python3 tools/split_takes.py `; the printed line must name the new take. Then run the same command for each scene whose line was not printed, and continue with P3. Second take rejected too: stop and escalate. Do not lower the threshold to pass | +| R4 | Render interrupted | The command ended without its last line (`rendered: …` or `done in …`). An `out/.mp4` from an earlier render is not the result | First make sure no render is still running. After P6b: `pgrep -fl "remotion render"` on the authoring machine prints nothing. After P6a: `ssh 'pgrep -fl "remotion render"'` prints nothing (the host cannot be reached: P6b). A process is listed: wait one minute and repeat; still listed after five minutes: stop and escalate; ending a process on the render machine is the owner's decision. Then delete `out/raw.mp4` and any earlier `out/.mp4` and `out/-with-opening.mp4` in the project, and run P6 again; after P6a, first repeat the render-machine check of Before starting (it fails: P6b). The render ends without its last line a second time: after P6a take P6b once; after P6b stop and escalate with the output. No partial file is a result. Not rehearsed: R4 after P6a | +| R5 | Delivery measurement failed | Last line `FAILED`; the failing row shows `FAIL` (file), `OUT OF RANGE` (pace) or `N outside ±` (pauses), or the line before it is `has no sound track or cannot be read` | Pace: R6. Resolution or frame rate: correct `picture` in the profile, `python3 tools/timeline.py`, then P5 and P6. Duration or pauses: `python3 tools/timeline.py`, then P6 and P7. Loudness or peak: P6 once. Sound track, or `has no sound track or cannot be read`: the file is not a result; with an opening P7 once more, still the same: R4. After any of these actions continue through P7 to P8; with an opening the joined file is made again in P7a before it is measured. With an opening: `python3 tools/measure.py all out/.mp4`. If `out/.mp4` passes and only the file with the opening fails, the opening sequence is the cause: correct that file, then P7. The same row fails a second time: stop and escalate; do not change a profile limit to pass | | R6 | Pace out of range | `pace … OUT OF RANGE [low, high]` in the output of `tools/measure.py` | Story video: never change wording, tone or order of a line. Azure: `python3 tools/probe_settings.py rate=` (short paid requests); keep the setting under `speech.settings` in the profile only if its last line is exactly `EFFECTIVE` (a line starting `NOT EFFECTIVE` means: do not keep it); then repeat P2 and P3 (a changed setting voices every line again). ElevenLabs: no pace setting is defined; stop and escalate. Tutorial only: a changed wording is produced by `tutorial-video-scripting`, then start again at Before starting (script check and gate 1 for the changed script). Story line that needs other words, or no effective setting: stop and return to the story scripting skill and the author. The pause value does not change the pace measurement. Changing `pace_wpm` in the profile or under `overrides` in `video.json` is an owner decision recorded in the project `README.md`, not a fix the operator chooses | Rollback: no delivered file at is changed before P10b -(P10 only adds `.new`). Locally P2 -replaces the sound of changed lines, the Scenes check, P3 and P7a rewrite `src/timeline.json`, +(P10 only adds `.new`). Locally P2a +replaces the sound of changed lines and P2b the sound of every scene it cuts, each with its read-back word files, the Scenes check, P3 and P7a rewrite `src/timeline.json`, `out/captions.vtt` and `out/chapters.txt`, and P6 and P7a overwrite `out/.mp4` and `out/-with-opening.mp4`. After P10b the previous delivered file is `.previous`; keep it until P11 has passed. After P11 it stays until the next delivery @@ -185,20 +190,21 @@ replaces it; removing it earlier is the owner's decision. Escalate to through when `--check` still reports a rejected key, when P2a stops twice at the same line although `--check` accepts the credentials, when P2a stops with `still rate limited` on three separate -runs, when a second take is rejected, when a copy mismatches twice, when the delivered file mismatches in P11, +runs, when a second take is rejected, when a render fails twice or a render process does not end in R4, when a copy mismatches twice, when a rename fails in P10b, when the delivered file mismatches in P11, when a pace range cannot be met in R6 without an owner decision, when the same measurement row fails twice, when a line is still wrong in P4 after one new take (ElevenLabs), or when a key term stays wrong after a -phonetic entry, a language mark and a second voice. Preserve: the command -output of the failed step, `out/measure.json`, the rejected take and its word -file. Never include the env file or a key. +phonetic entry or respelling, a language mark and a second voice (the order of attempts in P1). Preserve: the command +output of the failed step, `out/measure.json` (not written when the file could not be read; a file of that name is then from P3 and no evidence for the failed file), every take of the scene with its word file, in `takes/` and +`takes/superseded/`. Never include the env file or a key. ## Completion Success: the file at has the checksum of the local file, `review.md` records gate 2 as passed, and the project record is complete. Stop state: a step that fails before P10b leaves the delivered file -untouched; a failure in P10b or P11 is undone by restoring `.previous`. +untouched; a failure in P10b or P11 is undone by restoring `.previous`; on a first +delivery there is none, and a mismatching file is renamed to `.failed`. ## Maintenance and sources diff --git a/templates/presentation-video/tools/measure.py b/templates/presentation-video/tools/measure.py index f78db77..d49c9fb 100755 --- a/templates/presentation-video/tools/measure.py +++ b/templates/presentation-video/tools/measure.py @@ -12,6 +12,7 @@ python3 tools/measure.py all out/video.mp4 [--offset SECONDS] """ import argparse +import subprocess import sys from pathlib import Path @@ -128,6 +129,11 @@ def main(argv=None) -> int: except (audio.ToolMissing, profile_mod.ProfileError, FileNotFoundError) as error: print(f"measure: {error}", file=sys.stderr) return 1 + except (ValueError, subprocess.CalledProcessError): + # ffprobe or the loudness pass could not read the file: no sound track, or a partial file + print(f"measure: {args.video} has no sound track or cannot be read", file=sys.stderr) + print("FAILED") + return 1 report["passed"] = not failed project.write_json(root / "out" / "measure.json", report) print("PASSED" if not failed else "FAILED") diff --git a/templates/presentation-video/tools/split_takes.py b/templates/presentation-video/tools/split_takes.py index fb200fc..3399f19 100755 --- a/templates/presentation-video/tools/split_takes.py +++ b/templates/presentation-video/tools/split_takes.py @@ -103,6 +103,19 @@ def choose(spoken: list[str], takes: list[tuple[Path, list[dict]]], threshold: f return best +def replace_scene_sound(out_dir: Path, scene: str, staging: Path) -> None: + """Replace every sound file of one scene by the pieces cut into staging.""" + own = speech.scene_file(scene) + for old in out_dir.glob("*.mp3"): + if own.fullmatch(old.name): + old.unlink() + # A line whose text is unchanged keeps its file name, but the sound is new: + # an old read-back transcription beside it would be read as the new sound's. + old.with_suffix(".words.json").unlink(missing_ok=True) + for piece in sorted(staging.glob("*.mp3")): + shutil.move(str(piece), out_dir / piece.name) + + def main(argv=None) -> int: argv = sys.argv[1:] if argv is None else argv root = project.ROOT @@ -145,17 +158,14 @@ def main(argv=None) -> int: "-i", str(take), "-ar", "48000", "-ac", "1", "-b:a", "192k", str(target)], check=True) entries_out.append({"file": f"audio/{target.name}", "hash": digest, "words": project.words(lines[i]["text"]), **voice_azure.measure_file(target)}) - own = speech.scene_file(scene) - for old in out_dir.glob("*.mp3"): - if own.fullmatch(old.name): - old.unlink() - for piece in sorted(Path(staging).glob("*.mp3")): - shutil.move(str(piece), out_dir / piece.name) + replace_scene_sound(out_dir, scene, Path(staging)) manifest[scene] = entries_out + # written after every scene: a later scene that is rejected must not leave + # this scene's new sound on disk without its manifest entry + order = {key: i for i, key in enumerate(narration)} + manifest = dict(sorted(((k, v) for k, v in manifest.items() if k in order), key=lambda kv: order[kv[0]])) + project.write_json(root / "src" / "audio-manifest.json", manifest) print(f"{scene}: {take.name} (match {ratio:.2f}), {len(lines)} lines") - order = {key: i for i, key in enumerate(narration)} - manifest = dict(sorted(((k, v) for k, v in manifest.items() if k in order), key=lambda kv: order[kv[0]])) - project.write_json(root / "src" / "audio-manifest.json", manifest) except (TakeRejected, FileNotFoundError, audio.ToolMissing, profile_mod.ProfileError, speech.PronunciationError, subprocess.CalledProcessError, KeyError) as error: print(f"split_takes: {error}", file=sys.stderr) diff --git a/templates/presentation-video/tools/voice_azure.py b/templates/presentation-video/tools/voice_azure.py index 3aa2f4c..ce9d86f 100755 --- a/templates/presentation-video/tools/voice_azure.py +++ b/templates/presentation-video/tools/voice_azure.py @@ -176,6 +176,8 @@ def voice(narration: dict, entries: list[dict], prof: dict, audio_dir: Path, syn for stale in audio_dir.glob("*.mp3"): if OWNED.match(stale.name) and stale.name not in used: stale.unlink() + # the read-back transcription of a removed sound describes nothing any more + stale.with_suffix(".words.json").unlink(missing_ok=True) return {"manifest": manifest, "new": new, "characters": characters} diff --git a/templates/story-vault/90-templates/review.md b/templates/story-vault/90-templates/review.md index 51d716b..9e454e6 100644 --- a/templates/story-vault/90-templates/review.md +++ b/templates/story-vault/90-templates/review.md @@ -21,9 +21,9 @@ voice_revision: unset ## Voice review -Fill this section only for a voice review. State the voice sheet revision and the character voice cards used. Every finding cites a passage and either a clause of the sheet or a card, or a named default of the drafting skill marked "method default, not sheet". +Fill this section only for a voice review. State the voice sheet revision and the character voice cards used. Every finding cites a passage and either a clause of the sheet or a card, or a named default of the drafting skill marked "method default, not sheet", or a pattern of the #1 prose rule marked "prose rule #1". -| Passage (file and location) | Clause, or "method default, not sheet" | Class | Note | +| Passage (file and location) | Clause, "method default, not sheet" or "prose rule #1" | Class | Note | | --- | --- | --- | --- | Classes: unintended deviation, deliberate exception, sheet gap, candidate sheet change. diff --git a/tests/test_natural_prose.py b/tests/test_natural_prose.py new file mode 100644 index 0000000..ec31cee --- /dev/null +++ b/tests/test_natural_prose.py @@ -0,0 +1,102 @@ +"""Writing rule #1 (natural prose) is present and every skill of the family map that writes or judges text carries it.""" +import json +from pathlib import Path +import re +import unittest + +ROOT = Path(__file__).resolve().parents[1] +RULE = "shared/policies/natural-prose.md" +STORY_ANCHOR = "rules.md#1-prose-rule-natural-prose" +# Skills of the family map that write no text: one renders a PDF, one voices and renders a video. +NO_TEXT = {"documentation-pdf", "presentation-video-production"} +SHARED_CARRIERS = [ + "shared/media/spoken-style.md", + "shared/policies/reader-oriented-output.md", + "shared/policies/writing-depth.md", + "shared/policies/lifecycle-selection.md", + "shared/story/rules.md", + "README.md", +] +SEVEN = ["a contrast with nothing", "a one-line closer", "a list of three", "a participle phrase at a sentence end", + "a stock word", "a bold label", "a line addressed to the person who asked"] +LINK = re.compile(r"\]\(([^)#\s]+)") + + +def links(path: Path) -> set[str]: + return {str((path.parent / target).resolve().relative_to(ROOT)) for target in LINK.findall(path.read_text()) + if "://" not in target and (path.parent / target).resolve().is_relative_to(ROOT)} + + +def families() -> dict[str, list[str]]: + hub = (ROOT / "shared/policies/writing-mode.md").read_text() + return json.loads(hub[hub.index("```json") + 7:hub.rindex("```")])["families"] + + +class NaturalProse(unittest.TestCase): + def test_the_rule_states_its_rank_its_groups_and_its_scope(self) -> None: + text = (ROOT / RULE).read_text() + self.assertTrue(text.startswith("# Writing rule #1: natural prose")) + self.assertIn("comes\nbefore every other writing rule", text) + headings = [line[3:] for line in text.splitlines() if line.startswith("## ") and line != "## Contents"] + contents = text[text.index("## Contents"):text.index("## Why readers")] + self.assertEqual(headings, [line[2:] for line in contents.splitlines() if line.startswith("- ")]) + for group in ("### A. Staged insight", "### B. Even rhythm", "### C. Inflation in place of fact", + "### D. Formatting as decoration", "### E. Left over from the chat"): + self.assertIn(group, text) + for mode in ("Reader-oriented text, including every reply", "Working notes", "Manuscript", + "Narration of a video", "Machine-read output"): + self.assertIn(f"| {mode}", text) + + def test_the_rule_links_into_no_family(self) -> None: + self.assertEqual(set(), links(ROOT / RULE)) + + def test_every_skill_of_the_family_map_that_writes_text_carries_the_rule(self) -> None: + map_ = families() + for name in map_["reader"] + map_["form"]: + if name in NO_TEXT: + continue + with self.subTest(skill=name): + self.assertIn(RULE, links(ROOT / "skills" / name / "SKILL.md")) + for name in map_["story"]: + with self.subTest(skill=name): + self.assertIn(STORY_ANCHOR, (ROOT / "skills" / name / "SKILL.md").read_text()) + + def test_shared_files_and_the_readme_link_the_rule(self) -> None: + for carrier in SHARED_CARRIERS: + with self.subTest(carrier=carrier): + self.assertIn(RULE, links(ROOT / carrier)) + self.assertIn("## #1 prose rule: natural prose", (ROOT / "shared/story/rules.md").read_text()) + + def test_the_story_files_name_the_same_groups_for_narration(self) -> None: + for path in (RULE, "shared/story/rules.md", "skills/story-drafting/SKILL.md", "skills/story-voice-review/SKILL.md"): + with self.subTest(path=path): + text = " ".join((ROOT / path).read_text().split()) + self.assertRegex(text, r"groups A, C and E") + self.assertRegex(text, r"(?i)group B.{0,40}where several of its patterns stand in one passage") + # fragments and repetition stay devices of prose in every one of them + self.assertIn("unless the sheet excludes", (ROOT / RULE).read_text()) + self.assertIn("unless the sheet excludes it", (ROOT / "shared/story/rules.md").read_text()) + self.assertIn("the prose rule does not make it one", (ROOT / "skills/story-voice-review/SKILL.md").read_text()) + + def test_the_delivery_check_is_the_same_in_the_rule_and_the_prose_skill(self) -> None: + def items(path: str, heading: str) -> list[str]: + text = (ROOT / path).read_text() + section = " ".join(text[text.index(heading):].split()) + listed = section[section.index(":") + 1:section.index(".", section.index(":"))] + return [item.strip() for item in listed.split(",")] + rule = items(RULE, "## Check before delivery") + self.assertEqual(SEVEN, rule) + self.assertEqual(rule, items("skills/human-prose-drafting/SKILL.md", "## Chunk check")) + + def test_the_prose_skill_description_names_short_texts_and_its_limits(self) -> None: + text = (ROOT / "skills/human-prose-drafting/SKILL.md").read_text() + description = next(line for line in text.splitlines() if line.startswith("description:")) + for part in ("no other writing skill covers it", "email", "announcement", "commit or pull-request description", + "writing rule #1", "supporting skill within documentation-authoring", + "Not for story manuscripts or in-world text."): + self.assertIn(part, description) + self.assertNotIn("release note", description) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_presentation_video.py b/tests/test_presentation_video.py index b5cb02e..9dd07d7 100644 --- a/tests/test_presentation_video.py +++ b/tests/test_presentation_video.py @@ -389,6 +389,18 @@ def test_one_changed_line_costs_one_request_and_removes_the_stale_file(self): self.assertEqual(1, result["new"]); self.assertEqual(4, len(self.calls)) self.assertEqual(3, len(list(self.dir.glob("*.mp3")))) + def test_a_removed_sound_file_takes_its_read_back_transcription_along(self): + self.run_voice() + for sound in self.dir.glob("*.mp3"): + sound.with_suffix(".words.json").write_text("[]") + changed = copy.deepcopy(self.narration); changed["a"][1]["text"] = "Two, corrected." + self.run_voice(changed) + sounds = {p.stem for p in self.dir.glob("*.mp3")} + transcriptions = {p.name[:-len(".words.json")] for p in self.dir.glob("*.words.json")} + # the two unchanged lines keep theirs; the replaced line's is gone and the new sound has none yet + self.assertEqual(2, len(transcriptions)) + self.assertTrue(transcriptions < sounds) + def test_foreign_files_in_the_audio_folder_are_left_alone(self): (self.dir / "jingle.mp3").write_bytes(b"x") self.run_voice() @@ -642,6 +654,26 @@ def test_prompt_is_one_line_per_narration_line_with_one_tone_tag(self): self.assertEqual("[warm] Die I T hilft.\nDanke!", text) +class TakeReplacement(unittest.TestCase): + def test_a_recut_scene_loses_its_old_sound_and_read_back_transcriptions(self): + with tempfile.TemporaryDirectory() as tmp: + out = Path(tmp) / "audio"; staging = Path(tmp) / "staging" + out.mkdir(); staging.mkdir() + kept = speech.audio_name("a", 0, "1111111111"); changed = speech.audio_name("a", 1, "2222222222") + other = speech.audio_name("b", 0, "3333333333") + for name in (kept, changed, other): + (out / name).write_bytes(b"old") + (out / name).with_suffix(".words.json").write_text("[]") + new = speech.audio_name("a", 1, "4444444444") + for name in (kept, new): + (staging / name).write_bytes(b"new") + split_takes.replace_scene_sound(out, "a", staging) + self.assertEqual({kept, new, other}, {p.name for p in out.glob("*.mp3")}) + self.assertEqual(b"new", (out / kept).read_bytes()) + # only the other scene keeps a transcription: the unchanged name carries new sound + self.assertEqual([Path(other).with_suffix(".words.json").name], [p.name for p in out.glob("*.words.json")]) + + @unittest.skipUnless(FFMPEG, "ffmpeg and ffprobe are required") class WithMediaTools(unittest.TestCase): def setUp(self): diff --git a/tests/test_writing_mode.py b/tests/test_writing_mode.py index f894ba7..2d849a4 100644 --- a/tests/test_writing_mode.py +++ b/tests/test_writing_mode.py @@ -369,7 +369,7 @@ def test_policy_block_states_the_contract(self): # A story video is scripted from the video project template and handed to the form skills. self.assertEqual( {"prefixes": STORY_SIDE_PREFIXES + ["templates/presentation-video/"], - "files": [HUB, "shared/policies/proportionality.md", + "files": [HUB, "shared/policies/natural-prose.md", "shared/policies/proportionality.md", "skills/verification-before-completion/SKILL.md", "skills/presentation-video-production/SKILL.md", "skills/presentation-video-review/SKILL.md", diff --git a/third-party/sources.lock.json b/third-party/sources.lock.json index a17b490..4c68a4c 100644 --- a/third-party/sources.lock.json +++ b/third-party/sources.lock.json @@ -12,7 +12,7 @@ "sha256": "4ac4810254ab36d45419141aeb8e69bf50652cfafe5b2dab947d06d44e5cbf96" }, "copyright": "Copyright (c) 2025 Siqi Chen", - "modification_summary": "Reframed the after-the-fact rewrite procedure as drafting-time constraints for medium and large documentation, condensed the 25 patterns into constraint groups, removed pasted-text and voice-matching modes, and added the chunk check and documentation voice rules.", + "modification_summary": "Reframed the after-the-fact rewrite procedure as drafting-time constraints, condensed the 25 patterns into five groups and moved them into a rule file that applies to every text, extended them from further sources named in that file, removed pasted-text and voice-matching modes, and added the delivery check, the scope by writing mode and the documentation voice rules.", "files": [ { "source_path": "LICENSE", @@ -24,7 +24,14 @@ "source_path": "SKILL.md", "destination_path": "skills/human-prose-drafting/SKILL.md", "source_sha256": "e8269e236bed06ed0fe4824c274112e54950b0cb46b0bafe5e1576ef7c9f93d5", - "destination_sha256": "eb60a8732f86fb1ffb92656700ff4d9aa4b76db6260e68467401133830c7c02c", + "destination_sha256": "26fffdb10b10560bb1e8623efbc4918a060fb103f1d41a4b000eaeb20fa7ce95", + "modification_status": "adapted" + }, + { + "source_path": "SKILL.md", + "destination_path": "shared/policies/natural-prose.md", + "source_sha256": "e8269e236bed06ed0fe4824c274112e54950b0cb46b0bafe5e1576ef7c9f93d5", + "destination_sha256": "f94a75d3b25b226a4e3255185bf1a859bedade50b60c541bad5f31896de69120", "modification_status": "adapted" } ]