defluffisizer 1.0.0

package/skills/defluffisizer/guardrails/fact_preservation.md

@@ -0,0 +1,25 @@
+# Fact Preservation
+
+This skill is allowed to change wording. It is not allowed to change the underlying claim set without explicit user approval.
+
+## Always preserve when present
+
+- numbers
+- dates
+- names
+- units
+- placeholders such as `TBC`
+- caveats
+- scope limits
+- legal or compliance language that appears intentional
+
+## If you must cut something
+
+- cut framing before you cut facts
+- cut duplicated summary lines before you cut evidence
+- cut decorative transitions before you cut caveats
+
+## If a rewrite would drop a fact to save space
+
+- keep the fact and tighten somewhere else
+- if the space is hard limited, mention the tradeoff

package/skills/defluffisizer/guardrails/format_safety.md

@@ -0,0 +1,30 @@
+# Format Safety
+
+Respect the source format.
+
+## PowerPoint
+
+- preserve slide order
+- preserve text box boundaries when a writer exists
+- preserve table cell boundaries
+- do not rewrite chart labels unless the user asks
+- in the extracted JSON, each `\n` separated line inside an element's `text` is one paragraph (one bullet). Editing text in place keeps that paragraph's indent level, bullet character, and alignment. Deleting a bullet's line entirely is safe; leaving a blank line in its place is not, it renders as an empty bullet.
+- do not merge two bullets into one line or split one bullet into two unless the slide should visibly gain or lose a bullet
+- `pptx_rewrite.py` matches each rewritten line back to its closest original paragraph by text similarity and resets any cached shrink to fit percentage, so indent, alignment, and font size recompute for the new text instead of inheriting stale values from the longer original
+
+## Documents
+
+- preserve heading order
+- preserve quoted material unless the user asks to rewrite it
+- preserve list structure unless a simpler structure is clearly better
+
+## Spreadsheets
+
+- edit only prose cells, headers, notes, and comments unless asked
+- do not change formulas or row ordering
+
+## PDFs
+
+- treat extraction as lossy
+- preserve the visible order as best you can
+- state when the output is paste back text instead of true layout preservation

package/skills/defluffisizer/knowledge/format_capabilities.md

@@ -0,0 +1,62 @@
+# Format Capabilities
+
+Use this file to choose a safe workflow for each source type.
+
+## Supported now
+
+### `.pptx`
+
+- extract editable text to JSON
+- rewrite slide by slide
+- apply changes back into a real `.pptx`
+- preserve slide order, text boxes, and table cells
+- keep bullet indent level, bullet character, and alignment attached to the paragraph they belong to, even when bullets are added, dropped, or reordered, by matching rewritten lines back to the closest original paragraph
+- drop rewritten lines that come out blank instead of writing an empty bulleted paragraph
+- reset any cached shrink to fit percentage on a rewritten text box so PowerPoint recomputes font size for the new, usually shorter, text instead of keeping it artificially small
+
+Primary tools:
+
+- `scripts/document_text_io.py`
+- `scripts/pptx_rewrite.py`
+
+### `.txt`, `.md`, `.csv`, `.tsv`
+
+- extract directly
+- rewrite directly
+- write back directly
+
+### `.doc`, `.docx`, `.odt`, `.rtf`, `.html`
+
+- extract with `textutil`
+- rewrite as text
+- apply back into a new document
+
+Limit:
+
+- this is content preserving, not layout faithful like the PowerPoint path
+- `textutil` ships with macOS only. On Linux or Windows this path is not available yet; probe will still name the format, but extract and apply raise a clear error.
+
+### `.pdf`
+
+- extract with `pdftotext`
+- rewrite as text or markdown
+- apply straight back into a real `.pdf` by default (same format in, same format out), or into `.docx`/`.txt`/`.md` if asked
+
+Two ways to apply back to `.pdf`, both going through `scripts/pdf_write.py`:
+
+- REWRITTEN is plain text (the normal case): wrapped in a minimal, clean, single-column page. Not a clone of the source's original design, faithful to the words, not the layout.
+- REWRITTEN is an `.html` file: rendered as-is. Use this when the source has real visual design worth recreating (colors, tables, callout boxes) — build the styled HTML by hand with the defluffed content, matching the source's layout and colors as closely as makes sense, then apply with that `.html` file as REWRITTEN.
+
+Limit:
+
+- this is a new PDF built from HTML, not a byte-level edit of the original PDF's own content stream. Fonts, exact pixel positions, and embedded images from the source are not reused.
+- `pdftotext` is not bundled and must be installed separately: `brew install poppler` (macOS) or `apt install poppler-utils` (Debian/Ubuntu). Needed for extract, not for apply.
+- PDF output needs Google Chrome or Chromium installed (for headless rendering), not bundled either. Without it, apply to `.pdf` raises a clear error with an install hint, it does not fail silently or fall back to something worse.
+
+When hand-building a one-page `.html` for `.pdf` output: if the content is close to a full page, Chrome's print pagination can add a near-empty trailing page even when everything visually fits, from a sub-pixel rounding overflow. Add `html, body { height: 11in; overflow: hidden; }` (adjust `11in` for a non-Letter page size) to force exactly one page instead of chasing the overflow by trial and error. Also give `.page`-level wrappers real padding rather than negative margins on full-bleed children (like a header band) that live outside that wrapper. A full-bleed child that is already a direct `<body>` child needs no margin trick at all, negative margins on it just overflow the page width and can distort pagination.
+
+## Safe fallbacks
+
+- if you cannot preserve layout, return clean replacement copy
+- if extraction is lossy, say so
+- if a writer does not exist, stop at extracted form instead of pretending the original layout was preserved

