Yila-AI/awesome-defensive-writing / skills/yila-clear-writing
yila-clear-writing
VerifiedDiagnose and revise AI defensive padding in drafts, reports, emails, research prose and public explanations when the user requests less hedging or clearer claims. Preserve evidence strength and meaningful reader guidance.
references/examples-en.md
View on GitHub# Complete writing examples
**English** | [简体中文](examples-zh.md)
These constructed scenarios provide the facts, a flawed draft, a suggested revision and editing reasons. Choose a similar task and substitute your own material to practice.
- [EX-01 Say the same thing clearly](#ex-01)
- [EX-02 A forecast is not a promise](#ex-02)
- [EX-03 An observational finding](#ex-03)
- [EX-04 Contribution and revision status](#ex-04)
- [EX-05 Distinguish an objective from an achievement](#ex-05)
- [EX-06 A real dependency and fallback](#ex-06)
- [EX-07 A blocker and revised schedule](#ex-07)
- [EX-08 Retrospective and resource request](#ex-08)
- [EX-09 Decline scope expansion courteously](#ex-09)
- [EX-10 Ask honestly and retain responsibility](#ex-10)
- [EX-11 A feature and its beta scope](#ex-11)
- [EX-12 A case is not a performance guarantee](#ex-12)
- [EX-13 A clear point with source boundaries](#ex-13)
- [EX-14 Explain a preprint within its scope](#ex-14)
- [EX-15 A complete tutorial path](#ex-15)
- [EX-16 A prohibition and a real trade-off](#ex-16)
- [EX-17 Chart denominators and samples](#ex-17)
- [EX-18 An inconclusive result is not equivalence](#ex-18)
- [EX-19 A learning record is not proficiency](#ex-19)
- [EX-20 Experience, resources and next steps](#ex-20)
- [EX-21 A code-review comment with a trigger](#ex-21)
- [EX-22 Choose against the goal and report the trade-off](#ex-22)
- [EX-23 A review must not invent its sources](#ex-23)
- [EX-24 Answer a pricing question directly](#ex-24)
- [EX-25 A progress follow-up with a clear reply time](#ex-25)
<a id="ex-01"></a>
## EX-01 · Say the same thing clearly
**Supplied facts**
The meeting confirmed prototype delivery on Thursday, followed by testing. Delivery refers to the prototype, not completed testing.
**Verbose or flawed draft**
Given the project's complexity, we may try to aim for prototype delivery on Thursday. Of course, this does not mean that all work is finished.
**Suggested revision**
The prototype will be delivered on Thursday, followed by testing.
**Why**
The source contains a firm delivery agreement. Remove wording that weakens it and use the testing step to state scope.
**Boundary to preserve**
If Thursday is only an internal target, write 'targeting Thursday' rather than copying this commitment.
<a id="ex-02"></a>
## EX-02 · A forecast is not a promise
**Supplied facts**
At the current workload, completion is estimated for Thursday. New data arriving Wednesday would move the estimate to Friday. No fixed date has been promised to the client.
**Verbose or flawed draft**
Completion might possibly be around Thursday, although the situation is complex and uncertainty remains.
**Suggested revision**
At the current workload, completion is estimated for Thursday, or Friday if new data arrives Wednesday.
**Why**
Replace stacked hedges with an explicit estimate and the supplied condition that changes timing.
**Boundary to preserve**
Keep the estimate and data-arrival condition; do not write 'will finish Thursday'.
<a id="ex-03"></a>
## EX-03 · An observational finding
**Supplied facts**
Fictional teaching data: a single-center observational study of 120 adults found Pearson r=0.32 between A and B, 95% CI 0.15–0.47. There was no random assignment or causal identification.
**Verbose or flawed draft**
The findings may to some extent suggest that A might have some connection with B. More research is needed before drawing conclusions.
**Suggested revision**
In this single-center observational study of 120 adults, A and B were positively correlated (r=0.32, 95% CI 0.15–0.47).
**Why**
Report the association directly; design, sample and interval state its evidential scope without generic retreat.
**Boundary to preserve**
Do not change the finding to causation. If surrounding text invites a causal reading, explicitly correct it.
<a id="ex-04"></a>
## EX-04 · Contribution and revision status
**Supplied facts**
Fictional study: the team harmonized public budget fields for three cities in 2019–2023 and supplied scripts. Notes cover only two related papers and cannot support a first-ever claim. A reviewer requested evidence for nationwide generalization. The authors narrowed the conclusion to the three cities; they added no regions or representativeness tests.
**Verbose or flawed draft**
Our work merely performs some preliminary organization and has very limited value. We fully agree with the reviewer and have added extensive analysis demonstrating applicability.
**Suggested revision**
The study harmonizes public budget-field coding for three cities in 2019–2023 and provides processing scripts. In response to the generalization concern, we narrowed the conclusion to these cities; the current data do not support nationwide generalization.
**Why**
Retain the actual contribution and completed scope revision while removing self-deprecation and a fabricated analysis.
**Boundary to preserve**
The generalization exclusion matters here. Stating a three-city focus does not justify broad claims elsewhere.
<a id="ex-05"></a>
## EX-05 · Distinguish an objective from an achievement
**Supplied facts**
Fictional project: a library logs bookings manually in spreadsheets; three staff interviews report duplicate entry. The team has two weeks of sandbox access and plans a booking-form prototype, checking required fields and duplicate-submission blocking with five predefined test records. Development has not been completed; no user-scale data are available.
**Verbose or flawed draft**
Booking management is a serious issue affecting tens of thousands. We might try to explore improvements and have already substantially solved duplicate entry.
**Suggested revision**
Three staff interviews identified duplicate entry in booking records. During the two-week sandbox period, the project plans to develop a booking-form prototype and test required fields and duplicate-submission blocking with five predefined records.
**Why**
Replace fabricated scale, vague attempts and false completion with the supported problem and assessable objective.
**Boundary to preserve**
The interviews do not establish population prevalence; five records constitute a functional check, not an effectiveness study.
<a id="ex-06"></a>
## EX-06 · A real dependency and fallback
**Supplied facts**
Fictional project: authorized data precede cleaning and a trial run. Compute is available but data approval is pending. Friday is the team's decision point: without approval, use public samples next week to check the pipeline. Public samples cannot substitute for project data in the final evaluation.
**Verbose or flawed draft**
The project has many complex risks, and data issues could prevent any progress, making feasibility difficult to assess.
**Suggested revision**
Compute is ready; data approval is pending. If approval has not arrived by Friday, use public samples next week to check the pipeline. Final evaluation still requires authorized project data.
**Why**
Replace blanket pessimism with available resources, a decision trigger and a feasible fallback.
**Boundary to preserve**
Do not describe the public-sample run as completed project evaluation or approval as already obtained.
<a id="ex-07"></a>
## EX-07 · A blocker and revised schedule
**Supplied facts**
Fictional update: page development is complete; API access has not been enabled; integration testing has not started. A testable build was due Tuesday and is now committed for Thursday. The owner asks the project manager to coordinate access today. The meeting confirmed this revision.
**Verbose or flawed draft**
Overall progress is good and we are working hard. Due to complexity, there might be a slight delay; thank you for understanding.
**Suggested revision**
Page development is complete, but API access is still unavailable and integration testing has not started. Delivery of a testable build moves from Tuesday to Thursday. The project manager is asked to coordinate API access today.
**Why**
State completion, blocker, revised commitment and requested action rather than empty assurances.
**Boundary to preserve**
Do not say integration testing is complete. An unconfirmed date must remain an estimate with its dependency.
<a id="ex-08"></a>
## EX-08 · Retrospective and resource request
**Supplied facts**
Fictional incident: Wednesday delivery was two hours late. Logs show the build machine's disk was full; clearing the cache restored operation. The team agreed to a pre-delivery space check and requests a spare drive with a budget ceiling of CNY 600; approval is pending. There is no evidence of individual negligence.
**Verbose or flawed draft**
We have many shortcomings and need comprehensive reflection; some people may not have been careful enough. We hope management might consider offering some support.
**Suggested revision**
Wednesday delivery was delayed by two hours because the build machine's disk was full; clearing the cache restored operation. The team adds a pre-delivery space check and requests a spare drive costing no more than CNY 600, pending approval.
**Why**
Use a verified cause and concrete improvement, with an explicit pending resource request.
**Boundary to preserve**
Do not assign unsupported personal blame or turn a pending budget into a completed purchase.
<a id="ex-09"></a>
## EX-09 · Decline scope expansion courteously
**Supplied facts**
Fictional collaboration: this week's agreed deliverable is a Chinese abstract. An English full-text request is new and unagreed. The team has no capacity this week and can assess its schedule next week, without promising completion then. The Chinese abstract remains due Friday.
**Verbose or flawed draft**
We are terribly sorry for our limited capabilities and may not do well, but we will try to meet everything.
**Suggested revision**
The Chinese abstract remains due Friday as agreed. We cannot add the English full text this week, but can assess its schedule next week. Please confirm whether you would like that assessment arranged.
**Why**
Retain the existing obligation and set a truthful boundary for the added request without using false promises as courtesy.
**Boundary to preserve**
Assessment next week is not completion next week; the existing Chinese deliverable remains owed.
<a id="ex-10"></a>
## EX-10 · Ask honestly and retain responsibility
**Supplied facts**
Fictional email: Lin is a third-year undergraduate with one data-cleaning course assignment and no papers. Lin wants to ask whether a supervisor could give brief advice on a data-quality topic. Lin missed a Tuesday commitment to send materials through an omission; the materials are now ready and attached.
**Verbose or flawed draft**
I am not competent enough to trouble you. The earlier materials may not have been sent on time for various reasons, and I have caused inconvenience. I may have some immature ideas about the topic; please advise.
**Suggested revision**
Hello Professor, I am Lin, a third-year undergraduate who completed a data-cleaning course assignment. I would appreciate brief advice on a data-quality topic, if you are available. I apologize for omitting the materials I had agreed to send Tuesday; they are now attached.
**Why**
Replace self-deprecation with actual identity and a specific request; acknowledge the omission and provide the remedy.
**Boundary to preserve**
An apology for a real omission must remain; do not invent the professor's research interests.
<a id="ex-11"></a>
## EX-11 · A feature and its beta scope
**Supplied facts**
Fictional product P: users on the current beta list can upload a PDF and choose a template to generate an editable figure draft. Public registration is not open. No efficiency study, free-use policy or submission-quality guarantee has been supplied. Release notes may announce only this beta capability.
**Verbose or flawed draft**
We might provide some assistance to some extent. Everyone can use it free and get submission-ready figures in one click.
**Suggested revision**
Users in the current beta can upload a PDF and choose a template to generate an editable figure draft. Public registration is not yet open.
**Why**
State the task clearly while retaining eligibility and draft status; remove redundant retreat and unsupported promotion.
**Boundary to preserve**
For a real product, supply its confirmed features, eligibility, pricing and availability.
<a id="ex-12"></a>
## EX-12 · A case is not a performance guarantee
**Supplied facts**
Fictional case: user A permits anonymous use of 'I turned scattered notes into an outline.' Records show notes imported and the generated outline manually revised. No timing, comparison group or quality score exists. The FAQ asks whether manual editing can be avoided in every task. The team confirms it cannot guarantee freedom from manual editing.
**Verbose or flawed draft**
This is merely a small preliminary attempt that may help some people; it has proven tenfold efficiency for everyone with no editing needed.
**Suggested revision**
User A shared: 'I turned scattered notes into an outline.' The workflow included importing notes and manually revising the result. The case illustrates one way to organize notes; it does not guarantee editing-free results for every task.
**Why**
Use the authorized quote and observed workflow while directly answering the guarantee question.
**Boundary to preserve**
The explicit exclusion answers a real question and must remain; do not invent an efficiency multiplier.
<a id="ex-13"></a>
## EX-13 · A clear point with source boundaries
**Supplied facts**
Fictional script material: the author inspected three of their own AI-edited drafts; two repeated 'for reference only.' The video demonstrates sentence-level checking. This is personal observation, not a model comparison. The video is a paid partnership and must disclose it. No paper data are supplied.
**Verbose or flawed draft**
My view may be immature, so please don't criticize me. All AI produces empty prose because its moral sensitivity is too high.
**Suggested revision**
This video is a paid partnership. In three of my AI-edited drafts, two repeated 'for reference only.' I will use sentence-level checking to see whether those phrases add information.
**Why**
A personal observation can introduce a tutorial but cannot establish a universal model mechanism. Keep sponsorship disclosure.
**Boundary to preserve**
Do not invent research support, enlarge the sample or remove sponsorship disclosure.
<a id="ex-14"></a>
## EX-14 · Explain a preprint within its scope
**Supplied facts**
Teaching source summary: a preprint compares qualifications across writing requests, including review-oriented requests. Its abstract distinguishes redundant qualifications from retractions that correct overclaims. It does not establish claims about all models, all domains or a moral-sensitivity mechanism. A reader asks whether all cautious sentences should be deleted.
**Verbose or flawed draft**
The issue is complex and needs a balanced view; all perspectives have merit and generalization may be inappropriate.
**Suggested revision**
Do not delete a sentence based on wording alone. The preprint distinguishes redundant qualifications from retractions that correct overclaims: the former may burden readers, while the latter may be necessary. Check whether the sentence changes the valid scope of the claim.
**Why**
Answer the question with an operational distinction rather than empty balance.
**Boundary to preserve**
Use the supplied summary only; do not add experimental numbers that were not supplied or verified.
<a id="ex-15"></a>
## EX-15 · A complete tutorial path
**Supplied facts**
Fictional offline-tool instructions: on a tested Windows setup, copy the whole sample-skill folder into the client's configured skills directory, retaining references. Reload the client and check for sample-skill. Copying only SKILL.md loses references. If it is missing, first check folder nesting. No install command or other tested operating system is supplied.
**Verbose or flawed draft**
Installation may carry various risks; proceed cautiously. Copy a file and it will work on every system.
**Suggested revision**
On the tested Windows setup, copy the whole sample-skill folder into the client's configured skills directory, retaining references. Reload the client and check for sample-skill; if missing, check whether the folder is nested one level too deep.
**Why**
Keep the environment, full-folder requirement and observable check; remove generic caution and universal compatibility claims.
**Boundary to preserve**
Do not omit references or invent a one-command installer or default path.
<a id="ex-16"></a>
## EX-16 · A prohibition and a real trade-off
**Supplied facts**
Fictional maintenance task: power must be disconnected before opening the service cover; opening it while powered is prohibited. Records need equipment ID and date. Route A organizes records without opening the cover. Route B checks internal wiring and requires opening the cover only after disconnection. These prerequisites are supplied; no other procedure is requested.
**Verbose or flawed draft**
Always remember safety and try to disconnect power before opening. For simplicity, both routes can be described as directly checking the device.
**Suggested revision**
Route A: organize maintenance records with equipment ID and date; no cover opening is needed. Route B: disconnect power before opening the service cover to check internal wiring. Opening while powered is prohibited.
**Why**
Replace admonition with operational language while retaining the prohibition and route distinction.
**Boundary to preserve**
The prohibition is not optional; do not collapse distinct routes into the same operation.
<a id="ex-17"></a>
## EX-17 · Chart denominators and samples
**Supplied facts**
Fictional chart: activity A has 20 completions among 100 participants; B has 30 among 200. Participants self-selected into different groups, without random assignment, in the same period. The requested comparison is completion rate, not count.
**Verbose or flawed draft**
B has more people, so it is clearly more effective. Of course, many factors may exist, so nothing can be concluded.
**Suggested revision**
A's completion rate is 20% (20/100), versus 15% (30/200) for B. The groups self-selected, so the comparison describes completion rates rather than identifying causal effects.
**Why**
Compute the supported rates, retain denominators and correct the causal overclaim.
**Boundary to preserve**
More completions do not establish better effectiveness; lack of causal identification does not prevent a descriptive comparison.
<a id="ex-18"></a>
## EX-18 · An inconclusive result is not equivalence
**Supplied facts**
A constructed study reports a difference test: the estimated group difference is 2 points, 95% CI −1 to 5, p=0.18. No equivalence margin was prespecified and no equivalence test was reported. The task is to report the analysis.
**Verbose or flawed draft**
The result is not significant, which may mean the study has little value. The situation is complex and more research may be needed, so it seems best to draw no conclusion.
**Suggested revision**
The difference test did not detect a significant difference: the estimate was 2 points, 95% CI −1 to 5, p=0.18. No equivalence margin was prespecified and no equivalence test was reported, so these results do not provide evidence of equivalence.
**Why**
Replace blanket self-dismissal with the estimate, interval and supported interpretation.
**Boundary to preserve**
Difference and equivalence tests address different questions; an interval crossing zero alone does not determine equivalence.
<a id="ex-19"></a>
## EX-19 · A learning record is not proficiency
**Supplied facts**
Fictional learner: an undergraduate with two hours a week completed three introductory lessons and can read CSVs with an example, but cannot independently clean missing values. The near-term goal is independently cleaning a small table with missing values. There are no research projects or publications.
**Verbose or flawed draft**
I am just a poor beginner, although I have mastered data analysis. Learning varies by person, so there is little to say.
**Suggested revision**
I have completed three introductory lessons and can read CSVs using an example. Next I will practice handling missing values independently, using my two hours a week to clean a small table and check whether I can repeat it without the example.
**Why**
Use observable capability, a specific gap and a checkable task instead of self-denigration or fabricated mastery.
**Boundary to preserve**
The proposed check is not an achieved result; do not invent a research identity.
<a id="ex-20"></a>
## EX-20 · Experience, resources and next steps
**Supplied facts**
Fictional material: the author used exercise-based resource A for one table-cleaning exercise. Resource B consists of theory notes, with no completed exercise by the author. The reader wants table-cleaning practice with one hour weekly. Prices, update dates and general effectiveness are unknown.
**Verbose or flawed draft**
Please don't criticize me; this is only my personal view. A and B are both good and bad; A will definitely make anyone proficient in a week.
**Suggested revision**
If the goal is table-cleaning practice, start with exercise-based A. I used it for one cleaning exercise; B focuses on theory notes. Use the next hour for one A exercise, then check whether you can reproduce it independently. Prices and update status still need verification.
**Why**
Make a goal-based recommendation grounded in actual experience and retain unknowns.
**Boundary to preserve**
One experience cannot establish universal learning outcomes or justify invented prices or freshness.
<a id="ex-21"></a>
## EX-21 · A code-review comment with a trigger
**Supplied facts**
Fictional code: def first(items): return items[0]. Empty lists are possible. The reviewer has not run tests. The interface specifies None for empty input.
**Verbose or flawed draft**
This implementation might not be very elegant; consider some edge cases carefully. I tested it and everything passed.
**Suggested revision**
When items is empty, items[0] raises IndexError rather than returning None as the interface specifies. Add an empty-list check returning None. Tests have not been run.
**Why**
State a verifiable trigger and consequence; remove vague aesthetic criticism and a fabricated test claim.
**Boundary to preserve**
A static assessment is not an executed test; without an empty-input contract, do not invent the return value.
<a id="ex-22"></a>
## EX-22 · Choose against the goal and report the trade-off
**Supplied facts**
Constructed selection task: offline operation is required, lower latency is the priority, and an accuracy decrease of up to 1 percentage point is acceptable. A and B both support the required offline format. On the same machine and test set, A has 90% accuracy and 100 ms latency; B has 89% accuracy and 60 ms latency. Pricing is not supplied.
**Verbose or flawed draft**
Both tools have pros and cons, and there are many uncertainties, so it is difficult to judge. B also loses accuracy and can only be considered cautiously; it depends on the user.
**Suggested revision**
Choose B for the stated goal. Both meet the offline requirement; B reduces latency from 100 to 60 ms while accuracy falls from 90% to 89%, meeting the allowed 1-percentage-point decrease.
**Why**
Turn empty balance into a comparable assessment and conditional choice, stating both gain and cost.
**Boundary to preserve**
Keep the accuracy loss alongside the latency gain; pricing remains to be checked.
<a id="ex-23"></a>
## EX-23 · A review must not invent its sources
**Supplied facts**
Fictional source notes: study A interviewed people in two cities and found unclear application steps. Study B analyzed one platform's completion records and reported an association between missing information and resubmissions. Only these two notes were searched; titles, authors and years are not supplied.
**Verbose or flawed draft**
The issue is very complex, and different studies have different views. A balanced perspective may be needed, and it currently seems hard to reach a useful judgment; more research is needed.
**Suggested revision**
Both notes concern application information: study A addresses understanding of steps, while study B reports an association between missing information and resubmission. Their populations and methods differ, and the supplied material cannot establish comparative prevalence.
**Why**
Synthesize the supplied studies through their subjects, findings and methods instead of empty balance.
**Boundary to preserve**
Do not invent authors, dates or citations; two notes do not establish a field-wide consensus.
<a id="ex-24"></a>
## EX-24 · Answer a pricing question directly
**Supplied facts**
Fictional product rules: visitors can view public examples; exporting requires a paid plan, with no free export allowance. The user asks whether export is available without payment. No other capabilities need describing.
**Verbose or flawed draft**
We value different user needs, and circumstances may vary; we suggest exploring for yourself.
**Suggested revision**
No. Export requires a paid plan and has no free allowance. You can view the public examples first.
**Why**
Answer the known rule directly and offer a real available option instead of evasive filler.
**Boundary to preserve**
Keep the direct answer and real viewing option; supply the pricing rules of the target product.
<a id="ex-25"></a>
## EX-25 · A progress follow-up with a clear reply time
**Supplied facts**
Constructed collaboration: Chen agreed to deliver design figures Friday; today is Thursday. To schedule integration testing, the owner needs Chen to confirm progress and whether Friday delivery is on track by 17:00 today. There is no evidence of a missed deadline.
**Verbose or flawed draft**
Sorry to trouble you again; I know you may be busy. Perhaps you could look at the figures whenever convenient. No rush, and sorry for the inconvenience.
**Suggested revision**
Chen, the design figures are due Friday as agreed. To schedule integration testing, please confirm current progress and whether Friday delivery is on track by 17:00 today. Thank you.
**Why**
Keep normal courtesy while stating the existing delivery agreement and the reply needed now; remove the conflicting no-rush message.
**Boundary to preserve**
17:00 today is the reply deadline and Friday is the delivery deadline; do not describe Chen as already late.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |