Edit

About this skill

Built and maintained by Bamboo DCM (bamboodcm.com) — the independent infrastructure for Brazil's corporate and structured credit market, with an intelligence layer on top. We use this skill (and the broader knowledge-systems framework around it) to edit our own writing — memos, board material, investor letters, public posts — at the grade each piece earns.

First public packaging. The methodology and the skill have been used and pressure-tested internally; this is their first release outside the firm. The leg-(d) meaning gate assumes your runtime can spawn independent (blind) reader calls — see § The gate. Bug reports and pushback are wanted.

Comments, improvements, or questions:

• Arthur O'Keefe — arthur@bamboodcm.com
• Felipe Grassi de Moraes — felipe@bamboodcm.com
• Urian Inhauser — urian@bamboodcm.com

License: CC-BY 4.0 — free to share and adapt with attribution.

/edit — the readability editor

Refine an existing draft so it reads as easily as its ideas allow — and prove the edit helped via a gate it can't game. Where a defect/AI-pattern linter lints for defects and a content skill drafts in a brand voice, /edit refines an existing draft to lower reading effort without changing what it says, at a grade the content earns. Voice-neutral: it refines anyone's draft (yours, a colleague's, a counterparty's), not toward one voice.

This skill EXECUTES a published methodology — it does not restate it. The canon is the Readability-Editing Methodology, published alongside this skill in the same library: ../readability-editing-methodology/readability_editing_methodology.md. Read it once on first encounter; this SKILL.md is the runnable orchestration layer on top of it.