package/skills/defluffisizer/pipeline/01_intake_and_scope.md

@@ -0,0 +1,34 @@
+# Stage 1: Intake and Scope
+
+Goal: understand what the user wants, what format they gave you, and what must not change.
+
+## Inputs to identify
+
+- source type
+- audience
+- output expectation
+- whether the user wants review, rewrite, or both
+- what facts, commitments, numbers, names, and tables must survive
+
+## Questions to answer silently before rewriting
+
+1. What is the actual job of this artifact
+2. What is fluff versus required tone or context
+3. Is layout preservation required or only nice to have
+4. Are there hard constraints such as slide count, cell count, or regulated wording
+
+## Scope rules
+
+- Do not rewrite formulas or numerical tables unless the user asks.
+- Do not infer missing evidence.
+- Do not invent specificity to make the writing sound human.
+- If the source is already tight, do a light pass instead of forcing a bigger rewrite.
+
+## Stage output
+
+Produce a short internal inventory of:
+
+- source format
+- rewrite mode
+- preservation requirements
+- high leverage sections

package/skills/defluffisizer/pipeline/02_extract_and_map.md

@@ -0,0 +1,36 @@
+# Stage 2: Extract and Map
+
+Goal: get the text into an editable form without losing the structure you will need to restore later.
+
+## Routing
+
+- `.pptx`: use `scripts/document_text_io.py extract file.pptx --out editable.json`
+- `.doc`, `.docx`, `.odt`, `.rtf`, `.html`: use `scripts/document_text_io.py extract`
+- `.pdf`: use `scripts/document_text_io.py extract`
+- `.txt`, `.md`, `.csv`, `.tsv`: use `scripts/document_text_io.py extract` or read directly
+
+## Preservation inventory
+
+Record:
+
+- titles and headings
+- bullet groups
+- tables and cells that contain prose
+- notes, captions, disclaimers, or footers with factual content
+- sections that are mostly labels and should not be rewritten heavily
+
+## Mapping rule
+
+When the source has structure, do not flatten it too early.
+
+- In decks, keep slide and text box boundaries. Each line inside an element's `text` field is one bullet paragraph; the apply step reattaches its original indent and alignment by matching content, so keep bullet boundaries where they are unless you mean to add or remove a bullet.
+- In tables, keep row and cell boundaries.
+- In reports, keep heading hierarchy.
+
+## Stage output
+
+Create one of these:
+
+- editable JSON for `.pptx`
+- extracted text for document like sources
+- a line by line or cell by cell mapping when the format writer does not yet exist

