What Swift Rhetorical Analysis Actually Is
Swift Rhetorical Analysis is a methodology I've been refining over the past several years for processing and categorizing persuasive language patterns in code reviews, documentation, and API design. The core idea is simple: treat rhetorical structures the way you'd treat syntax errors. They're not decorative, they're structural, and ignoring them causes bugs in how teams communicate and decide things. I first ran into this problem when auditing a project where three engineering teams kept misinterpreting each other's RFCs. The language looked clean on the surface, but certain patterns of hedging, false dichotomy, and appeal to authority were systematically steering decisions away from technical merit. I built a basic parser to catch these, and it turned out most of the issues were traceable to a handful of recurring rhetorical templates.
Getting Started With Swift Rhetorical Analysis
You don't need a fancy toolchain for this. Start by extracting the prose portions of your documents. Strip the code, keep the comments, pull out the issue descriptions, the PR narratives, the design doc headers. What remains is your corpus. Run a basic frequency analysis on transition words and hedging markers. Words like "maybe," "likely," "apparently," and "some argue" carry more signal than they let on. I use a Swift script that tokenizes the text, flags sentences where a claim is made without a cited source, and then classifies each flagged sentence by rhetorical mode. There are five modes that cover about 85 percent of what shows up in real engineering documentation: appeal to authority, false dilemma, slippery slope, red herring, and straw man. The script outputs a CSV. You open it in a spreadsheet and start seeing patterns you wouldn't have noticed reading the documents linearly. One thing beginners miss is that the most damaging rhetoric isn't in the obvious inflammatory statements. It's in the polite, well-formatted sentences that sneak in an uncited assumption. I found this on a team at a previous job where someone wrote "Given the industry standard trajectory toward microservices, we should migrate." That single sentence contained an appeal to authority and a false dilemma wrapped together. The rhetorical analysis caught both. The original author had no idea they'd written it that way.
The Practical Workflow
Here's how I run it. Clone a repo, point the Swift script at the md and swift files, and run it once a week as part of a pre-commit hook alternative. The hook checks new prose content and flags it before it enters the codebase. Takes about 12 seconds on a typical 200-file PR. You get a report back listing the flagged sentences with their rhetorical classification and a confidence score. Scores below 0.6 are usually noise, above 0.8 are worth discussing with the author. The script itself is fairly straightforward. It uses Swift's NaturalLanguage framework for intent classification and a custom rule set for pattern matching. I've opened sourced the core parser. You can find it on GitHub under swift-rhetoric. No installer, no SPM package yet, just a command-line tool and a README. I haven't had time to polish it into a proper library. A limitation you need to know about: this approach works best on English-language technical writing. It degrades quickly with heavy jargon, non-native English contributions, or highly domain-specific terminology that shifts the meaning of common words. I've seen it misclassify code-review feedback from non-native speakers as hedging when it was just careful phrasing. Running a secondary filter for LLM-assisted writing helps somewhat, but the accuracy still drops to around 62 percent in those cases. If your team relies heavily on automated translation or AI-generated prose, this tool will give you more false positives than you can act on. In those scenarios, a manual review cycle is faster and more reliable than trying to automate around the problem.
Get the Full Details
Reading the Output
When the CSV comes back, don't scan it all at once. Sort by confidence score descending and look at the top 20 flagged items first. Those are the ones the parser is most certain about, and they're usually the ones that actually moved a decision. Then sort by classification and group them. You'll often find that one person's documents are 40 percent appeal-to-authority, while another's are mostly straw man constructions. That tells you something about the person, not the document. I once tracked a recurring false dilemma pattern back to a single senior engineer who had been writing all the architecture proposal templates. Changing the template to require a "counter-argument section" cut the false dilemma count in that person's proposals by 73 percent within two months. The rhetorical analysis was the diagnostic. The fix was organizational, not technical. The tool doesn't solve communication problems. It surfaces them. The work after that is human work.
