Iceberg Editor

Named after Hemingway's iceberg theory: the strength of a document comes from what you cut.

These rules apply to documentation, plans, proposals, READMEs, and any prose. They do not apply to code blocks, inline code, command names, variable names, or URLs.

Input

• /iceberg:edit <file-path> — read the file, apply rules, write it back in place. Resolve relative paths from the current working directory.
• /iceberg:edit <file-path> "intent description" — edit while preserving the intended voice
• /iceberg:edit <file-path> --no-em-dash --no-weakeners --strip-ai-commentary — also apply the opt-in extended rules (any combination, including one alone)
• /iceberg:edit <file-path> --jargon=finance,legal — also drop words from the named bundled packs for this run
• /iceberg:edit — user pastes text; return the rewritten version
• Automatic — apply to every plan and output document before returning it to the user. The automatic pass runs the core 14 rules only — the extended rules require an explicit flag, every time, even on auto-applied edits. Rule 18 is the one exception: it runs on the automatic pass whenever .iceberg/jargon.txt exists, because the file is the user's standing opt-in.

If no intent is provided, infer it from document signals before editing. Three profiles: technical (default), conversational (guides/tutorials — skip Rules 9, 11, 12), executive (summaries/proposals — treat Rules 5, 8, 12, 13 as HIGH priority). Pass intent, inferred profile, and any extended-rule flags through to the subagent for long documents.

Skip: code-only responses, shell output, error messages, stack traces, files under vendor/, node_modules/, or dist/, any document under 50 words.

The 14 Rules

1. Short sentences

Target 15–20 words. At 25 words, find a split point. At 30 words, split unconditionally. Break at conjunctions, relative clauses, or participial phrases.

2. Active voice

Find the actor. Make it the subject. Fix agentless passives too — "is forwarded", "are stored", "was configured" — not just those with an explicit "by" phrase.

• "The config is loaded by the server" → "The server loads the config"
• "Events are forwarded to replicas" → "The coordinator forwards events to replicas"
• Keep passive only when the actor is unknown or irrelevant.

3. Strong verbs, no adverbs

An adverb is a verb you haven't found yet.

• "runs slowly" → "stalls"
• "quickly processes" → "processes"
• If no stronger verb exists, keep the adverb.

4. Delete qualifiers and hedges

Remove: very, quite, somewhat, rather, fairly, essentially, basically, arguably, maybe, perhaps, appears to, tends to, could potentially, a bit, sort of, kind of.

• If the sentence is false without the qualifier, rewrite the sentence — don't just delete the word.

5. Concrete nouns

Replace abstract categories with specific things. Signal words to watch: solution, approach, initiative, framework, experience, value, requirements, functionality, ecosystem, posture, collaboration, improvement.

• "implement a comprehensive solution" → "add a retry loop"
• "improve the developer experience" → "cut the build time to under 10 seconds"
• "handle edge cases" → "handle empty arrays and null values"

6. One idea per sentence

One main clause. Break at "and," "which," "that," or "but" when each side could stand alone.

• "The system fetches the config and then validates it, which can take up to 500ms." → "The system fetches the config. Validation takes up to 500ms."

7. Conditions before instructions

The reader needs to know whether to act before reading what to do. Pattern to fix: "do X if Y" → "if Y, do X".

• "If the cache is cold, run the warm-up script" — not "Run the warm-up script if the cache is cold."
• "If you observe quota exhaustion, reduce the burst limit." — not "Reduce the burst limit if you observe quota exhaustion."

8. Lead with the answer

Put the conclusion in the first sentence. Context and reasoning follow. Never bury the key finding. Exception: do not restructure sections explicitly titled Background, Overview, Context, or How it works — these sections are intentionally ordered from context to conclusion.

9. Second person

Use "you" for instructions. Use the component name for system behavior.

• "You configure the server" — not "We recommend configuring" or "The user should configure"
• "The API returns 404" — not "A 404 will be returned"

10. Simple words

11. No negative framing

State what to do, not what to avoid.

• "Use HTTPS" — not "Don't use HTTP"
• Exception: warnings, known failure modes, and safety-critical instructions.

12. Short paragraphs

2–4 sentences. One topic. Two ideas means two paragraphs.

13. Define or cut jargon

First use: add a brief inline definition. Second use: no definition needed. If a plain equivalent exists, use it throughout.

14. Measure, don't describe

Replace every subjective descriptor with a number or observable fact.

• "fast" → "under 100ms"
• "large" → "over 1GB"
• "improves performance" → "reduces latency by 40%"
• "easy to use" → (delete — let the design show it)

Extended rules — opt-in, off by default

These two sit outside the core 14. Apply a rule only when its flag is present in the invocation — never infer intent to turn one on, and never apply one because the document "seems like" a fit.

15. No em dashes — flag --no-em-dash

Replace every em dash (—) with the punctuation the sentence actually needs. Never leave a bare hyphen where an em dash was doing grammatical work — pick the real replacement.

• "The API is fast — under 50ms — for reads." → "The API is fast (under 50ms) for reads."
• "Ship it — but test it first." → "Ship it, but test it first."
• "The migration failed — the schema had already changed." → "The migration failed. The schema had already changed."

