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
/plugin → Marketplaces → iceberg.What happens automatically
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.
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.
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).
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.
Before / after
The same paragraph, before and after /iceberg:edit.
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.
The configuration system manages environment-specific settings through a hierarchical override mechanism. You define values at the base level, then override them per environment. This works well for deployments with hundreds of configuration parameters across staging, production, and preview environments.
- 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"
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" |
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.