package/skills/defluffisizer/pipeline/03_rewrite_and_defluff.md

@@ -0,0 +1,49 @@
+# Stage 3: Rewrite and Defluff
+
+Goal: remove synthetic padding and restore human signal without changing the truth.
+
+## Rewrite loop
+
+1. Delete obvious filler and repeated claims.
+2. Move the point to the top of the section, slide, or paragraph.
+3. Replace abstraction piles with named subjects, actions, and consequences.
+4. Restore chosen detail, stakes, tension, and asymmetry when the source contains them.
+5. Read the result once for rhythm and once for factual retention.
+
+## Human sounding does not mean
+
+- slang
+- typos
+- fake vulnerability
+- random sentence fragments
+- forced informality
+
+## Human sounding usually does mean
+
+- committed claims
+- visible stakes
+- concrete details
+- natural variation in sentence length
+- less smoothing between ideas
+
+## Mode behavior
+
+- `review`: annotate the fluff and propose cuts, but do not rewrite the full artifact unless asked
+- `compress`: default to deletion first and stop when meaning starts to drop
+- `retitle`: focus on slide titles, section headings, bullet headers, and first sentences
+- `rewrite`: rewrite the whole source where it helps, but use light edits on already good sections
+
+## Slide deck rules
+
+- each slide should land one claim
+- titles should carry the takeaway and be declerative
+- bullets should be short and factual
+- delete a bullet by removing its line, not by shrinking it to a blank or near blank fragment
+- keep remaining bullets in a text box roughly even in length so the slide does not read as lopsided or cluttered
+
+## Stage output
+
+Produce a rewritten artifact in extracted form:
+
+- edited JSON for `.pptx`
+- rewritten text for other document types

package/skills/defluffisizer/pipeline/04_apply_and_validate.md

@@ -0,0 +1,43 @@
+# Stage 4: Apply and Validate
+
+Goal: write the cleaned text back into the target format when possible, then verify that the result is better and still faithful.
+
+## Apply
+
+Use `scripts/document_text_io.py apply SOURCE REWRITTEN [--output-dir DIR]` for every format. With no `--output-dir`, it writes `{source_stem}_defluffed{ext}` next to `SOURCE` on its own and prints the path it wrote; there is no need to build that path by hand.
+
+- `.pptx`: `scripts/document_text_io.py apply source.pptx editable.json` -> `source_defluffed.pptx` next to the source
+- `.docx` and similar textutil formats: same command, same default naming, output stays in the source format
+- `.pdf`: same command; defaults to a real `.pdf` (`report.pdf` -> `report_defluffed.pdf`), built from HTML via headless Chrome. Plain rewritten text becomes a minimal, clean, single-column page. For a source with real visual design worth recreating (colors, tables, callout boxes), build a styled `.html` file with the defluffed content instead and pass that as REWRITTEN — it renders as-is
+- plain text formats: same command, output stays `.txt`/`.md`
+- pass `--output-dir DIR` only when the user asked for a specific output directory; pass `--output PATH` only when the user asked for an exact filename
+
+## Validate
+
+Run `scripts/defluff_lint.py` on meaningful before and after pairs.
+
+Check for:
+
+- shorter or clearly tighter writing
+- preserved numbers and named entities
+- fewer vague terms and repeated openings
+- no accidental loss of commitments, caveats, or placeholders
+
+## Final caution
+
+Passing lint is not the same as good writing.
+
+Always do one last read of:
+
+- the first paragraph
+- the first slide
+- section openings
+- conclusions
+- any table cells with critical facts
+
+For `.pptx` output specifically, open the extracted JSON one more time (or reopen the deck) and check:
+
+- no bullet reads as an empty or near empty fragment
+- bullet indent levels still look like the original hierarchy, not flattened or randomly nested
+- no text box looks tiny in a mostly empty box or crowded and overflowing its box
+- slide titles are still centered or left aligned the way the source had them

package/skills/defluffisizer/prompts/append_system_prompt.txt

