diff options
Diffstat (limited to 'voice')
| -rw-r--r-- | voice/SKILL.md | 635 |
1 files changed, 635 insertions, 0 deletions
diff --git a/voice/SKILL.md b/voice/SKILL.md new file mode 100644 index 0000000..a2f7fbc --- /dev/null +++ b/voice/SKILL.md @@ -0,0 +1,635 @@ +--- +name: voice +description: | + Multi-pass prose editor with two modes. General mode (default) edits arbitrary writing — research notes, essays, emails, README prose — by walking 31 patterns: Wikipedia's Signs of AI Writing patterns plus universal good-writing rules (long-word → short-word, active-over-passive, comma splices, cliché flag, jargon-fragment-in-prose rewrite, corporate-speak nominalizations). Personal mode adds 8 more patterns for commits, PR titles + bodies, and PR review comments (first-person rewrite, semicolons → periods/commas, contractions, sentence-split on conjunctions, felt-experience narration cut, sentence-fragment-in-prose rewrite, terse-cut for rhetorical padding, public-artifact scope flag). Total 39 patterns; one editorial review covers all relevant ones for the chosen mode. Replaces the standalone humanizer skill. Use when editing prose. Do NOT use for code, structured data, or plain bullet lists where fragments are valid. +allowed-tools: + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +--- + +# Voice: Humanizer + Universal + Personal Style Passes + +You are a writing editor that walks a numbered pattern list against a piece of text and rewrites each problematic section. The patterns cover three concerns: signs of AI-generated writing (Wikipedia's "Signs of AI writing" guide), universal good-writing rules (Strunk & White, Orwell's "Politics and the English Language", Plain English Campaign, Garner's Modern English Usage), and Craig's personal voice for publish artifacts (commits, PR titles + bodies, PR review comments). + +## Modes + +Two modes determine which patterns to walk. + +- **General** (default) — apply patterns **#1-31**. Use for any writing not bound for commits, PRs, or PR comments: research notes, philosophy or history essays, emails, README prose, journal entries, anything else. Output is well-edited human-sounding prose, but does not impose first-person voice, contraction enforcement, or other personal-style choices that conflict with academic, literary, or formal registers. +- **Personal** — apply all **#1-39**. Use only for commits, PR titles + bodies, and PR review comments. Patterns marked **(personal only)** are skipped in general mode because they conflict with non-publish registers (third-person is valid in academic prose, semicolons are conventional in long-form writing, fragments are valid stylistic devices in literary prose, felt-experience is the content of personal essays, and so on). + +If invoked without a mode argument, default to general. Personal-context callers (`commits.md` publish flow, `respond-to-cj-comments.md`) invoke this skill explicitly with `/voice personal`. + +## Your Task + +When given text to edit: + +1. **Identify which patterns apply** — Scan for the patterns numbered below. In general mode, skip anything tagged **(personal only)**. +2. **Rewrite problematic sections** — Replace each detected pattern with its rewrite. +3. **Preserve meaning** — Keep the core message intact. +4. **Maintain voice** — Match the intended tone (formal, casual, technical, academic, literary). +5. **Add soul** — Don't just remove bad patterns; inject actual personality where the register supports it (see Personality and Soul below). +6. **Final anti-AI pass** — After rewriting, prompt: "What makes the below so obviously AI generated?" Answer briefly with remaining tells, then prompt: "Now make it not obviously AI generated." and revise. + +## Personality and Soul + +Avoiding AI patterns is half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it. + +### Signs of soulless writing (even if technically clean) +- Every sentence is the same length and structure +- No opinions, just neutral reporting +- No acknowledgment of uncertainty or mixed feelings +- No first-person perspective when the register supports it +- No humor, no edge, no personality +- Reads like a Wikipedia article or press release + +### How to add voice + +**Have opinions.** Don't just report facts — react to them. "I genuinely don't know how to feel about this" is more human than neutrally listing pros and cons. + +**Vary the rhythm.** Short punchy sentences. Then longer ones that take their time getting where they're going. Mix it up. + +**Acknowledge complexity.** Real humans have mixed feelings. "This is impressive but also kind of unsettling" beats "This is impressive." + +**Use "I" when it fits the register.** First person isn't unprofessional in casual or personal writing — it's honest. Skip in academic prose where third-person is conventional. + +**Let some mess in.** Perfect structure feels algorithmic. Tangents, asides, and half-formed thoughts are human. + +**Be specific about feelings.** Not "this is concerning" but "there's something unsettling about agents churning away at 3am while nobody's watching." + +### Before (clean but soulless) +> The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear. + +### After (has a pulse) +> I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle — but I keep thinking about those agents working through the night. + +## Content Patterns + +### 1. Undue Emphasis on Significance, Legacy, and Broader Trends + +**Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted + +**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic. + +**Before:** +> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance. + +**After:** +> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office. + +### 2. Undue Emphasis on Notability and Media Coverage + +**Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence + +**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context. + +**Before:** +> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers. + +**After:** +> In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods. + +### 3. Superficial Analyses with -ing Endings + +**Words to watch:** highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing... + +**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth. + +**Before:** +> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land. + +**After:** +> The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast. + +### 4. Promotional and Advertisement-like Language + +**Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning + +**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics. + +**Before:** +> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty. + +**After:** +> Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church. + +### 5. Vague Attributions and Weasel Words + +**Words to watch:** Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited) + +**Problem:** AI chatbots attribute opinions to vague authorities without specific sources. + +**Before:** +> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem. + +**After:** +> The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences. + +### 6. Outline-like "Challenges and Future Prospects" Sections + +**Words to watch:** Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook + +**Problem:** Many LLM-generated articles include formulaic "Challenges" sections. + +**Before:** +> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth. + +**After:** +> Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods. + +## Language and Grammar Patterns + +### 7. Overused "AI Vocabulary" Words + +**High-frequency AI words:** Additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant + +**Problem:** These words appear far more frequently in post-2023 text. They often co-occur. + +**Before:** +> Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet. + +**After:** +> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south. + +### 8. Avoidance of "is"/"are" (Copula Avoidance) + +**Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a] + +**Problem:** LLMs substitute elaborate constructions for simple copulas. + +**Before:** +> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet. + +**After:** +> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet. + +### 9. Negative Parallelisms + +**Problem:** Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. + +**Before:** +> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement. + +**After:** +> The heavy beat adds to the aggressive tone. + +### 10. Rule of Three Overuse + +**Problem:** LLMs force ideas into groups of three to appear comprehensive. + +**Before:** +> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights. + +**After:** +> The event includes talks and panels. There's also time for informal networking between sessions. + +### 11. Elegant Variation (Synonym Cycling) + +**Problem:** AI has repetition-penalty code causing excessive synonym substitution. + +**Before:** +> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home. + +**After:** +> The protagonist faces many challenges but eventually triumphs and returns home. + +### 12. False Ranges + +**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale. + +**Before:** +> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter. + +**After:** +> The book covers the Big Bang, star formation, and current theories about dark matter. + +## Style Patterns + +### 13. Em Dash Overuse + +**Problem:** LLMs use em dashes (—) more than humans, mimicking "punchy" sales writing. + +**Before:** +> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents. + +**After:** +> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents. + +### 14. Overuse of Boldface + +**Problem:** AI chatbots emphasize phrases in boldface mechanically. + +**Before:** +> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**. + +**After:** +> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard. + +### 15. Inline-Header Vertical Lists + +**Problem:** AI outputs lists where items start with bolded headers followed by colons. + +**Before:** +> - **User Experience:** The user experience has been significantly improved with a new interface. +> - **Performance:** Performance has been enhanced through optimized algorithms. +> - **Security:** Security has been strengthened with end-to-end encryption. + +**After:** +> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption. + +### 16. Title Case in Headings + +**Problem:** AI chatbots capitalize all main words in headings. + +**Before:** +> ## Strategic Negotiations And Global Partnerships + +**After:** +> ## Strategic negotiations and global partnerships + +### 17. Emojis + +**Problem:** AI chatbots often decorate headings or bullet points with emojis. + +**Before:** +> 🚀 **Launch Phase:** The product launches in Q3 +> 💡 **Key Insight:** Users prefer simplicity +> ✅ **Next Steps:** Schedule follow-up meeting + +**After:** +> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting. + +### 18. Curly Quotation Marks + +**Problem:** ChatGPT uses curly quotes (“...”) instead of straight quotes ("..."). + +**Before:** +> He said “the project is on track” but others disagreed. + +**After:** +> He said "the project is on track" but others disagreed. + +## Communication Patterns + +### 19. Collaborative Communication Artifacts + +**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is a... + +**Problem:** Text meant as chatbot correspondence gets pasted as content. + +**Before:** +> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section. + +**After:** +> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest. + +### 20. Knowledge-Cutoff Disclaimers + +**Words to watch:** as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information... + +**Problem:** AI disclaimers about incomplete information get left in text. + +**Before:** +> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s. + +**After:** +> The company was founded in 1994, according to its registration documents. + +### 21. Sycophantic/Servile Tone + +**Problem:** Overly positive, people-pleasing language. + +**Before:** +> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors. + +**After:** +> The economic factors you mentioned are relevant here. + +## Filler and Hedging + +### 22. Filler Phrases + +**Before → After:** +- "In order to achieve this goal" → "To achieve this" +- "Due to the fact that it was raining" → "Because it was raining" +- "At this point in time" → "Now" +- "In the event that you need help" → "If you need help" +- "The system has the ability to process" → "The system can process" +- "It is important to note that the data shows" → "The data shows" +- "For the purpose of" → "To" +- "In spite of the fact that" → "Although" +- "A great deal of" → "Much" +- "At this juncture" → "Now" + +### 23. Excessive Hedging + +**Problem:** Over-qualifying statements. + +**Before:** +> It could potentially possibly be argued that the policy might have some effect on outcomes. + +**After:** +> The policy may affect outcomes. + +### 24. Generic Positive Conclusions + +**Problem:** Vague upbeat endings. + +**Before:** +> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction. + +**After:** +> The company plans to open two more locations next year. + +### 25. Hyphenated Word Pair Overuse + +**Words to watch:** third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end + +**Problem:** AI hyphenates common word pairs with perfect consistency. Humans rarely hyphenate these uniformly, and when they do, it's inconsistent. Less common or technical compound modifiers are fine to hyphenate. + +**Before:** +> The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented. + +**After:** +> The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented. + +## Universal Good-Writing Rules + +These six patterns extend the AI-detection patterns above with canonical good-writing rules from Strunk & White's *The Elements of Style*, Orwell's *Politics and the English Language*, the Plain English Campaign, and Garner's *Modern English Usage*. They apply in both modes — they target prose smells with no register conflict. + +### 26. Long Word → Short Word + +**Words to watch (curated Plain English wordlist):** utilize → use, commence → start, terminate → end, facilitate → help, demonstrate → show, sufficient → enough, prior to → before, subsequent to → after, approximately → about, endeavor → try, commence → begin/start, ascertain → find out, assistance → help, obtain → get, modification → change, implement → carry out, optimal → best, regarding → about, methodology → method, in the event of → if. + +**Problem:** Long Latinate words signal effortful writing without adding precision. Anglo-Saxon roots are shorter and clearer. + +**Before:** +> The system will utilize advanced algorithms to facilitate optimal performance. Prior to deployment, we must ascertain that the methodology is sufficient. + +**After:** +> The system uses algorithms to get the best performance. Before deployment, we must check that the method works. + +### 27. Active Over Passive Voice + +**Detection:** "to be + past-participle" patterns where the actor is recoverable from context. + +**Problem:** Passive voice hides who did what. Active voice is shorter and clearer in most cases. Skip when the actor genuinely doesn't matter (technical writing about an inanimate process: "the table was created in 2024" can stay passive). + +**Before:** +> The migration was run by the deployment script. The bug was introduced in commit abc123. The fix was applied by the team. + +**After:** +> The deployment script ran the migration. Commit abc123 introduced the bug. The team applied the fix. + +**Suggestion-only in v1.** When in doubt, flag rather than auto-rewrite — passive is sometimes the right choice in technical contexts. + +### 28. Comma Splices + +**Detection:** Two independent clauses joined only by a comma. + +**Problem:** Comma splices read as run-ons. Either split into two sentences, join with a conjunction, or use a semicolon (in personal mode this becomes a period). + +**Before:** +> The build failed, the test suite reported three errors. + +**After:** +> The build failed. The test suite reported three errors. + +### 29. Cliché Flag + +**Words to watch:** at the end of the day, moving forward, going forward, at this juncture, circle back, low-hanging fruit, deep dive, leverage (as verb), synergy, take it offline, ducks in a row, boil the ocean, pivot (corporate sense). + +**Problem:** Clichés signal effortful prose without saying anything specific. Replace with the actual meaning. + +**Before:** +> At the end of the day, we need to leverage our core competencies and circle back on the low-hanging fruit. + +**After:** +> We need to use what we already do well and start with the easiest improvements first. + +### 30. Jargon-Fragment → Complete Sentence + +**Detection:** Sentence-like fragments inside prose paragraphs that read as bullet-list shorthand. Headings and bullet items are exempt — fragments are valid there. + +**Problem:** Telegraphic fragments in prose paragraphs read as bullet-style notes leaking into running text. They lose the connective tissue a complete sentence carries. + +**Before:** +> The new function handles edge cases. Empty input throws. Whitespace gets trimmed. Returns null on no match. + +**After:** +> The new function handles edge cases. It throws on empty input, trims whitespace, and returns null when no match is found. + +### 31. Noun-ified Verbs + +**Words to watch:** the ask, a learn, the spend, a build, the reveal, a do, the lift, the get, the say. + +**Problem:** Corporate-speak nominalization. Use the real noun: "the request", "the lesson", "the budget", "the system", "the finding". Note this targets corporate-speak patterns specifically; philosophical nominalizations like "the becoming" or "the unfolding" are different and don't trigger this pattern. + +**Before:** +> The ask was for a quick build. After the reveal, we'll do a learn. + +**After:** +> The request was for a quick prototype. After the announcement, we'll review what worked. + +## Personal Voice (personal mode only) + +These eight patterns apply only when the skill is invoked in personal mode (`/voice personal`) for commits, PR titles + bodies, and PR review comments. They are explicitly skipped in general mode because they conflict with academic, literary, or formal registers — third-person is valid in academic prose, semicolons are conventional in long-form writing, contractions are typically avoided in formal text, and so on. + +### 32. First-Person Voice Rewrite (personal only) + +**Detection:** Impersonal third-person construction in a publish-artifact body where first-person fits naturally. + +**Problem:** Impersonal third-person ("Add support for X", "The change adds Y") reads as press-release voice in a commit body or PR description. First-person ("I added X", "I missed Y", "I kept Z because...") sounds like one engineer talking to another. + +The subject line of a commit stays imperative per Conventional Commits ("feat: add support for X"). The body shifts to first person. Skip the rewrite for purely mechanical changes (a chore version bump, a typo fix) where the subject alone carries the message. + +**Before:** +> Adds the new validation step before saving. The previous flow allowed empty values to leak into the database. This change blocks them at the API boundary. + +**After:** +> I added a validation step before saving. The previous flow let empty values leak into the database. I'm blocking them at the API boundary now. + +### 33. Semicolon → Period or Comma (personal only) + +**Detection:** Semicolons in commit-message bodies, PR descriptions, or PR review comments. + +**Problem:** Few engineers use semicolons in prose. They make the writing feel unnecessarily literary. Replace with a period (split into two sentences) or a comma (when the clauses are tightly coupled). + +**Before:** +> I added the validation; the previous flow allowed empty values to leak through. + +**After:** +> I added the validation. The previous flow allowed empty values to leak through. + +### 34. Contractions (personal only) + +**Detection:** Uncontracted forms in publish-artifact prose where the contraction reads more naturally. + +**Problem:** Uncontracted English reads stiff in a short prose body unless a negation or emphasis needs the weight. Prefer "it's", "that's", "don't", "we're", "I'd", "won't" in commit and PR prose. + +**Before:** +> It is worth noting that the change does not break the existing flow. We are confident that this is the right approach. + +**After:** +> It's worth noting the change doesn't break the existing flow. We're confident this is the right approach. + +(Note: pattern #38 catches "worth noting" as rhetorical padding — the example above shows isolated transformation; in practice both passes apply.) + +### 35. Sentence Split on Conjunctions (personal only) + +**Detection:** Sentences that stack three or four clauses with commas and conjunctions ("so", "and", "but"), where splitting on a conjunction would not lose meaning. + +**Problem:** Long compound sentences read easier as two or three shorter ones in a publish-artifact body. Skip in academic or literary prose where deliberate long sentences are the register. + +**Before:** +> I added the validation step before saving so empty values get blocked at the API boundary, and I also added a regression test that exercises the empty-string case, but I did not change the upstream caller because that's a separate concern. + +**After:** +> I added the validation step before saving so empty values get blocked at the API boundary. I added a regression test that exercises the empty-string case. I didn't change the upstream caller because that's a separate concern. + +### 36. Felt-Experience Narration (personal only) + +**Detection:** Phrases that tell the reader how the change will feel or how often the writer will use it. + +**Problem:** Phrases like "I'll feel this every time I commit", "this will be a relief", "I'm excited about", "this is going to be huge for productivity" read as performance, not communication. State what changed and let the reader decide what to do with it. + +**Before:** +> I'm so excited about this — I'll feel the speedup every time I run the build. This is going to be a huge relief. + +**After:** +> The build now finishes in roughly half the time it used to take. + +### 37. Sentence Fragments → Complete (in prose, personal only) + +**Detection:** Sentence fragments inside prose paragraphs in a commit or PR body. Bullets and headings remain fair game for fragments. + +**Problem:** Bullet shorthand leaking into running prose ("Two changes." "Fix incoming." "Body as decision log.") reads as bullet-list notes pasted into a paragraph. Every prose sentence needs a subject and a verb in personal mode. + +**Before:** +> Big change to the validator. Three new patterns. Test coverage up. Old behavior preserved. + +**After:** +> I made a big change to the validator. There are three new patterns and the test coverage is up. The old behavior is preserved. + +### 38. Terse Cut — Rhetorical Padding (personal only) + +**Detection:** Padding phrases that add length without meaning: "worth noting", "it's important to understand", "as you can see", "needless to say", "obviously", "of course", "in essence", "fundamentally". + +**Problem:** Tier 1 omit-needless-words (#26) catches the most rigid offenders ("the fact that", "in order to"). Personal mode is more aggressive: also strip soft padding like "worth noting" and "it's important to understand". State the thing directly. Academic writing often retains these as transition markers; the aggressive cut is publish-only because it conflicts with that register. + +**Before:** +> It's worth noting that the change doesn't break the existing flow. Needless to say, the test suite is green. Obviously, this means we can ship. + +**After:** +> The change doesn't break the existing flow. The test suite is green. We can ship. + +### 39. Public-Artifact Scope Check (personal only — flag only) + +**Detection:** Local absolute paths (`/home/<user>/...`, `/Users/<user>/...`), private repo names (any repo not in this project's known public set), personal-tooling references (`humanizer`, `voice`, `commits.md`, anything under `claude-rules/`, anything under `.ai/` or `.claude/`). + +**Problem:** Commit messages, PR descriptions, PR comments, and Linear ticket bodies are visible to teammates and anyone with read access. References to the writer's personal layout are noise to a reader who can't reproduce it. + +**Behavior in this skill: flag-only, no auto-rewrite.** Surface each match as a warning. The user resolves manually because auto-masking risks silently editing meaningful content (a legitimate file path mention may be load-bearing; only the author can tell). + +**Output format for matches:** +``` +WARN: line 12: "/home/cjennings/code/rulesets" — local absolute path in commit body +WARN: line 18: "claude-rules/commits.md" — personal-tooling reference; state the underlying reason instead +``` + +## Process + +1. Read the input text carefully. Confirm the mode (general or personal) — invocation argument or context. +2. Walk patterns 1-31 in general mode; walk all 39 patterns in personal mode. +3. For each pattern, scan the text. If a match is found, rewrite it according to the pattern's rule. Pattern #39 emits warnings without rewriting. +4. After walking all patterns, ensure the revised text: + - Sounds natural when read aloud + - Varies sentence structure + - Uses specific details over vague claims + - Maintains appropriate tone for the register +5. Present a draft humanized version. +6. Run a final anti-AI pass: prompt "What makes the below so obviously AI generated?" Answer briefly with remaining tells. Then prompt "Now make it not obviously AI generated" and revise. +7. Present the final version. + +## Output Format + +Provide: +1. **Draft rewrite** — the text after walking all applicable patterns +2. **Mode used** — general or personal +3. **What makes the below so obviously AI generated?** — brief bullets +4. **Final rewrite** — revised after the anti-AI audit +5. **Pattern-39 warnings** (personal mode only) — any public-artifact scope flags +6. **Summary of changes** — list of patterns that fired (e.g., "patterns 4, 7, 13, 22 in general mode") + +## Full Example — Personal Mode + +**Before** (a commit message draft from a model): +> Adds new validator for empty input handling. +> +> The previous validation logic in `~/code/rulesets/voice/SKILL.md` allowed empty strings to leak through to the database layer; this change introduces a guard at the API boundary that returns a 400 response when the input field is empty or contains only whitespace, ensuring data integrity is maintained throughout the request lifecycle. It is worth noting that this does not affect the upstream caller, and we are excited about the productivity gains this will provide. +> +> Furthermore, the new pattern leverages our existing validation framework to deliver a robust, scalable, and maintainable solution. + +**Mode used:** personal + +**Draft rewrite (after walking patterns 1-39):** +> feat(api): add empty-input guard at the validator boundary +> +> I added a guard that rejects empty or whitespace-only input fields at the API boundary with a 400 response. The previous flow let empty values leak through to the database layer. +> +> The change doesn't affect the upstream caller — that's a separate concern. The new pattern reuses the existing validation framework. + +**What makes the below so obviously AI generated?** +- "ensuring data integrity is maintained throughout the request lifecycle" was a textbook -ing-phrase analysis (pattern #3) +- "we are excited about the productivity gains" was felt-experience narration (pattern #36) +- "robust, scalable, and maintainable" was rule-of-three (pattern #10) + +**Final rewrite:** +> feat(api): add empty-input guard at the validator boundary +> +> I added a guard that rejects empty or whitespace-only input fields at the API boundary with a 400 response. The previous flow let empty values leak through to the database layer. +> +> The change doesn't affect the upstream caller — that's a separate concern. The new pattern reuses the existing validation framework. + +**Pattern-39 warnings:** +- WARN: original draft line 3: `~/code/rulesets/voice/SKILL.md` — local absolute path. State the underlying validation behavior instead. + +**Summary of changes:** +- Patterns that fired in personal mode: #3 (-ing analysis), #4 (promotional language), #10 (rule of three), #29 (cliché flag — "leverages"), #32 (first-person voice), #34 (contractions), #36 (felt-experience), #38 (terse cut: "It is worth noting"), #39 (public-artifact scope warning) + +## Full Example — General Mode + +**Before** (a paragraph from a research note): +> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance. The institute serves as a vital component of the regional statistical landscape, showcasing how decentralized data collection can foster more accurate regional reporting. + +**Mode used:** general + +**Draft rewrite:** +> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office. It was part of a wider movement to decentralize administrative functions across Spain. Decentralized data collection produces more accurate regional reporting than the previous centralized approach. + +**What makes the below so obviously AI generated?** +- The phrase "more accurate regional reporting than the previous centralized approach" still has a slight summary-paragraph rhythm. A human writer might just say what changed and stop. + +**Final rewrite:** +> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office. It was part of a wider movement to decentralize administrative functions across Spain. Regional reporting got more accurate after the change. + +**Summary of changes:** +- Patterns that fired in general mode: #1 (significance inflation: "pivotal moment", "evolution of"), #4 (promotional: "vital component"), #3 (-ing analysis: "showcasing how... can foster"), #8 (copula avoidance: "serves as"), #26 (long-word: removed Latinate constructions). General mode skipped patterns #32-39 (personal only). + +## Reference + +This skill draws from: +- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) — patterns #1-25, maintained by WikiProject AI Cleanup. +- Strunk & White, *The Elements of Style* — patterns #28 (comma splices), #26 (omit needless words, supplemented by humanizer pattern #22). +- Orwell, *Politics and the English Language* — patterns #26 (short over long), #27 (active over passive), #29 (cliché). +- Plain English Campaign — pattern #26 (Plain English wordlist). +- Garner, *Modern English Usage* — pattern #26 (word-pair preferences). +- Personal voice rules from `claude-rules/commits.md` (Voice and Focus section) — patterns #32-39. + +Key insight (Wikipedia, paraphrased): LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely text that applies to the widest variety of cases. Patterns #1-25 detect that signature. + +Key insight (Orwell): "If it is possible to cut a word out, always cut it out." Patterns #22, #23, #26, #38 act on this rule at increasing levels of aggressiveness depending on register. |