16. No mid-document weakeners — flag --no-weakeners

Remove a sentence or clause that concedes uncertainty about a claim the document just made, when it sits outside a section explicitly labeled Limitations, Caveats, Risks, or Open questions. Distinct from Rule 4: Rule 4 deletes single hedge words inside an otherwise-confident sentence; this rule removes whole clauses that undercut the surrounding claim.

• Real risk information: don't delete it, relocate it. "The migration handles most cases, though we're honestly not sure about the edge cases with nested tenants." → move the nested-tenant risk into a Limitations section, state it as a fact there: "Nested-tenant migrations are unverified."
• Pure filler with no content: delete outright. "We think this should work, but who knows." → delete, or state the claim plainly if it belongs in the document at all.
• Signal phrases: we're still figuring this out, take this with a grain of salt, no promises, could be wrong here, this might not hold up, don't quote us on this, fingers crossed.

17. No AI commentary — flag --strip-ai-commentary

Remove self-referential assistant voice and process narration — anything revealing this document came out of a request-and-response exchange or a development effort, instead of reading as a standalone product artifact for a reader who was part of neither.

Two sub-patterns, both in scope:

• Assistant self-reference: "I've added/created/implemented/fixed...", "I'll now...", "Let me know if you'd like any changes", "Feel free to ask if anything's unclear", "I hope this helps", "As requested/per your request", "Based on our conversation", "Great question!", "Certainly! / Sure! / Of course!" as a sentence opener, "Here's a summary of what I did/changed."
• Dev-cycle narration: "In this PR/commit/change...", "We then implemented/added/built...", "The next step was to...", "As discussed / as mentioned earlier / per our conversation", "In this session / during this work...", a bare "TODO" / "WIP" / "draft — needs review" left in shipped prose.

Rewrite each hit as a statement about the product, not the work: "I've added retry logic to the client" → "The client retries failed requests." "Let me know if you want this expanded" → delete, or if there's a real open question, name it plainly as a question rather than an offer to keep talking.

Do not touch legitimate in-document cross-references — "see the Setup section above," "as shown in Table 2" — those orient a reader inside the document itself and don't reveal how the document was made. Only remove reference to the conversation or development process behind it.

What survives: a genuine Changelog/release-notes document (same exception as Rule 16), and attribution a reader actually needs (an owner to contact, where to file issues).

Rule 18 — Banned jargon (user list)

Runs when .iceberg/jargon.txt exists in the working directory, or when --jargon=<pack>[,<pack>] is passed. With neither, skip it entirely.

Loading the list

Build one merged list before editing:

1. Start empty.
2. For each pack named by an @pack <name> line in .iceberg/jargon.txt, then by --jargon=, read skills/jargon/packs/<name>.txt and add its entries. Try ${CLAUDE_PLUGIN_ROOT}/skills/jargon/packs/<name>.txt first. If that does not resolve, Glob for **/skills/jargon/packs/<name>.txt. If a pack cannot be found, say so in one line and continue without it.
3. Add the entries from .iceberg/jargon.txt itself. A later entry replaces an earlier entry for the same term.
4. Remove every term named by a !term line.

Entry format: term => replacement replaces. A bare term deletes. Lines starting with # are comments. Format details live in skills/jargon/SKILL.md.

Applying the list

• Match whole words and phrases, ignoring case. Inflections match: leverage also catches leveraged and leveraging. Inflect the replacement to fit: "we leveraged the cache" → "we used the cache".
• Replace with the given replacement. A replacement containing <placeholder> text (for example improve <metric>) needs a real value from the document. If the document has none, use the nearest plain wording without the placeholder.
• For a bare entry, delete the word or phrase and rewrite the sentence so it still parses and keeps its meaning. Deleting the word alone is not enough.
• Apply Rule 18 last, after Rules 1–17, so an earlier rewrite cannot bring a listed word back.
• Never change code blocks, inline code, URLs, proper nouns, or text inside quotation marks.
• Do not add content beyond what a replacement or sentence repair needs.

Editing Process

1. Read the full document before changing anything.
2. Apply rules in order, 1 through 14. Earlier rules take priority when they conflict. Apply Rules 15–17 only if their flag was passed — apply them last, after the core 14, since they operate on clause- and punctuation-level content the core rules may have just rewritten. Apply Rule 18 after those, if it is active.
3. Never change: code blocks, inline code, commands, variable names, URLs, proper nouns.
4. Do not add content. Cut, simplify, and restructure only.
5. Preserve all headings, lists, tables, and document structure.
6. Return the complete rewritten document. No preamble, no changelog, no commentary.

Long Documents (over 500 words)

Spawn the iceberg-edit agent. Pass it the full document text, the intent string (if provided), which extended-rule flags (if any) were passed, and the merged jargon list as a [JARGON] block (one term => replacement or bare term per line, already resolved). The skill loads and merges the list so the agent does not parse files. If Rule 18 is inactive, pass [JARGON] as empty. Return the agent's output verbatim as the final result.