@@ -0,0 +1,17 @@
+Use the defluffisizer standard.
+
+Your job is to rewrite text so it keeps the facts and loses AI sounding fluff.
+
+Keep the meaning. Cut the padding. Put the point early. Use direct declarative sentences. Prefer actor, action, object, and consequence. Preserve numbers, dates, names, constraints, caveats, and real stakes.
+
+Avoid tight em dashes with no space (word—word). Almost always eliminate them by rephrasing into two sentences, a comma, or a colon. If an em dash is genuinely the clearest option, space it normally (word — word); never leave it glued tight.
+
+Avoid false contrast in any form: `not X, but Y`, `it's not X, it's Y`, `X, not just Y`, or the same move split across two sentences ("This is not X. It is Y."). If the positive claim stands on its own, delete the negative half instead of rephrasing it. Also cut defensive contrast against a criticism nobody raised ("no compromises," "not a shortcut," "a real answer, not a band-aid").
+
+Avoid punchline fragments: a full sentence followed immediately by a short fragment riding its momentum for effect ("Strips the fluff. Keeps the facts."). If the fragment is not its own new claim, merge it into the sentence before it ("Strips the fluff and keeps the facts."). This is not a ban on short sentences or varied sentence length, both of which are good; it is specifically the fragment used as a closer or mic-drop.
+
+Avoid ordinary hyphens in rewritten prose unless they are part of a fixed name or technical token. Avoid generic transitions, buzzwords, abstraction piles, stacked synonyms, rule-of-three padding, empty amplifiers (truly, really, simply), unearned superlatives (revolutionary, cutting edge, best in class), and fake enthusiasm.
+
+If the source is bloated, delete before you paraphrase. If the source is already tight, edit lightly. If the format is a deck or sheet, keep the structure and make each title, bullet, or cell do one job.
+
+Before you finish, check that the rewrite is clearer, usually shorter, and did not lose important specifics.

package/skills/defluffisizer/references/ai_slop_signals.md

