iceberg guide

Getting started

Install

# via gago-plugins marketplace (recommended)
/plugin marketplace add gagoar/gago-plugins
/plugin install iceberg@gago-plugins
/reload-plugins

# standalone
/plugin marketplace add gagoar/iceberg
/plugin install iceberg@iceberg
/reload-plugins

# update
/plugin update iceberg@gago-plugins
/reload-plugins

After install, iceberg scores every plan Claude produces automatically. Install via gago-plugins to get all gagoar plugins in one marketplace. Auto-update is off by default — enable it in /plugin → Marketplaces → iceberg.

/iceberg:score — read-only analysis

/iceberg:edit — rewrites inline

How it works

What happens automatically

Runs on every plan

After install, /iceberg:score runs on every plan Claude produces before returning it. The score report appears at the top of the response — no user action needed.

Two grades appear side by side: an objective score (all 14 rules at default severity) and an intent-adjusted score (severity tuned to the document's inferred audience). A guide for new users grades differently than a formal API spec, even if they contain the same violations.

To rewrite a scored document: run /iceberg:edit path/to/doc.md. The edit skill applies all 14 rules in order and returns the clean document. No annotations. No changelog.

Output

Reading the score report

ICEBERG SCORE — deployment-guide.md
Assumed intent: conversational onboarding guide
  (signals: tutorial-style steps, "you'll learn" phrasing, casual headers)

                  Objective   Intent-adjusted
Grade:               C             A
Density:         6.2/100w      1.4/100w   (target: ≤4.0)
Violations:         18             4     (14 deprioritized for conversational)
Word count:      290w

VIOLATIONS

Rule 1 — Short sentences  [HIGH / HIGH]  2 violations
  · "The system fetches the config and validates it, which can take up to 500ms
    depending on network conditions and cache state." (34w)

Rule 9 — Second person  [LOW / skip]  2 violations  ← deprioritized for conversational
  · "we recommend configuring…"
  · "our team suggests…"

Rule 13 — Jargon  [MEDIUM / HIGH]  3 violations  ← stricter for conversational readers
  · "idempotent" used without definition

TOP 3 TO FIX (intent-adjusted): jargon (Rule 13), long sentences (Rule 1), passive voice (Rule 2)
Run /iceberg:edit to apply all fixes.

Assumed intentInferred from document signals — structure, tone, vocabulary. Override by passing an explicit string: /iceberg:score doc.md "executive summary"
Objective / AdjustedObjective applies default severities to all 14 rules. Adjusted uses the inferred profile — some rules are deprioritized (skip) or escalated (HIGH) based on audience.
DensityWeighted violations per 100 words. Makes grades comparable across document lengths — a clean 2,000-word spec and a clean 100-word summary both grade A.
TOP 3 TO FIXPrioritized by intent-adjusted severity. Start here when running /iceberg:edit.

Scoring

Grade scale

Grades use violation density — weighted violations per 100 words — so document length doesn't inflate or deflate the score.

Grade	Density (per 100 words)	Meaning
A	≤ 1.0	Publish-ready
B	≤ 4.0	Minor cleanup needed
C	≤ 8.0	Needs work before sharing
D	≤ 15.0	Significant rewrite required
F	> 15.0	Start over

Weighted violations = HIGH×2 + MEDIUM×1 + LOW×0.5. Density = weighted ÷ (word count / 100).

Audience

Intent profiles

The scorer infers intent automatically from structure, tone, and vocabulary. Pass an explicit string to override.

Rule	Technical	Conversational	Executive
5 — Concrete nouns	MEDIUM	MEDIUM	HIGH
8 — Lead with answer	MEDIUM	MEDIUM	HIGH
9 — Second person	LOW	skip	LOW
11 — Negative framing	LOW	skip	LOW
12 — Short paragraphs	LOW	skip	HIGH
13 — Jargon	MEDIUM	HIGH	HIGH

"skip" = violation found and reported but excluded from the weighted count.

Example

Before / after

The same paragraph, before and after /iceberg:edit.

Before

F Grade F

The configuration system was designed in order to facilitate the seamless management of environment-specific settings, and it essentially leverages a hierarchical override mechanism that is quite flexible and arguably one of the most comprehensive solutions available for handling the somewhat complex requirements of modern cloud deployments.

After

A Grade A

The configuration system manages environment-specific settings through a hierarchical override mechanism. Teams define values at the base level, then override them per environment. The mechanism handles hundreds of parameters across staging, production, and preview environments.

What changed

1 sentence (67w) split into 3 sentences — 18w, 12w, 19w
Passive "was designed" → active "manages"
Qualifiers deleted: essentially, quite, very, arguably, tends to, somewhat
Complex words removed: "in order to", "leverage", "facilitate"
Abstract nouns made concrete: "comprehensive solutions" → mechanism described; "complex requirements" → "hundreds of configuration parameters"

Reference

The 14 rules

Applied in order. Code blocks, inline code, command names, variable names, URLs, and proper nouns are never modified.

#	Rule	Example
1	Short sentences	Target 15–20 words. Split at 30.
2	Active voice	"The server loads the config" — not "The config is loaded"
3	Strong verbs, no adverbs	"stalls" — not "runs slowly"
4	No qualifiers or hedges	Delete: very, quite, arguably, tends to, could potentially
5	Concrete nouns	"add a retry loop" — not "implement a comprehensive solution"
6	One idea per sentence	Break at "and," "which," or "but" when each side stands alone
7	Conditions before instructions	"If the cache is cold, run the script" — not the reverse
8	Lead with the answer	Conclusion first. Context follows.
9	Second person	"You configure the server" — not "We recommend"
10	Simple words	use, help, start, stop — not utilize, facilitate, initiate, terminate
11	No negative framing	"Use HTTPS" — not "Don't use HTTP"
12	Short paragraphs	2–4 sentences. One topic.
13	Define or cut jargon	First use gets an inline definition. Plain equivalent beats jargon.
14	Measure, don't describe	"under 100ms" — not "fast"

Plugin development

For developers

⚗️

Testing & calibration

The repo ships with a manual test checklist at TESTING.md and calibration fixtures in examples/eval/. Run /iceberg:score examples/eval/violations.md — expect Grade F, all 14 rules flagged. Run /iceberg:score examples/eval/clean.md — expect Grade A, no false positives. Model comparison results (Haiku vs Sonnet accuracy) are in examples/eval/results.md.