Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
11 changes: 9 additions & 2 deletions FEATURES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

<!-- engineering-method:feature {"schema_version":1,"id":"F-003","name":"Narrated tutorial videos","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.","status":"available","related_backlog_ids":["WM-001"],"updated_at":"2026-11-13T19:21:17Z"} -->
<!-- engineering-method:feature {"schema_version":1,"id":"F-003","name":"Narrated tutorial videos","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.","status":"available","related_backlog_ids":["WM-001"],"updated_at":"2026-11-13T22:30:00Z"} -->
## `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`

<!-- engineering-method:feature {"schema_version":1,"id":"F-004","name":"Story writing family (experimental)","summary":"Nine story- skills with shared story rules and a story vault starter, separated from reader-oriented writing by a per-text writing mode. No story has been written with it; produced text is not measured.","status":"available","related_backlog_ids":["WM-003"],"updated_at":"2026-11-13T19:21:17Z"} -->
Expand All @@ -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`

<!-- engineering-method:feature {"schema_version":1,"id":"F-006","name":"Writing rule #1: natural prose","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.","status":"available","related_backlog_ids":["WM-005"],"updated_at":"2026-11-13T22:30:00Z"} -->
## `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`
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
---
type: reference
audience: Authors and maintainers familiar with their coding assistant and Git
version: 0.4.1
version: 0.5.0
---
# Writing Method

Writing Method provides reader-oriented writing, documentation planning, review, local PDF delivery and narrated tutorial videos for Claude, Codex and OpenCode. A separate, experimental family of skills supports story writing; see [Story writing (experimental)](#story-writing-experimental). Install it on its own or alongside [Engineering Method](https://github.com/phense/engineering-method). Both bundle shared support from [Method Core](https://github.com/phense/method-core); no sibling checkout is needed at runtime.

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 |
Expand Down Expand Up @@ -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 |

Expand Down Expand Up @@ -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

Expand Down
3 changes: 2 additions & 1 deletion THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
76 changes: 71 additions & 5 deletions docs/specs/WM-001-presentation-video/playbook-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<scene>` |
| 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.
Loading
Loading