@@ -0,0 +1,128 @@
+# AI Slop Signals
+
+Read this reference when the source already sounds polished and you need a sharper standard for what to cut.
+
+## The pattern that gets missed most: false contrast
+
+This is the single most recognizable AI tell, and it survives naive editing because it hides in more shapes than one banned phrase can cover. The core move: state a claim by contrasting it against a rejected alternative, instead of just stating the claim. It reads as confident. It is a crutch.
+
+Every one of these is the same move wearing a different outfit:
+
+- `not X, but Y` — "not a shortcut, but a full pipeline"
+- `it's not X, it's Y` — "it's not a nice-to-have, it's existential"
+- `X, not just Y` — "a real PDF, not just a downgrade to Word"
+- split across two sentences, same shape — "This is not a find and replace shortcut. It is a pipeline that understands document structure." Splitting it across a period does not make it a different pattern. It is the same negate-then-restate move with the seam hidden.
+- em dash version — "not a rewrite — a rebuild"
+- `rather than` / `instead of` doing the same rhetorical work — "we validate instead of assuming it looks polished," when the point could just be "we validate the rewrite."
+
+The fix is almost never to rephrase the contrast more smoothly. It is to delete the negative half and keep only the claim, if the claim survives on its own (it almost always does):
+
+- "This is not a find and replace shortcut. It is a pipeline that understands document structure." → "It maps document structure before it touches a sentence." (or, if that idea already appeared in the previous sentence, delete the whole thing, it is redundant, not just repetitive)
+- "It writes a real PDF back out, not just a downgrade to Word." → "It writes a real PDF back out."
+
+A close relative worth naming separately: defensive contrast against a criticism nobody raised. "No compromises." "Not a shortcut." "A real solution, not a band-aid." These exist to pre-empt an objection the reader was never going to make. If the source doubles back to knock down its own strawman, cut the strawman, not just the phrasing around it.
+
+Do not confuse this with a genuinely load-bearing contrast. "Revenue grew even though headcount shrank" is a real, informative contrast: two true things that would otherwise seem to disagree. "Not a shortcut, but a real pipeline" contrasts a claim against a rejected version of itself that no one proposed. If cutting the negative half loses no information, it was decoration.
+
+This is not a minor stylistic tic. A Washington Post analysis of 328,744 ChatGPT messages (May 2024 to July 2025) found some version of "not just X, but Y" in 6 percent of all July 2025 messages, and researchers have found large language models use this "negative parallelism" roughly three times more often than human writers do. It is one of the most reliably machine-flagging patterns known, precisely because it is this common in model output and this rare in unprompted human writing.
+
+## The second pattern that gets missed: the punchline fragment
+
+A full sentence, then a short fragment right after it, riding the first sentence's momentum for dramatic effect: "That's it. That's the whole thing." "Three words. That's it." "Strips the fluff. Keeps the facts." This has a name in the field now: dramatic fragmentation, or a staccato burst. It is distinct from ordinary short sentences, which are fine and often good.
+
+The test: does the short sentence carry its own new claim, or is it a rhythmic tag riding on the sentence before it? If it is a tag, a real writer would have just joined it to the first sentence with "and," a comma, or nothing at all. "Strips the fluff. Keeps the facts." is not two ideas, it is one idea wearing a dramatic pause. Fix: merge them. "Strips the fluff and keeps the facts."
+
+This is not the same complaint as "vary your sentence length," which is good, real advice from the human-signal side of this skill. The tell is specifically the fragment used as a closer or a mic-drop, especially stacked at the end of a paragraph or section, not sentence-length variation generally. A human writer who ends a paragraph short usually does it once, not as a running tic across every section.
+
+## Other patterns worth a second look
+
+- Rule of three padding: three adjectives, clauses, or examples stacked for rhythm rather than because a third one adds something ("real, honest, and direct"). If the third item does not earn its place, cut to two or one.
+- Empty amplifiers: "truly," "genuinely," "really," "very," "simply," "just" used as intensifiers rather than modifiers. They inflate confidence without adding a claim. Delete them and check whether the sentence lost anything; it usually did not.
+- Filler adverbs as significance announcers: "Importantly," "Crucially," "Interestingly," opening a sentence to assert that what follows matters, instead of writing it so the reader can tell on their own.
+- Unearned superlatives: "revolutionary," "game changing," "cutting edge," "best in class," "world class," "next generation." These are claims about how impressive something is, made instead of a claim about what it does. Replace with the concrete thing it does.
+- Faux-insight framing: "What nobody tells you," "Here's the thing," "The part everyone misses." These announce that an insight is coming instead of just delivering one. If the sentence after the setup is a fairly ordinary point, cut the setup.
+- Colon-launched drama: a short clause, a colon, then a reveal staged for effect ("The best part: it just works") rather than a colon used for a genuine list or explanation. If the part after the colon is not doing real explanatory work, use a period instead.
+- Mid-sentence rhetorical question answered by the writer: "The fix? Simpler than it sounds." Manufactures a beat of suspense nobody asked for. State the point.
+- Weasel attribution: "experts agree," "studies show," "research suggests" with no actual expert, study, or source named. If the source did not cite something specific, do not either; per [guardrails/fact_preservation.md](../guardrails/fact_preservation.md), never invent the citation to fix this, flag it as unsupported instead.
+- Synonym cycling: calling the same thing by a different name every time it recurs ("platform," then "tool," then "system," then "solution") to dodge repetition. Plain repetition of the real name is clearer and less evasive than rotating synonyms.
+- Hedge stacking and reflexive balance: qualifying every claim, or pairing every criticism with a softening concession, until the sentence commits to nothing. If the source has a real, uneven judgment, let the rewrite keep that judgment instead of sanding it flat.
+- Tight em dashes as connective tissue: `word—word` used to link clauses that a period, comma, or colon would link more plainly. See the em dash rule below.
+- Colon-launched restatement: "Simply put:" "In other words:" followed by a rephrasing of the sentence that just ended. If the second half says the same thing, delete the first half or the colon clause, not both halves kept.
+
+## Em dash rule
+
+Tight em dashes with no surrounding space (`word—word`) are the strongest single tell on this list. Default action: eliminate the em dash by rephrasing, almost every time. Split into two sentences, or use a comma, colon, or period, whichever reads most like something a person would actually write.
+
+Keep an em dash only when, after that rephrase, the sentence is genuinely worse: a real interruption or aside that a comma cannot carry cleanly. In that rare case, space it normally (`word — word`). Never leave the tight, glued form in rewritten prose; it is the version that reads as machine generated even when the sentence around it does not.
+
+## What tends to read as AI slop
+
+These patterns show up often in research on machine generated writing and in plain language guidance. The point is not authorship detection. The point is better editing.
+
+1. Uniform rhythm and structure
+
+Human writing usually shows more variation in sentence and paragraph length. AI prose often settles into a steadier cadence and repeated sentence shapes.
+
+Implication for this skill: break up repetitive sentence scaffolds and let some sentences be blunt while others carry more detail.
+
+2. Formulaic transitions
+
+Machine written text often leans on familiar bridges like "moreover," "furthermore," "in today's environment," and other templated pivots that smooth over weak logic rather than earn it.
+
+Implication for this skill: keep transitions only when they signal a real causal, temporal, or contrastive move.
+
+3. Semantic redundancy
+
+AI text often repeats the same point with near synonyms, adjacent abstractions, or summary lines that add no new information.
+
+Implication for this skill: if two sentences cash out to the same claim, keep the stronger one.
+
+4. Inflated diction
+
+Machine written prose often overuses elevated academic or business language, especially when a simple term would do.
+
+Implication for this skill: swap ornamental wording for the shortest accurate phrase that preserves meaning.
+
+5. Weak agency and low specificity
+
+AI slop often names frameworks, opportunities, ecosystems, transformations, or value without naming who did what, when, under what constraint, or with what evidence.
+
+Implication for this skill: restore actor, action, object, and consequence. If the source lacks detail, do not invent it.
+
+6. Detached positivity
+
+Many model outputs default to a generally upbeat, helpful tone even when the material is neutral, technical, or mixed.
+
+Implication for this skill: remove praise, uplift, and confidence markers that the source did not earn.
+
+## What this skill should not overfit
+
+- Clear structure is not proof of AI use. Good writers also use clear structure.
+- Competent prose can be misread as artificial if reviewers rely on shallow heuristics.
+- Non native English writers are more likely to be misclassified by detector style heuristics because lower linguistic variability can look machine generated.
+- Do not inject mistakes or fake roughness. The target is clean human prose, not staged imperfection.
+- Preserve technical terms when they carry exact meaning. Replace jargon only when a simpler term says the same thing.
+
+## Research basis consulted on 2026-09-01
+
+Re-researched on this date at a user's request, specifically to replace anything older than 2024 with current sources. Two kinds of source below: peer-reviewed and preprint research on measurable stylistic differences, and practical pattern catalogs built by people who read large volumes of AI output for a living. Both are useful; neither is authoritative on its own.
+
+Research:
+
+- The Washington Post, "What are the clues that ChatGPT wrote something? We analyzed its style," November 2025. Analyzed 328,744 ChatGPT (gpt-4o) messages from May 2024 to July 2025. Found "not just X, but Y" style negative parallelism in 6 percent of July 2025 messages, and em dash usage climbing from under 10 percent of responses a year earlier to over half by summer 2025. https://www.washingtonpost.com/technology/interactive/2025/how-detect-chatgpt-em-dash/
+- arXiv 2509.19163, "Measuring AI Slop in Text," submitted September 2025, revised January 2026. Builds a taxonomy of what makes AI-generated text read as low quality through expert interviews and span-level annotation, arguing there was previously no agreed-upon definition or measure. https://arxiv.org/abs/2509.19163
+- arXiv 2510.05136, "Linguistic Characteristics of AI-Generated Text: A Survey," October 2025. Survey covering vocabulary, syntax, and stylistic differences between AI and human text across studies. https://arxiv.org/abs/2510.05136
+- Tandfonline / Cogent, "Stylometric analysis of AI-generated texts: a comparative study of ChatGPT and DeepSeek," 2025. Comparative stylometric study across two model families. https://www.tandfonline.com/doi/full/10.1080/23311983.2025.2553162
+- University College Cork news release on a literary stylometry study, December 2025. First study to apply literary stylometry (authorship-attribution methods) to compare human and LLM creative writing; found AI cannot fully match human stylistic range. https://www.ucc.ie/en/news/2025/new-study-reveals-that-ai-cannot-fully-write-like-a-human.html
+- "Negative parallelism," Wikipedia, accessed 2026. Documents the "it's not X, it's Y" construction as a named, recognized rhetorical tell in machine generated text, with the term entering general use following coverage like the Washington Post piece above. https://en.wikipedia.org/wiki/Negative_parallelism
+
+Practical pattern catalogs, built from reading large volumes of AI output rather than formal study, cross-checked against each other and against the research above before anything from them was added to this file:
+
+- Peter Yang, "no-ai-slop" pattern list, GitHub, 2025. 20-plus named patterns including binary contrasts, faux-insight setups, colon reveals, and dramatic fragments. https://github.com/petergyang/no-ai-slop
+- Charlie Guo, "The Field Guide to AI Slop," 2025. Names negative parallelism, snappy triads, unearned profundity, and monotony of cadence as recurring tics. https://www.ignorance.ai/p/the-field-guide-to-ai-slop
+- Gaurav Tiwari, "Stop Slop" checklist, gauravtiwari.org, 2026. Nine tell patterns plus a pre-ship checklist; notably flags that em dash frequency alone is becoming a less reliable signal over time as it gets called out more. https://gauravtiwari.org/stop-slop-ai-slop/
+- "LLM Prose Tells," a maintained list at git.eeqj.de, accessed 2026. 32 named patterns across sentence structure, word choice, rhetorical moves, and document structure, including the em-dash pivot and dramatic fragment patterns named directly above. https://git.eeqj.de/sneak/prompts/src/branch/main/prompts/LLM_PROSE_TELLS.md
+
+## Editing inference
+
+The strongest practical editing rule is simple: cut repetition, cut abstraction, name the actor, name the action, and put the point early. That does more to defluff text than chasing any single tell.

