Doc Editing
Edit documentation and long-form prose to be clear, precise, and easy to scan.
Response Contract
- Deliverable: apply the edits to the target document.
- Chat output: Do not restate the document content in the chat.
Document Model
Definitions used to reason about documents and edits.
Semantic Layers
A document can contain two kinds of description.
Meta description
Constraints on how the document should be written or edited, such as audience, scope, tone, formatting expectations, and must-not-change constraints.
Content description
Subject matter that belongs in the document, including anything the user explicitly requests to be included as part of the document.
Structure Forms
A document can be organized using two structural forms.
Module structure
The document is divided into modules by responsibility. Each responsibility has a stable home.
Enumeration structure
Within one responsibility, items are listed as peers under a single framing.
Editing Standards
Apply these standards throughout the edit. Each standard is single-sourced here and referenced elsewhere by its ID.
layers.distinct — Keep layers distinct
Keep meta description distinct from content description unless meta-level material is explicitly part of the subject matter. If the user explicitly requests that meta-level material be included in the document as content, treat it as content.
meaning.preserve — Preserve meaning
Preserve the document’s meaning, claims, and intent while improving clarity and structure.
facts.no_new — No new facts
Do not introduce new factual content, new claims, or new conclusions that are not present in the source text or explicitly provided by the user.
structure.modules — Stable responsibility modules
Use module structure to assign each major responsibility a stable home. Keep module boundaries clear and headings responsibility-oriented. Place meta-level material that is included as content into a deliberate, clearly bounded module.
structure.enumerations — Peer enumerations only
Use enumeration structure only to list peers within one responsibility. If a list mixes responsibilities, restructure it into module structure.
meta.constraints — Enforce meta constraints
Treat meta description constraints as hard constraints. When a potential improvement would violate a meta constraint, prefer preserving the constraint and choose the least-invasive alternative that still improves clarity.
Workflow
Use a repeatable editing pass.
- Identify the document’s subject and extract meta description constraints. Apply
layers.distinct and meta.constraints.
- Confirm what must be preserved and what additions, if any, the user explicitly requested. Apply
meaning.preserve and facts.no_new.
- Establish or repair module structure for major responsibilities, align headings to responsibilities, and relocate material to its responsible module. Apply
structure.modules.
- Normalize enumerations within each module; convert mixed-responsibility lists into module structure. Apply
structure.enumerations and structure.modules.
- Edit prose for clarity and precision without changing intent or adding facts. Apply
meaning.preserve and facts.no_new.
- Do a final pass for internal consistency and constraint compliance.
- Run acceptance checks.
Acceptance Criteria
A revision is complete only if all checks pass.
- Response: Output satisfies the Response Contract.
- Standards satisfied:
layers.distinct, meaning.preserve, facts.no_new, structure.modules, structure.enumerations, meta.constraints.
1---2name: doc-editing3description: Use when the user asks to edit, polish, or rewrite documentation or long-form prose to improve clarity and structural quality, aiming for publishable text without tone drift or unnecessary structural churn.4---5
6# Doc Editing
7
8Edit documentation and long-form prose to be clear, precise, and easy to scan.
9
10## Response Contract
11
12- Deliverable: apply the edits to the target document.
13- Chat output: Do not restate the document content in the chat.
14
15## Document Model
16
17Definitions used to reason about documents and edits.
18
19### Semantic Layers
20
21A document can contain two kinds of description.
22
23- **Meta description**
24 Constraints on how the document should be written or edited, such as audience, scope, tone, formatting expectations, and must-not-change constraints.
25
26- **Content description**
27 Subject matter that belongs in the document, including anything the user explicitly requests to be included as part of the document.
28
29### Structure Forms
30
31A document can be organized using two structural forms.
32
33- **Module structure**
34 The document is divided into modules by responsibility. Each responsibility has a stable home.
35
36- **Enumeration structure**
37 Within one responsibility, items are listed as peers under a single framing.
38
39## Editing Standards
40
41Apply these standards throughout the edit. Each standard is single-sourced here and referenced elsewhere by its ID.
42
43- **layers.distinct — Keep layers distinct**
44 Keep meta description distinct from content description unless meta-level material is explicitly part of the subject matter. If the user explicitly requests that meta-level material be included in the document as content, treat it as content.
45
46- **meaning.preserve — Preserve meaning**
47 Preserve the document’s meaning, claims, and intent while improving clarity and structure.
48
49- **facts.no_new — No new facts**
50 Do not introduce new factual content, new claims, or new conclusions that are not present in the source text or explicitly provided by the user.
51
52- **structure.modules — Stable responsibility modules**
53 Use module structure to assign each major responsibility a stable home. Keep module boundaries clear and headings responsibility-oriented. Place meta-level material that is included as content into a deliberate, clearly bounded module.
54
55- **structure.enumerations — Peer enumerations only**
56 Use enumeration structure only to list peers within one responsibility. If a list mixes responsibilities, restructure it into module structure.
57
58- **meta.constraints — Enforce meta constraints**
59 Treat meta description constraints as hard constraints. When a potential improvement would violate a meta constraint, prefer preserving the constraint and choose the least-invasive alternative that still improves clarity.
60
61## Workflow
62
63Use a repeatable editing pass.
64
651. Identify the document’s subject and extract meta description constraints. Apply `layers.distinct` and `meta.constraints`.
662. Confirm what must be preserved and what additions, if any, the user explicitly requested. Apply `meaning.preserve` and `facts.no_new`.
673. Establish or repair module structure for major responsibilities, align headings to responsibilities, and relocate material to its responsible module. Apply `structure.modules`.
684. Normalize enumerations within each module; convert mixed-responsibility lists into module structure. Apply `structure.enumerations` and `structure.modules`.
695. Edit prose for clarity and precision without changing intent or adding facts. Apply `meaning.preserve` and `facts.no_new`.
706. Do a final pass for internal consistency and constraint compliance.
717. Run acceptance checks.
72
73## Acceptance Criteria
74
75A revision is complete only if all checks pass.
76
77- **Response**: Output satisfies the Response Contract.
78- **Standards satisfied**: `layers.distinct`, `meaning.preserve`, `facts.no_new`, `structure.modules`, `structure.enumerations`, `meta.constraints`.
majiayu000