From 9b045f554c5077bef694834aabdddbcb58401009 Mon Sep 17 00:00:00 2001 From: Focus Date: Tue, 6 Oct 2026 13:14:54 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=A6=20new=20(skills):=20distill=20huma?= =?UTF-8?q?n-writing=20into=20bowrite=20(material=20gate,=20hard=20bans)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- book/README.md | 2 +- book/docs/decisions/ADR-002-adopt-bowrite.md | 13 ++++++- book/guidelines/writing-style.md | 2 +- skills/README.md | 4 +-- skills/bowrite/SKILL.md | 37 +++++++++++++++++--- 5 files changed, 49 insertions(+), 9 deletions(-) diff --git a/book/README.md b/book/README.md index 34ba103..dc6196d 100644 --- a/book/README.md +++ b/book/README.md @@ -49,7 +49,7 @@ description: Master index of the book — the map of every document. Regenerate ### docs/decisions/ - [ADR-001-adopt-bocode.md](docs/decisions/ADR-001-adopt-bocode.md) — We run this repository on the BoCode workflow — book drives code, code writes back, six phases gate every feature -- [ADR-002-adopt-bowrite.md](docs/decisions/ADR-002-adopt-bowrite.md) — We distill shuorenhua plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well +- [ADR-002-adopt-bowrite.md](docs/decisions/ADR-002-adopt-bowrite.md) — We distill shuorenhua and human-writing plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well - [ADR-003-intent-gates-vs-distrust-gates.md](docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md) — We classify workflow gates by justification — intent gates stay hard, distrust gates soften as models improve; Phase 2 approval becomes gap-based stopping - [ADR-004-template-free-of-instance-records.md](docs/decisions/ADR-004-template-free-of-instance-records.md) — This repository ships template content only — instance working records (notes entries, plans, changelog months) never enter it; a release check enforces the boundary - [README.md](docs/decisions/README.md) — How to write an ADR here — sections, naming, numbering, and when a decision needs a record diff --git a/book/docs/decisions/ADR-002-adopt-bowrite.md b/book/docs/decisions/ADR-002-adopt-bowrite.md index 0f43f81..5e591fa 100644 --- a/book/docs/decisions/ADR-002-adopt-bowrite.md +++ b/book/docs/decisions/ADR-002-adopt-bowrite.md @@ -1,5 +1,5 @@ --- -description: We distill shuorenhua plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well +description: We distill shuorenhua and human-writing plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well --- # ADR-002: Adopt the bowrite writing skill (薄写) @@ -30,3 +30,14 @@ Add a fourth skill, `bowrite`（中文名：薄写 — write thin, write well: - The project's review findings now compound into the skill instead of living in one-off fixes - Three layers must stay distinct: skill = when/how for agents, guideline = what/why for humans, upstream = deep Chinese ruleset — duplication gets reconciled on sight - The ledger needs curation; entries with no recurrences eventually get folded into the general rules + +## Amendment — 2026-10: a second upstream distilled + +bowrite now also distills [human-writing](https://github.com/KKKKhazix/human-writing)（MIT，by KKKKhazix）, the living-voice creation ruleset. What moved in, each compressed to the skill's thin register: + +- **The material gate** — padding is written when material runs out; a from-scratch long draft counts its concrete materials first, and shortage exits are research / ask (≤3 questions) / write shorter, never re-explanation. The 压缩试验 (cut a third, nothing lost ⇒ 注水) is its post-hoc twin. +- **段段有新货** — every paragraph pays new material; re-arguing the previous point in new words fails the deletion test one level up. +- **Voice-and-rhythm craft** — 主干早出, keyword repetition over elegant variation, sentence-length variance, 白话打底. +- **Hard bans scoped to from-scratch public prose only** — pivot scaffolding in any disguise, triple parallelism, lyric verbs on abstract nouns, dash/quote-colon rules, business jargon. Project documents keep their normal rules; the bans never apply to them. + +What stays upstream, deliberately: fiction writing, reality-source verification, and the per-format playbooks（知乎 / 公众号 / 口播 / 诗歌……）— BoCode documents don't need them and the skill stays thin. Policy unchanged: reference third-party skills with attribution, never bundle them; the three-layer split holds. diff --git a/book/guidelines/writing-style.md b/book/guidelines/writing-style.md index 1e55db6..ea84e0d 100644 --- a/book/guidelines/writing-style.md +++ b/book/guidelines/writing-style.md @@ -6,7 +6,7 @@ description: Plain-language writing standard for every book document — fidelit Everything under `book/` (summary, changelog, learn, issue, task, plans, guidelines, docs) is written the same way: like a specific person speaking in a specific situation — not like a model performing writing. Professional is fine; templated is not. -Three layers carry this standard: the **`bowrite` skill**（薄写 — write thin, write well）is the executable form for agents, distilling [shuorenhua](https://github.com/MrGeDiao/shuorenhua) (source, MIT, by MrGeDiao) together with patterns accumulated in this project's own reviews; the upstream shuorenhua skill goes deepest for Chinese and is worth installing if available; this file is the in-project prose fallback when neither skill is loaded. +Three layers carry this standard: the **`bowrite` skill**（薄写 — write thin, write well）is the executable form for agents, distilling [shuorenhua](https://github.com/MrGeDiao/shuorenhua) (MIT, by MrGeDiao) for cleanup and [human-writing](https://github.com/KKKKhazix/human-writing) (MIT, by KKKKhazix) for the from-scratch gates, together with patterns accumulated in this project's own reviews; the upstreams go deeper（shuorenhua for Chinese cleanup, human-writing for long-form creation）and are worth installing if available; this file is the in-project prose fallback when no skill is loaded. ## Fidelity contract — above any style diff --git a/skills/README.md b/skills/README.md index c697eaf..0d7c0b3 100644 --- a/skills/README.md +++ b/skills/README.md @@ -7,7 +7,7 @@ Four self-contained skills implement the BoCode workflow for AI agents. Each is | `bocode` | The entry skill（薄码）: structure map and session discipline — read before coding, write back after | Session start in a BoCode repo; questions about where documents go or how the index works | | `boscope` | The feature-development skill（薄界）: Step-0 requirements brief + six hard-gated phases — scope it thin, gate it hard | "Implement / add / support / change X" with a sparse request | | `book-writeback` | The write-back skill（返写）: templates and quality gates for writing back to the book | Feature wrap-up; "write a summary / learn entry / issue" | -| `bowrite` | The writing skill（薄写）: write documents thin and well — fewer words, same core, natural voice | Writing or revising any document; drafts that smell templated, translated, or strained | +| `bowrite` | The writing skill（薄写）: write documents thin and well — fewer words, same core, natural voice; from-scratch drafts start at the material gate | Writing or revising any document; drafting a document or post from scratch; drafts that smell templated, translated, or strained | Division of labor: **skills say when and how** (executable behavior for the agent); **`book/guidelines/` says what and why** (reference for humans). They reference each other and never duplicate rules. @@ -23,4 +23,4 @@ Copy the four skill directories into your agent's skills folder: cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite / ``` -`bowrite` distills [shuorenhua](https://github.com/MrGeDiao/shuorenhua) (MIT, by MrGeDiao) together with patterns accumulated in this project's own reviews; for deep Chinese cleanups the upstream skill goes further and is worth installing alongside. +`bowrite` distills two upstreams with attribution kept: [shuorenhua](https://github.com/MrGeDiao/shuorenhua) (MIT, by MrGeDiao) for cleanup, and [human-writing](https://github.com/KKKKhazix/human-writing) (MIT, by KKKKhazix) for the from-scratch gates（材料门槛、段段有新货、成稿禁令）— together with patterns accumulated in this project's own reviews. For deep Chinese cleanups or full long-form creation the upstreams go further and are worth installing alongside. diff --git a/skills/bowrite/SKILL.md b/skills/bowrite/SKILL.md index 9b947b5..e09be3e 100644 --- a/skills/bowrite/SKILL.md +++ b/skills/bowrite/SKILL.md @@ -1,6 +1,6 @@ --- name: bowrite -description: BoCode's writing skill (中文名：薄写) — write documents thin and well. Use when writing or revising any book document, README, summary, learn entry, issue, or changelog; when a draft smells like template-speak, translation-ese, or strained cleverness; and whenever text must shrink without losing substance. +description: BoCode's writing skill (中文名：薄写) — write documents thin and well. Use when writing or revising any book document, README, summary, learn entry, issue, or changelog; when a draft smells like template-speak, translation-ese, or strained cleverness; whenever text must shrink without losing substance; and when drafting a document or public post from scratch — the material gate runs before writing. --- # BoWrite（薄写） @@ -14,6 +14,12 @@ Two mandates, always together: 1. **Thin（写薄）**: fewer words, zero information lost. 2. **Well（写好）**: natural, direct, in the reader's language — never clever at the cost of clear. +## The material gate — before any from-scratch draft + +Padding is written when material runs out. So the first thinning happens before writing: count what you actually hold — facts, numbers, actions, quotes, links, first-hand results. A long draft (roughly 1,200+ 字) needs enough distinct material to form a real process, not five ways to restate three ideas. + +Not enough material? Three exits, in order: research what is public; ask the source (at most three questions, once); write shorter. Never pay length with re-explanations, synonym rounds, or "significance" — that is padding being born. The same test works after drafting（压缩试验）: cut a third; if nothing of substance is gone, the draft was 注水. + ## The fidelity contract — before any thinning No rewrite may add facts, drop core facts, or change who is responsible. The following never move: @@ -28,7 +34,7 @@ Thinning that loses facts isn't thinning — it's damage. ## How to write it thin — the method -把书读薄 is a reading craft: strip the book until its skeleton shows, then retell it with the book closed. Writing thin runs the same craft at writing time. Five moves, in order: +把书读薄 is a reading craft: strip the book until its skeleton shows, then retell it with the book closed. Writing thin runs the same craft at writing time. Six moves, in order: ### 1. 提骨架 — extract the skeleton @@ -50,6 +56,10 @@ Adjectives and adverbs convert into concrete facts or get cut: `非常快` → h Thin it, read it once, close it, retell the core. What you can retell is the core that survived; what you can't means you cut into it — put that back. **内容变少，核心没变——核心保没保住，复述说了算。** This is 把书读薄's own test, applied at writing time. +### 6. 段段有新货 — every paragraph pays new material + +Each paragraph must add something the reader didn't have: a fact, an action, an example, a distinction, a consequence. A paragraph that re-argues the previous point in new words fails the deletion test one level up — cut it or merge it. Forward motion comes from material and cause, not from "going deeper" signposts. + ### Worked example 厚（62 字）： @@ -133,14 +143,33 @@ An opening paragraph that previews the document often restates the first section - Found: 引言说"每开一个新会话都从零开始"，问题 1 又说"每个会话从零开始"——引言留钩子，事实归问题 1。 +## Voice and rhythm — for from-scratch writing + +- **Know who is speaking, and why now.** A document has an author with a position: what they did, what they checked, what they are still unsure of. State the load-bearing ones once each; don't perform an author. +- **Answer the reader's next question.** Write each section as the answer to what the previous section raised. Background arrives where it explains a choice — not up front to prove the writer knows a lot. +- **主干早出**： subject and verb before their modifiers. `在经历了长达数年的……以后，最终促使他改变方向的，是一次邀请` → 他折腾了几年没挣到钱；后来老同事找过来，他才换了方向。 +- **Repeat the right word.** The keyword stays the keyword（`修表` stays `修表`）— upgrading it to `这门手艺` then `这项技能` is model-speak. +- **Let lengths breathe.** A ten-character sentence next to a forty-character one is human; all-even sentences sound like a machine keeping time. 白话打底 — plain speech carries it; ornate archaism doesn't. + +## Hard bans — from-scratch public prose only + +A public long-form piece（帖、公众号文章、知乎回答）drafted from scratch clears one stricter layer at delivery, and only there — project documents keep their normal rules（docs use colons and dashes legitimately）: + +- No pivot scaffolding in any disguise: `不是……而是……`、`并非……而是……`、`与其说……不如说……`、`看似……实则……`、`你以为……其实……` — give the judgment from the front, then the grounds (ledger #3 is the cleanup-side version). +- No parallel runs of three or more; two is the limit, the third changes shape or goes. +- No lyric verbs on abstract nouns — time doesn't 保管 details, anxiety has no shape. +- No `——`; colons only to introduce a direct quote（`一句话总结：` is banned）. +- No business-report jargon: `赋能、抓手、闭环、底层逻辑、颗粒度、组合拳` → people, actions, money, time, consequences. + ## Read-back — three passes before done 1. **Fidelity**: protected spans intact, no facts lost, terms stable, nothing reads broken after the cuts. 2. **Thinness**: what got removed — words, or information? Content shrinks, core doesn't. If the core shrank, put it back. 3. **Residue** (only if it still smells): openers, summary-closers, emphasis formulas, cleverness, over-even rhythm. +4. **From-scratch deliverables** (public prose drafted here): the material gate was passed before writing, forward motion holds（段段有新货）, and the hard bans are clear. The finish line is "ready to send" — not "sounds human". Stop there. -## Standing on shuorenhua +## Standing on shuorenhua and human-writing -BoWrite distills [shuorenhua](https://github.com/MrGeDiao/shuorenhua)（MIT，by MrGeDiao）— the fuller plain-language ruleset, especially for Chinese — together with patterns accumulated in this project's own reviews. For deep Chinese cleanups the upstream skill goes further; `book/guidelines/writing-style.md` is the prose fallback inside every project. +BoWrite distills two upstreams, attribution kept: [shuorenhua](https://github.com/MrGeDiao/shuorenhua)（MIT，by MrGeDiao）— the fuller plain-language ruleset, especially for Chinese cleanup — and [human-writing](https://github.com/KKKKhazix/human-writing)（MIT，by KKKKhazix）— the living-voice creation ruleset, from which the material gate, 段段有新货, voice-and-rhythm craft, and the from-scratch hard bans are distilled. Patterns from this project's own reviews ride on top. For deep Chinese cleanup or full long-form creation the upstreams go further and are worth installing alongside; `book/guidelines/writing-style.md` is the prose fallback inside every project.