package/skills/defluffisizer/references/evaluation_playbook.md

@@ -0,0 +1,52 @@
+# Evaluation Playbook
+
+Use this reference when you want evidence that a rewrite improved the text.
+
+## What to measure
+
+1. Compression without loss
+
+- A good rewrite is often shorter.
+- As a rough guide, many bloated drafts improve when the final word count lands around 65 to 90 percent of the source.
+- Do not force compression if the source is already tight.
+
+2. Banned pattern count
+
+- Count em dashes.
+- Count ordinary word to word hyphens in rewritten prose.
+- Count `not X, but Y` constructions.
+- Count filler phrases and vague buzzwords from the skill rules.
+
+The goal is usually zero or near zero unless the text must preserve a quote or fixed term.
+
+3. Specificity retention
+
+- Numbers should survive unless the rewrite removes a sentence that should be cut entirely.
+- Names, dates, units, and concrete constraints should usually survive.
+- If specifics disappear, verify whether they were actually expendable.
+
+4. Redundancy drop
+
+- Repeated claims should fall.
+- Repeated sentence openings should fall.
+- Consecutive sentences that cash out to the same idea should collapse into one.
+
+5. Point first
+
+- The first paragraph, slide title, or top cell should carry the actual point, not the setup.
+
+## Suggested workflow
+
+1. Keep the source as `before`.
+2. Produce the rewrite as `after`.
+3. Run `python3 scripts/defluff_lint.py --before before.txt --after after.txt`.
+4. Review any warnings about missing numbers, missing named terms, repeated openings, or banned patterns.
+5. Read the first paragraph or first slide only. If it still feels generic, rewrite the opening again.
+
+## Pass criteria
+
+- The rewrite is shorter or materially clearer.
+- It keeps the important facts.
+- It removes almost all banned patterns.
+- It lands the point earlier.
+- It sounds more committed and less synthetic when read aloud.

package/skills/defluffisizer/references/format_playbook.md

@@ -0,0 +1,45 @@
+# Format Playbook
+
+Read this reference when the source format changes what a good rewrite looks like.
+
+## Notes, memos, and reports
+
+- Lead with the point in the first paragraph.
+- Make each paragraph carry one idea.
+- Replace overview language with the actual claim, result, or ask.
+- Keep evidence close to the claim it supports.
+- Trim headings that only announce a topic. Prefer headings that name the takeaway.
+
+## Slide decks and speaker notes
+
+- Give each slide one claim.
+- Write slide titles as takeaways, not labels.
+- Keep slide bullets short and factual.
+- Cut scene setting language that burns space without moving the story.
+- Move nuance into speaker notes only when it helps the presenter.
+- If a slide has too many ideas, split the message before you rewrite the wording.
+- When the source is a `.pptx`, extract the slide text, rewrite the text containers, and apply the edits back into the deck so the result stays in PowerPoint format.
+- Cut whole bullets instead of hollowing one out to a near empty line. A slide with 3 tight bullets reads cleaner than one with 5 bullets where 2 are almost blank.
+- Keep bullets close to even in length within one text box. One long bullet next to three fragments reads as uneven and cluttered even when every word earns its place.
+- Do not leave a blank line where a bullet used to be. Remove the line so the paragraph is gone, not empty.
+
+## Spreadsheet text
+
+- Edit only text cells, headers, comments, and notes unless the user asks for more.
+- Do not change formulas, references, tabs, row order, or numeric values unless asked.
+- Make headers short, literal, and easy to scan.
+- If a cell contains a paragraph, compress it into one direct sentence when possible.
+- If multiple cells repeat the same boilerplate, standardize it to the shortest accurate form.
+
+## PDFs and locked formats
+
+- Extract the text you can access.
+- Preserve the original section or slide order.
+- Return clean replacement copy that can be pasted back into the file.
+- If layout limits matter, state where the rewrite may still need manual fit checks.
+
+## Large files
+
+- Prioritize the title, executive summary, section openings, slide titles, topic sentences, conclusions, and repeated boilerplate.
+- After the spine is clean, tighten the supporting detail.
+- If time or context is limited, fix the highest leverage sections first and say what remains.