Install note. This skill shells out to two deterministic tools — readability_diag.py (the countable-flags diagnostic) and blind_meaning_confirm.py (leg-(d)'s blinding + diff harness) — both co-located in this directory. The skill does not function without them. Both are stdlib-only Python 3.8+ (no pip; standard library only). Install them alongside this SKILL.md — or copy them to the path your shell-out uses — and invoke:

• macOS / Linux: python3 readability_diag.py --json <file>
• Windows: py -3 readability_diag.py --json <file> (or python readability_diag.py ...)

This canonical ships the two tools co-located, so the shell-out paths below read readability_diag.py / blind_meaning_confirm.py. Point them wherever you install the two files.

The executor-fit contract (load-bearing — read first)

This skill is a mix of work-classes, split by the cheapest-executor-per-part principle:

• Deterministic, countable → readability_diag.py (no model). The skill SHELLS OUT to it for the countable flags — readability scores (FK/Fog), sentence-length variance (the Lever-4 rhythm/monotone flag), nominalization density, term-frequency surface, whole-piece antithesis count, subject-verb-gap estimate. The skill does NOT recompute these in-model. Run it:

  python3 readability_diag.py --json <file>          # or:  --json --text "..."
  

• Irreducible judgment → the model (this skill). Intrinsic-vs-extraneous discrimination (methodology §4); the information-density / recovery read (model-assisted, NOT in the tool); the generative rewrite; floor/ceiling calibration; the meaning read it surfaces but never self-certifies.

• Adaptive recovery loop → not needed → not an agent. A single-pass edit + the gate. The one out-of-skill handoff — leg-(d), §The gate — wires as blind_meaning_confirm.py --diff (code, the deterministic blinding + diff-anchoring) + three blind out-of-model readers whose verdicts are combined by a consensus rule (the claim-diff judgment), the meaning-side twin of the readability_diag.py split. A structured handoff, not an agent loop.

The withheld-verdict contract — respect parse_confidence / withheld. The tool emits a parse_confidence and a sentence_segmentation status (trusted / low_confidence / degenerate). When a sentence-dependent flag is withheld (listed in the tool's withheld array, value "unmeasured"), the deterministic verdict is unavailable — the model judgment carries; NEVER fabricate the number. A naive splitter already produced a false "harder" verdict in testing; withholding is the tool refusing to emit a confident wrong number. On a withheld leg-(a), the rhythm half abstains and §4 judgment decides (see § The gate, leg (a)).

Mode

• /edit <text|file> — default: diagnose + propose, read-only. Outputs the lever diagnosis (intrinsic-vs-extraneous split + the dominant 2–3 load sources + per-lever findings) and the proposed refine moves, each with its two-sided floor/ceiling check, plus the predicted gate result. Changes nothing. Includes the STOP / NO-EDIT verdict when the difficulty is intrinsic-only or the prose is at-floor — restraint is a first-class output. (= methodology Steps 1–2.)
• /edit --apply <file> — apply + gate. Applies the refine moves and runs the four-part gate. Outputs the refined text + the gate result, with meaning-preservation handed to the blocking-blind-independent confirm (§ The gate, leg (d)). (= methodology Steps 3–4.)

/edit mirrors a read-only-default / write-on-flag UX for consistency with a linter run in the same pipeline. Both run around this editor in the pipeline below; neither replaces it.

Pipeline position (the invariant)

The editor is the middle of a fixed order; it does not run alone:

draft (a content skill or a human)
  → linter CRITICAL pre-screen   (Pass 1: confidentiality + capability-disclosure short-circuits)
  → /edit  (this skill)          (the generative readability refine)
  → linter FULL                  (Pass 1 + Pass 2: catch any AI-tell the rewrite introduced)
  → publish

• Linter-critical FIRST — a confidentiality leak or capability-disclosure must be caught before a voice-neutral, confidentiality-blind generative rewriter touches the text (a rewrite can paraphrase a leak past a regex; this skill has no such machinery).
• /edit MIDDLE — the generative refine.
• Linter-full LAST — a generative rewrite can introduce fresh AI-tells (a new synonym-cycle, an accidental rule-of-three); a full defect/style pass back-stops the output.

The linter is a separate defect / AI-pattern / style pass, run before and after this skill. It is not part of this package; substitute whatever defect linter your workflow uses. (Internally we pair /edit with a skill we call /review.)

Process — the runnable sequence (methodology §5)

The deterministic measures come from readability_diag.py; the judgment is the model's. A tool output is a flag to adjudicate, never a target to optimize (methodology §1 — the metric-trap).

Step 0 — Calibrate the floor AND ceiling

Name the audience and content class → read off the target grade band (a ceiling-and-floor pair, not a single target) + the home-vocabulary keep-list (the exact terms a specialist reader uses with peers). Everything downstream edits toward the band — never below its floor (dumb-down), never above its ceiling (inflation).

• If audience is unstated, infer it from content class and STATE the inference. A wrong floor is a dumb-down risk; a wrong ceiling an inflation risk — the band is never silently assumed.
• Set the band + keep-list to YOUR audience. Pick a grade band for the content class and audience, and keep the audience's home vocabulary — the words a peer would actually use, not signaling. Worked example (the firm's own bands): a private-credit desk sets an investor-grade floor across audiences — board memos sit higher (grade ~12–14), shareholder letters ~11–13, LinkedIn ~10–11, press ~9–10 (external floor) — but nothing drops below an institutional-investor reading level. The home vocabulary survives: "covenant," "FIDC," "debênture," "tranche" are grade-11+ terms a credit investor uses daily, so they stay; "sub-linear," "intelligence-heavy services layer" are signaling and get cut. The test: would the reader use this exact word telling a peer what you do? Keep precision; cut signaling. Set your own bands and keep-list for your audience — the numbers above are an example, not a default.
• Language (EN/PT). The six levers are language-general; the calibration is language-specific. Worked example for a second language: Portuguese runs ~1 grade above English at the same register (gerúndios, subjunctive, heavier natural nominalization) — don't fight it; an institutional-Portuguese vocabulary (e.g. CVM 161, ANBIMA, FIDC sênior, debênture incentivada, CRA, alocador) is grade-11+ by nature and is the reader's home, and the density tell shifts to -ção chains. Pass --lang pt to the tool, or let it auto-detect.

Step 1 — Diagnose, then decide whether to edit at all

1. Run the tool on the input. Read the flag list; respect parse_confidence / withheld.
2. The core split (methodology §4): for each hard passage, is it hard because the idea is hard (intrinsic — leave it, maybe anchor or rest it) or because the prose is hard (extraneous — fix it)? This is the irreducible judgment a score cannot make.
3. Scan the six levers (§ The six levers) and name the dominant 2–3 load sources — do not try to fix all six everywhere.
4. Diagnostic unit per lever. Declare the unit and refuse whole-piece legs on a fragment:
   • Levers 1–4 (abstraction, concreteness, cohesion, sentence-variation/recovery) are section-local — diagnosable on a passed-in snippet.
   • Levers 5–6 (structural variation, term-glossing) are whole-piece — device-repetition counts across the whole article (6 antitheses ÷ sections = 2–3 each, fine locally); glossing happens at a term's first load-bearing use, which a non-first-use section lacks.
   • On a fragment input, mark Levers 5–6 unassessed (whole-piece required) and do NOT fire leg-(a)'s device-count or leg-(c)'s gloss-screen on them — preventing false device/gloss verdicts in both directions.

STOP / NO-EDIT terminal. If the difficulty is intrinsic-only OR the prose is already at floor, STOP — emit a NO-EDIT verdict + a short rejected-move log (what you considered and why you left it). Restraint is the right answer often; do not proceed to Step 2 to manufacture an edit. (In the methodology's validation, two of four pieces correctly stopped here.)

=== /edit: NO-EDIT VERDICT ===
verdict:  NO EDIT — {intrinsic-only difficulty | already at floor}
why:      {1–2 lines}
rejected-move log:
  - {move considered} → rejected: {floor / ceiling / net-of-cost reason}
  - ...

Step 2 — Propose

For each dominant lever, pick the refine move and attach its two-sided floor/ceiling check — "does this drop content/precision the audience expects (below floor)?" AND "does this raise register, ceremony, or glossing above the audience (above ceiling)?" If either fires, reject the move.

Net-of-cost, per move. A refine move enters only if its readability gain exceeds its meaning/precision/voice cost. A move that buys variance by deleting a causal connective (the tree-bark trap) fails net-of-cost and is rejected here, before it ships. Propose, don't yet apply — a proposal you can inspect is one you can reject before it costs meaning. (The default mode stops here: a diagnosis + proposed moves, read-only.)

Step 3 — Refine (--apply only)

Apply the moves. The mantra: same ideas, same sophistication — paced for a reader, not compressed for a writer. You move load off the prose, not out of the content.

Step 4 — Gate-check (--apply only)

Run the four-part gate (§ The gate). Re-run readability_diag.py on the refined output for leg-(a)'s deterministic deltas — code, not the rewriter's say-so. If (b), (c), or (d) fails, return to Step 2. If leg-(a) flags but your §4 judgment disagrees, adjudicate — do not auto-fail, do not re-propose a real fix to chase a number. Ship only when (b)/(c)/(d) clear and the blocking, blind, independent meaning-confirm returns clean — leg-(d) is wired out-of-model (the code-blinded diff-anchored brief → three blind readers → the mechanical consensus roll-up; see § Leg-(d) wiring). The rewriting model never produces the meaning-diff nor sees which text is the edit.

The gate it can't game (methodology §6 — made executable)

The editor is an optimizer; give it a weak gate and it will satisfy the gate without doing the work. The hard-AND is on legs (b), (c), (d). Leg (a) is a computed flag adjudicated against judgment, never a ship-blocking veto. An edit ships only after the blocking, blind, independent meaning-confirm (d) returns clean.

The non-forgeable boundary, in one rule: the skill that does the rewriting neither produces the meaning-diff it is judged against nor sees which text is the edit. That independence is what makes the whole gate non-forgeable — not "one leg is code." An in-skill "I promise to emit PENDING and not self-certify" is a recall-tier control the same model could skip; the structural form is that the blind confirm runs outside the rewriting model's process (a held-out party — a human read, or a separate model call with no access to which text is the edit).

Leg-(d) output contract (the frozen interface; § Leg-(d) wiring consumes it)

On --apply, after Steps 3–4, the skill emits exactly this block:

=== /edit --apply: GATE RESULT (PENDING) ===
leg (a) measurably easier   [ADJUDICATED FLAG — never a veto]
  variance delta:    {tool, on the output; "ABSTAINED — low-confidence parse (withheld)" if parse_confidence < threshold}
  recovery/density:  {model-assisted read — did a lower-density sentence follow the high-density one?}
  score delta:       {FK/Fog flag, direction only}
  adjudication:      {corroborates §4 judgment | DISAGREES → adjudicated against §4 → {keep edit / revisit}}
leg (b) not dumbed down     [HARD-AND]:  {✅ PASS | 🔴 FAIL — reason}
  below-floor grade alarm:  {tool FK vs band floor}
  home-vocab term-diff:     {keep-list — any term stripped?}
  content-drop:             {model — any claim/precision lost?}
leg (c) on-floor+ceiling    [HARD-AND]:  {✅ PASS | 🔴 FAIL — reason}
  jargon screen:            {keep-list match + new-signaling (model)}
  register-inflation:       {model — manufactured formality / over-glossing?}
leg (d) meaning preserved   [HARD-AND, BLOCKING]:  PENDING
  --- HELD-OUT TEXT A ---
  {one of the two texts}
  --- HELD-OUT TEXT B ---
  {the other text}
  (the A/B ↔ original/edit mapping is WITHHELD from the confirming party — see boundary rule above)
STATUS:   PENDING — edit NOT shipped.   ⚠️ HUMAN-READ-REQUIRED
OVERALL:  ✅ CLEAN (apply) / 🟡 DRIFT (re-diagnose → Step 2) / ⚠️ ESCALATE (human read)   — set by --rollup
NEXT:     leg-(d) blind independent confirm (diff-anchored, 3-reader consensus — § Leg-(d) wiring) → unanimous-clean = ✅ CLEAN; unanimous-drift = 🟡 DRIFT; a split = ⚠️ ESCALATE.

Gate glyphs. Legs read ✅ PASS / 🔴 FAIL; the overall verdict reads ✅ CLEAN (apply) / 🟡 DRIFT (re-diagnose) / ⚠️ ESCALATE (human read). The gate summary sits ABOVE the refined text (never tokenizes it); the read-only NO-EDIT terminal is unchanged.

If (b) or (c) FAILS, the skill does not emit the held-out texts — it returns to Step 2 with the failing leg named. Leg-(d)'s PENDING is reached only when (b)/(c) clear.

Leg-(d) wiring — the out-of-model blind confirm

The mechanism — code blinds + diff-anchors, three out-of-model readers judge, the skill rolls up by consensus. On --apply, after (b)/(c) clear and the PENDING block is emitted:

1. Blind (code, non-forgeable) — emit the DIFF-ANCHORED brief. Write the original and the refined text to two files, then run with --diff:

   python3 blind_meaning_confirm.py --original <orig> --edited <edit> --diff \
       --brief-out <scratch>/confirm_brief.txt --key-out <scratch>/confirm_key.json
   

   The harness assigns the two texts to Text A / Text B (content-hash order — the edit is not always the same slot), writes a symmetric, diff-anchored brief — a mechanically-computed word-level A/B diff (order-preserving PART 1 opcodes + an order-independent PART 2 residue) that forces the reader to classify every numbered change as claim-change vs repackaging — and withholds the A/B↔original/edit mapping to confirm_key.json. The --diff mode is the fix for a silent-ship failure mode: a subtle qualifier dropped inside a reworded/reordered clause is an enumerated item the reader must adjudicate, not something to catch by holistic re-reading (blind readers went 0/3 → 3/3 on that case). Doing the blinding AND the diff in CODE is the load-bearing choice — a prose brief handed to the rewriting model is recall-tier (it could leak the mapping); the harness takes the leak out of the model's hands.

2. Judge (THREE blind out-of-model readers — the consensus panel). Spawn three independent readers (a separate mid-tier model call — e.g. Claude Sonnet — or human readers), each with the brief only: "Read only confirm_brief.txt; do not open any other file (there is an answer key you must not see); classify every numbered diff item and return the structured findings." Each runs in a separate context, blind to which text is the edit, and returns change_classifications (one line per numbered item) + claim_deltas (quote-anchored) + uncertain. Three readers, not one, because the diff-anchored brief's forcing-function — classify EVERY item — makes a lone reader occasionally over-classify a borderline near-synonym or a subordination↔coordination swap as a claim-change, and a single reader cannot tell its own spurious flag from a real one. Consensus (step 3) routes that disagreement to the human read instead of a spurious bounce.

3. Roll up (mechanical CONSENSUS rule — the skill never re-derives the diff). The skill computes the verdict from the three readers' lists, without reading the key. Let a reader "flag" iff its claim_deltas is non-empty:

   • all three CLEAN (every reader: empty claim_deltas and empty uncertain) → CLEAN → apply the edit to the file.
   • all three FLAG (unanimous non-empty claim_deltas) → DRIFT → do not ship; return to Step 2 with each delta named (read confirm_key.json only now, to map A/B → which phrase the edit changed).
   • anything else — the readers SPLIT (one or two flag), or any reader is uncertain → ESCALATE → route to the human read (the methodology's ground truth) before shipping. Never auto-clean and never auto-bounce on a split.

   Why unanimous-consensus and not pure-OR. Pure-OR (any one reader's claim_deltas non-empty → DRIFT) amplifies the lone-reader over-flag: a clean readability reword that stresses the synonym / causal-connective boundary drew a spurious flag from 1–2 of 3 readers → a false DRIFT that bounces a clean edit. The consensus rule converts that into an ESCALATE (a human dismisses it), while a real buried drop — which the --diff brief makes salient to all readers — still goes 3/3 → DRIFT. It never silent-ships (any reader catching a real drift forces at least an ESCALATE).

Why this is genuinely out-of-model + non-rubber-stampable (not theater): (a) the reader's separate context is the structural out-of-model boundary — it cannot see the rewrite reasoning; (b) the code-blinded symmetric brief means the reader cannot tell which text is the edit, and the rewriting model cannot leak it; (c) the rewriting model produces neither the diff nor the verdict — each reader enumerates the deltas, the skill only applies the consensus rule over the three lists; (d) the brief forbids "reads equivalent" hand-waving — it forces a bidirectional, quote-anchored claim enumeration that distinguishes a claim-change from pure syntactic repackaging.

The verification contract — applied WITHOUT breaking blindness. The reader's verdict gates an apply, so it is an execution-party verdict. But "re-verify against the source at the moment of action" must not be read as the orchestrator re-deriving the diff — that is the self-certification the gate forbids. The blindness-preserving application:

• Pre-dispatch: the skill picks the exact two texts (gather-vs-judge split — the reader never chooses what to compare); the brief is the fixed symmetric template; the anti-fabrication + quote-first rules are baked in by the harness.
• Form-verification (orchestrator-safe): confirm the verdict is well-formed — every claim-delta carries a verbatim anchor that is actually present in the texts, and the pass was bidirectional. This checks the verdict's form, never re-derives its substance.
• Substance defense-in-depth (out-of-model, never the orchestrator): the three-reader consensus is the default (a lone reader's verdict never decides); on top of that the retained human read (ground truth, below) is owed for publication.

The human read stays the publication ground truth. The wired reader panel is the routine, automated front-stop — it catches gross-to-moderate drift cheaply and escalates the subtle. An LLM reader is a proxy, not a held-out human read. For anything published, the HUMAN-READ-REQUIRED flag still owes a human cold read; the wiring front-stops it, it does not replace it.

The six levers (operational reference)

The real levers of reading difficulty — what a score can't see and the editor moves. Each is diagnostic signal → refine move → floor/ceiling check. Full science + citations: methodology §3 — do not re-derive here.

Inputs & outputs

Inputs: text or a file path; audience/register (sets the floor band and ceiling — Step 0); language (EN/PT). Audience unstated → infer from content class and state the inference.

Outputs:

• default (/edit): a diagnosis report — a findings list of readability levers — + the proposed moves + the predicted gate result; or the NO-EDIT verdict + rejected-move log when restraint is the answer.
• --apply: the refined text + the GATE RESULT (PENDING) block above (legs (b)/(c)/(d) pass/fail; leg-(a) an adjudicated flag with parse_confidence; leg-(d) the two held-out texts + PENDING + HUMAN-READ-REQUIRED).

Gotchas

• The score is a flag, never a target (the metric-trap). Every formula (FK, Fog, SMOG…) is a function of word length + sentence length only — blind to cohesion, abstraction, order. You can satisfy a formula and make the text harder (the tree-bark proof: chopping a sentence deletes the causal link the reader needed). Never optimize to a number.
• High variance ≠ easy. The variance flag is narrow — a piece can have healthy variance and still read as "constant maximum load." Variance catches monotone; it does not certify ease. That's why leg-(a) is a flag, not a veto.
• Never fabricate a withheld number. When the tool withholds a verdict (low parse_confidence), the model judgment carries — do not invent the variance/score figure. Emit "ABSTAINED — low-confidence parse."
• Don't fire whole-piece legs on a fragment. On a snippet, Levers 5–6 are unassessed; don't count antithesis or screen glossing on it.
• The rewriter must never produce the diff it's judged against (leg-d). A model judging its own rewrite — or reading a diff it produced — is the gameable LLM-judge the gate exists to avoid. Leg-(d) is structurally outside the rewriter, blind, and blocking (wired via blind_meaning_confirm.py --diff + three blind readers under a consensus rule — § Leg-(d) wiring). The mechanical word-level diff is code-computed and symmetric — it is not the rewriter's diff.
• The wired blind confirm is a proxy, not the ground truth (leg-d). The three-reader consensus catches gross-to-moderate drift and escalates the subtle or the split (→ human read); it does not replace the held-out human read a publication piece owes. And the diff-anchored brief must define a delta as a claim/precision change, not any surface difference — the forcing-function (classify every diff item) fixes the buried-drop silent-ship but makes a lone reader over-classify a borderline synonym / connective swap, which is exactly why the consensus rule (unanimous-flag → DRIFT, split → ESCALATE) is load-bearing, not just best-of-N. Each reader enumerates claim_deltas; the gate applies the consensus rule — no single reader editorializes a verdict.
• Two symmetric failures, not one. Below floor (dumb-down): stripping content/precision an expert reader expects. Above ceiling (inflation): manufactured formality, over-glossing — on expert-grade prose this is the more common real failure. Every move carries both checks.
• Restraint is an output. NO-EDIT on intrinsic-only / at-floor prose is correct, not a failure to act. Manufacturing an edit to "do something" is the failure.

Edge cases

• Fragment / snippet input → Levers 5–6 unassessed (whole-piece required); leg-(a) device-count + leg-(c) gloss-screen do not fire on it.
• Low parse_confidence / degenerate segmentation → the sentence-dependent flags are withheld; leg-(a)'s rhythm half abstains, §4 judgment carries; report the abstention, never a fabricated figure.
• Portuguese text → shift the band ~1 grade up; run an institutional-Portuguese home-vocabulary set; apply the Lever-3 formal-legal register check with extra force (a closed S-V gap can read less formal). Pass --lang pt.
• Already-at-floor or intrinsic-only difficulty → NO-EDIT verdict + rejected-move log (Step 1 STOP).
• --apply reaches PENDING → leg-(d) runs → the skill runs the out-of-model blind confirm (§ Leg-(d) wiring): blind_meaning_confirm.py --diff blinds the two texts + emits the diff-anchored brief → three blind readers each re-derive claim_deltas cold → the skill applies the consensus rule. Unanimous non-empty claim_deltas → DRIFT (return to Step 2); a split (1–2 flag) or any uncertain → ESCALATE to the human read; unanimous clean → apply. The edit is never auto-applied before leg-(d) returns unanimous-clean, and a publication piece still owes the HUMAN-READ-REQUIRED ground-truth human read on top of the automated confirm.
• Markdown input → the tool strips formatting and excludes fenced code blocks before measuring; pass --raw to measure literally.

See also

• ../readability-editing-methodology/readability_editing_methodology.md — the published methodology this skill executes (§3 levers, §5 sequence, §6 the gate). Published alongside this skill in the same library.
• readability_diag.py — the deterministic executor the skill shells out to, co-located (--json contract: flags, parse_confidence, sentence_segmentation, withheld).
• blind_meaning_confirm.py — leg-(d)'s out-of-model blinding harness, co-located (--diff mode): blinds the two texts → A/B with the mapping withheld and emits the diff-anchored brief, feeding the three blind readers whose verdicts the consensus rule combines (§ Leg-(d) wiring).
• A defect / AI-pattern linter — the composes-with sibling that runs around /edit in the pipeline (linter-critical → /edit → linter-full). Substitute whatever defect/style linter your workflow uses. A brand-voice content-drafting skill is the other composes-with sibling: it drafts; /edit refines readability of any draft, voice-neutral.

This skill is part of an internal knowledge-systems framework Bamboo DCM has been building for AI-native execution in regulated finance. If the broader framework is interesting, get in touch — we're publishing more as we package them.