Skip to content

rrrrrredy/research-toolkit / plugins/research-toolkit

research-toolkit

Flagged

Use for source-backed long-form research and writing in English or Chinese across fields, including revisions and continuation. Understand requirements, develop analysis through substantive research collaboration, and deliver a complete report after independent review, audit and acceptance.

FileKindSize
.codex-plugin/plugin.jsonconfig1.0 KB
.generated-files.jsonconfig6.3 KB
.mcp.jsonconfig158 B
LICENSEother1.0 KB
README.mdmarkdown3.4 KB
README.zh-CN.mdmarkdown3.0 KB
SKILL.mdskill md7.8 KB
SKILL.zh-CN.mdmarkdown6.5 KB
VERSIONother6 B
docs/compatibility.mdmarkdown3.8 KB
docs/compatibility.zh-CN.mdmarkdown3.2 KB
docs/delivery-verification.mdmarkdown19.2 KB
docs/delivery-verification.zh-CN.mdmarkdown16.3 KB
docs/review-completion.mdmarkdown18.0 KB
docs/review-completion.zh-CN.mdmarkdown14.7 KB
docs/usage-data.mdmarkdown15.4 KB
docs/usage-data.zh-CN.mdmarkdown13.9 KB
docs/usage-modes.mdmarkdown55.6 KB
docs/usage-modes.zh-CN.mdmarkdown48.6 KB
hooks/hooks.jsonconfig3.2 KB
mcp.jsonconfig253 B
plugin.jsonconfig1.1 KB
references/gotchas.mdmarkdown6.2 KB
references/gotchas.zh-CN.mdmarkdown3.6 KB
references/horizontal-vertical-analysis.mdmarkdown4.3 KB
references/horizontal-vertical-analysis.zh-CN.mdmarkdown3.2 KB
references/optional-analysis-lenses.mdmarkdown8.1 KB
references/optional-analysis-lenses.zh-CN.mdmarkdown6.1 KB
references/postmortem-lessons.mdmarkdown4.3 KB
references/postmortem-lessons.zh-CN.mdmarkdown3.5 KB
references/quality-gates.mdmarkdown5.7 KB
references/quality-gates.zh-CN.mdmarkdown4.5 KB
references/research-standard.mdmarkdown18.2 KB
references/research-standard.zh-CN.mdmarkdown13.7 KB
references/research-workflow.mdmarkdown25.5 KB
references/research-workflow.zh-CN.mdmarkdown19.9 KB
references/subagents-and-review-loop.mdmarkdown17.0 KB
references/subagents-and-review-loop.zh-CN.mdmarkdown13.4 KB
references/task-continuity.mdmarkdown6.9 KB
references/task-continuity.zh-CN.mdmarkdown5.3 KB
references/writing-style.mdmarkdown18.1 KB
references/writing-style.zh-CN.mdmarkdown14.9 KB
requirements-mcp.txtmarkdown11 B
scripts/agent_session.pyscript6.2 KB
scripts/check_delivery.pyscript44.6 KB
scripts/check_review_completion.pyscript28.5 KB
scripts/cli_agent_session.pyscript9.6 KB
scripts/codex_session.pyscript7.5 KB
scripts/extract_source_text.pyscript10.7 KB
scripts/host_review.pyscript78.4 KB
scripts/install_usage.pyscript9.7 KB
scripts/record_changes.pyscript13.7 KB
scripts/release_updates.pyscript9.8 KB
scripts/research_guidance.pyscript5.8 KB
scripts/research_host.pyscript52.4 KB
scripts/research_mcp.pyscript18.9 KB
scripts/research_records.pyscript28.5 KB
scripts/research_workflow.pyscript40.9 KB
scripts/review_process.pyscript5.2 KB
scripts/review_runner.pyscript20.2 KB
scripts/run_observation.pyscript7.7 KB
scripts/task_context.pyscript21.1 KB
scripts/task_lock.pyscript1.7 KB
scripts/task_reading.pyscript4.0 KB
scripts/task_storage.pyscript3.1 KB
scripts/usage_events.pyscript38.9 KB
scripts/usage_host.pyscript7.8 KB
scripts/usage_opencode.mjsscript3.1 KB

references/writing-style.md

View on GitHub
# Writing Style

[English](writing-style.md) | [简体中文](writing-style.zh-CN.md)

Use this file before drafting, rewriting, or finalizing.