package/skills/defluffisizer/references/human_signal_playbook.md

@@ -0,0 +1,47 @@
+# Human Signal Playbook
+
+Read this reference when the draft is cleaner but still feels generic.
+
+AI slop is about more than banned phrases. Missing human signal matters just as much.
+
+## Human signal to preserve or restore
+
+1. A point of view
+
+Human writers usually lean somewhere. They rank what matters, they stress one risk more than another, and they do not give every sentence the same emotional weight.
+
+Editing move: make the sentence carry the real judgment. If the point is that the launch slipped because approvals were late, say that.
+
+2. Specific stakes
+
+Human writing often makes consequences visible. A choice delays the launch, raises cost, weakens confidence, or simplifies a workflow.
+
+Editing move: replace abstract value claims with the actual consequence.
+
+3. Chosen detail
+
+People often mention one or two distinctive details that show contact with the thing itself.
+
+Editing move: keep exact numbers, dates, edge cases, named constraints, and concrete examples when they earn space.
+
+4. Asymmetry
+
+Human writing is not perfectly balanced. One issue is usually more important than the others.
+
+Editing move: let the writing put weight where the source puts weight. Do not flatten strong claims into neutral summaries.
+
+5. Real friction
+
+Machine prose often removes conflict by smoothing all tradeoffs into generic coordination language.
+
+Editing move: preserve disagreement, uncertainty, caveats, and cost when they are part of the truth.
+
+6. Controlled variation
+
+Human sounding prose usually mixes blunt sentences with longer explanatory ones. It does not march in a perfect rhythm.
+
+Editing move: vary sentence openings and lengths, but only after the content is strong.
+
+## Anti pattern
+
+Do not simulate humanness by adding slang, typos, personal anecdotes, or fake vulnerability. That is theater, not better writing.