For concrete choices about developing, cutting or revising an argument, consult the [worked examples](writing-style.md#worked-choices-in-research-prose) as needed.

<!-- method:writing -->
## Voice

Write for the audience, genre and style specified in the brief. State known facts and explain judgments, mechanisms, comparisons and implications directly. Preserve source attribution and place specific conditions or unresolved evidence beside the judgment they affect, replacing repeated general cautions. If the user asks for methodology, source scope or operating instructions, those belong in the answer too. See [Process-Language Cleanup](#process-language-cleanup) for deciding whether to remove process narration.

## Structure

Organize the text around the reader's questions, retaining the required coverage and format rather than following source-collection order. For organizing a long report, connecting section arguments or reducing repeated introductions, consult [assembly and the whole-report example](research-workflow.md#9-assembly) as needed. Use the rest of this page for prose and paragraph edits.

## Length And Decision Usefulness

Allocate space to the required questions before drafting. When the task has a length constraint or delivery requires a length count, count the actual report before delivery using the requested convention (English words or Chinese characters, with headings and references handled as agreed), and state the count and convention in the delivery note or an existing record; no separate checklist is required. If a count is needed but no convention is given, state a reasonable one. Cut repeated background and generic cautions first, while keeping the developed answer within the agreed length.

For a targeted revision, keep unaffected findings, conditions, source attribution and usable links in place. Limit new claims to what the agreed scope and a verified correction require. If the revised text exceeds the length limit, cut optional detail and repeated wording. Remeasure the actual final text and check affected conclusions across sections.

When the research supports a decision, state the recommendation, rationale, next action and conditions that would change the decision. Distinguish measured results from proposed pilot criteria. Explain any proposed numerical target using the decision's risks, a baseline or an agreed service requirement; without such a basis, describe the trigger and how to calibrate it. Check that a target does not reward hiding failures or blocking necessary escalation. For example, capping human handoffs can conflict with giving customers timely access to a person.

When the brief asks for an executable plan, make its first step usable: identify an initial scope, responsible role, practical time or resource assumptions, and observations that would expand, change or stop the work. Label proposed starting values as proposals. Use the details relevant to this decision; do not turn them into a universal checklist or require new external participants.

For a summary or local argument within a long report, combine related answers in the space assigned to that section. Use tables, background and appendices where they serve the agreed report, rather than reproducing them in every unit. Check the recommendation against every current hard constraint; do not silently trade a budget limit for performance or turn a growth forecast into an existing requirement. Preserve a source's time, sample and measurement conditions through the conclusion. Treat missing measurements as unknown; base claims of differences or absence on appropriate observations. Keep production disclosures in the separate delivery note when the agreed format provides one; retain substantive evidence limits in the report.

## Cut Redundancy, Preserve Relationships

Cut repeated summaries, background and filler that do not advance the answer. Preserve the actors, actions, conditions, negations, causes and contrasts readers need to follow the argument. Reusing a term, comparing different options on the same dimension, or briefly returning to a key reason in the conclusion is not redundant merely because the wording is similar. Use concrete subjects and verbs and explain necessary terms rather than compressing reasoning into abstract noun stacks. Expand where a relationship needs explaining; a rewrite must retain facts, attribution and the corresponding citations.

Before:

> Source changes do not directly invalidate conclusions; perform impact scoping and evidence-sufficiency reassessment.

After:

> Identify which facts changed and which conclusions rely on them. Reassess those conclusions against the updated evidence; retain conclusions whose supporting facts and reasoning still hold.

The rewrite makes the order of actions and the judgment conditions explicit while preserving the original evidence boundary.

When condensing body text into a summary, table or conclusion, preserve the meaning of key facts. Keep a number connected to its population, metric definition and scope where they affect the judgment. Shortening must not turn a missing-record rate into a completeness rate, or a proportion within a sample into a proportion of all tasks. When a source's label and detailed description can be confused, paraphrase the full description rather than carrying over the label alone.

Example ([archived synthetic pilot material](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-21-external-batches/tasks/ai-agent-workforce-fte-roi-bar-en-20261018/sources/S4.md#L7), not a real-company statistic): the label says "completeness," but the description states that 62% of human edits lacked reason codes. The [original report and correction record](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/repairs/2026-10-21-source-polarity/README.md) retain both accurate paraphrases and incorrect shortened versions within the same draft.

Incorrect shortening:

> Reason-code completeness was 62%.

Meaning-preserving alternatives, depending on where the fact appears:

| Location | Example wording |
| --- | --- |
| Body text | In this pilot, 62% of human edits lacked reason codes. |
| Table | Human edits missing reason codes: 62% (this pilot). |
| Conclusion | In this pilot, 62% of human edits lacked a recorded reason. A task-level editing rate needs all tasks as its denominator; estimating workforce replacement also requires evidence about workload and staffing changes. |

<!-- /method:writing -->

## Worked Choices in Research Prose

Read the relevant example when deciding what to develop, remove or revise. These use synthetic material in public archives, not real-company investigations; original reports and historical records remain unchanged. The first two are teaching adaptations of original and separately revised reports; the third adds a constructed follow-up requirement. They are not unique answers. Different wording and structures can work if they answer the current question and explain the evidence-to-judgment connection. The author's intended conclusion remains subject to the evidence.

### Develop the Analysis: Does Less Downtime Justify Multiyear Prepayment?

**Question and material.** A manufacturer must decide whether predictive maintenance justifies multiyear prepayment. The [90-day review](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-19-external-batches/tasks/iIoT-predictive-maintenance-arr-zh-20261016/sources/S3.md) records downtime falling from 1,840 to 1,510 minutes, alongside a 6% reduction in production load and a changed spare-parts strategy. The [procurement minutes](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-19-external-batches/tasks/iIoT-predictive-maintenance-arr-zh-20261016/sources/S2.md) also record a non-bottleneck workshop accepting weaker terms.

**The original gap.** [Section 3 of the original](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-19-external-batches/tasks/iIoT-predictive-maintenance-arr-zh-20261016/final.md) already warns against attributing all improvement to the model, but quickly concludes that downtime ROI is only marketing, not a basis for contractual consideration. It does not explain how the observed improvement connects to procurement value, and risks dismissing useful observations. [Sections 4–6 of the separate revision](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/repairs/2026-10-19-reader-edit/reports/iIoT-predictive-maintenance-arr-zh-20261016.md) develop that connection.

**Rewritten passage:**

> Downtime fell by 330 minutes, about 17.9% of the comparison-period total, which warrants investigating the product's contribution. Production load fell by 6% and spare-parts policy also changed. The two percentages measure different quantities; assess the model's contribution using evidence about particular faults, workload and spare-parts changes rather than subtracting the rates or assigning the whole reduction to the model. Procurement value then depends on avoided losses per minute and human handling costs relative to the subscription. A non-bottleneck workshop's acceptance of weaker terms supports considering a limited trial there. For the bottleneck line, continue that assessment and defer multiyear prepayment until the loss estimate, missed-alert liability and prepaid-fee refund terms justify the commitment.

**Why this choice helps.** Keep the observed improvement and counterexample, then supply the missing connections among observed change, attribution, economic value and contract choice. This needs more explanation. Adding only “limited sample” or making the conclusion more cautious would still leave the procurement question unanswered.

### Remove Distractions: What Determines an RFQ Answer?

**Question and material.** A manufacturer wants to answer a customer RFQ using an emissions-factor library. The [synthetic brochure](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-19-external-batches/tasks/scope3-factor-rfq-evidence-en-20261016/sources/S1.md) advertises over 12,000 factors and use in 40 RFQs without buyer challenges. The factors are industry-average or spend-based estimates; premium ranges cover only 30% of SKUs, and the library provides no third-party assurance. The [advisor extract](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-19-external-batches/tasks/scope3-factor-rfq-evidence-en-20261016/sources/S4.md) says some buyers accept labelled screening estimates.

**The original gap.** The [original](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-19-external-batches/tasks/scope3-factor-rfq-evidence-en-20261016/final.md) has useful tiered advice, but its ending repeatedly explains what makes a qualified long-form report and restates evidence discipline. These reminders do not help determine whether the current factor is suitable. [Sections 1, 3 and 6 of the revision](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/repairs/2026-10-19-reader-edit/reports/scope3-factor-rfq-evidence-en-20261016.md) use the space to match the buyer's question to the evidence.

**Rewritten passage:**

> Match the RFQ answer to the buyer's purpose. For preliminary screening, use the library's industry-average or spend-based estimate if the buyer accepts that use, and label it accordingly. Comparing a particular supplier's product requires explaining why the selected factor fits that product. Premium ranges cover 30% of SKUs, so check whether the current product is included and retain the estimate's method and scope. The library provides no third-party assurance; an RFQ requiring an assured answer needs that assurance before submission. A buyer accepting a labelled screening estimate can use it for that narrower purpose.

**Why this choice helps.** Catalogue size and “no challenges” describe the claimed range and prior use. This decision turns on the current product, the buyer's purpose and the required assurance, so the paragraph develops those points instead of repeating product background or writing advice. The premium coverage limit and screening counterexample remain because they change the recommendation. Cutting makes space for necessary analysis; minimum length is not the goal.

### Revise Locally: Which Judgments Change with the Requirements?

**Original question and material.** The [archived Maple task](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/diagnostics/2026-10-13-targeted-recheck/judges/maple-storage-en/packet.json) concerns fictional storage procurement: first-year total cost at most 10 units, recovery within 4 hours, data on premises and current demand of 12 TB. A costs 11 units, recovers in 2 hours and holds 24 TB; B is 8/5/24 and C is 8/3/14. All are on premises. Another 4 TB next year is only a forecast; C's expansion price and recovery time are unknown.

**Original passage and change.** The [archived report](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/repairs/2026-10-13-astra/maple-storage-en.md) recommends C, correctly under those requirements. This example adds a **constructed follow-up**: an approved budget increase to 11, with 16 TB now mandatory; other conditions stay unchanged. Continuing to recommend C retains an obsolete premise. Replacing all analysis with “insufficient information; research again” discards comparisons that still hold.

**Rewritten passage:**

> Under the revised 11-unit budget and current 16 TB capacity requirement, A qualifies with 11 units in total cost, 2-hour recovery and 24 TB capacity. B still exceeds the recovery limit at 5 hours. C's 14 TB falls short; reassessing it requires an expansion to at least 16 TB with a confirmed price and recovery time. All three remain on premises. Reliability and operating labor remain unresolved in the supplied evidence. The revised budget and capacity requirements change the recommendation to A; the supplied cost, recovery and capacity figures are unchanged.

**Why this choice helps.** Change the recommendation and its budget/capacity reasoning while retaining B's recovery limit, the location finding and the unknowns. Revise a judgment when new input changes its premises, not merely because a new file or a large update exists. Follow-up requirements and evidence in an actual task must come from its actual inputs, not be invented to imitate this example.

<!-- method:language-style -->
## Chinese Longform Preferences

For Chinese final articles:

- Use clean section titles.
- Put the strongest insights near the beginning.
- Use numbered insights when the opening is dense.
- Keep English technical terms only when they are real industry terms.
- Replace translationese with natural Chinese.
- Remove production narration unrelated to the question; retain internal source IDs only when the task asks to present or explain them.
- Follow the brief's citation form. Use a reference list only when requested or useful within that brief; omit it when the task excludes one. Retain source attribution and locators needed to understand or verify the answer.

## English Longform Preferences

For English final articles:

- Prefer concrete nouns and active verbs.
- Avoid consulting-style filler.
- Explain why a fact changes the argument.
- Use caveats sparingly but clearly.
- Keep paragraphs purposeful; avoid source-by-source narration.

## Process-Language Cleanup

Decide whether to cut, revise or retain a sentence by its role in the current answer, not by a matched phrase or sentence pattern:

- Remove narration of collection, recording or review actions that does not help readers understand the answer. When the task explicitly requests this information, present it as agreed.
- If "the material shows" is vague, identify the material and the judgment it supports. Keep necessary attribution such as "reports" or "estimates" rather than turning a source's claim into an independently confirmed fact. Keep "user-provided" when it defines the scope of the material.
- Retain comparisons, parallel structures, transitions, headings and qualifications that help readers distinguish options, follow reasoning or find information. Condense passages that only repeat a conclusion without adding a reason, distinction or use. Frequent use of a language feature does not establish poor writing quality.

For example, the [archived synthetic cold-chain brief](https://github.com/rrrrrredy/research-toolkit/blob/main/evals/studies/2026-10-27-research-writing-choices/runs/cold-chain-revision/after/output.md) describes the independent tests' environment, starting temperature and applicable operating conditions: these support the comparison. Its distinction between round-the-clock customer support and immediate vehicle dispatch separates a service claim from delivery assurance. Keep both. By contrast, "meets all these requirements" also sweeps in next week's delivery date, which is not confirmed. Name the capacity, temperature-control and budget conditions that are met, and state that the delivery date still needs confirmation. The reason for the edit is an inaccurate scope of judgment, not an AI-like sentence pattern.

## References

For public writing, references should be readable:

- category
- organization or source type
- title

Retain internal source IDs, local paths, access status or audit grades only when the task asks to present or explain them.

Check citations in the destination format. In exported Markdown or documents, replace chat/tool citation tokens with the corresponding source title, URL and useful locator from the source record. A token that worked in the originating chat is not a portable reference. Verify its target rather than guessing a URL; retain literal tokens when the task is explaining the syntax itself.

Example categories:

- official websites, filings, blogs, docs, and reports
- papers, technical reports, datasets, repositories
- interviews, talks, podcasts, and public speeches
- industry reports, market data, pricing, and financial materials
- media coverage and longform commentary
- user, developer, and community discussions
- criticism, failures, disputes, and counter-evidence
<!-- /method:language-style -->
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall