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/subagents-and-review-loop.md

View on GitHub
# Subagents and Review

[English](subagents-and-review-loop.md) | [简体中文](subagents-and-review-loop.zh-CN.md)

This reference owns production handoff, independent content review, audit and final acceptance. Read the part needed for the current assignment. The agent tool provides subagent execution; Toolkit supplies the research inputs, methods and versioned artifacts.

<!-- method:delegate -->
## Research production and handoff

Use the agent tool's native subagents when the question has work that can be owned and advanced separately. Start those assignments as soon as their boundaries and initial inputs are clear, while the lead continues research and coordination. No separately configured API is required for native delegation.

The lead owns the original question, effective requirements, overall outline and cross-part decisions. Workers can investigate sources, calculate, compare, challenge explanations, develop local arguments and write sections. Assign whole-report assembly to a named writer, who may be the lead or a separate production agent. Only that writer edits the main report; other workers save distinct contributions. The lead remains responsible for the final research judgment even when assembly is delegated.

Assign work by the actual question and dependencies. Preserve coverage dimensions alongside analytical responsibilities: for a domestic/overseas study, name which researcher covers each geography and required company, and who compares their mechanisms. Dividing by mechanism must not silently drop geographic coverage; dividing by geography must not leave cross-company explanation unowned. Give each assignment the current question, relevant original requirements and corrections, outline context, readable sources and previous analyses, expected output, and the work that depends on it.

Progress through research units rather than waiting to produce the whole report at once. A unit can be a comparison, calculation, case, mechanism or connected argument. Its owner develops evidence and reasoning into usable analysis or prose. Before dependent units rely on a consequential result, give the relevant independent reviewer the premise, evidence and current output. Unrelated units can proceed concurrently. The lead updates the outline and dependencies when a new finding changes the research; the assembler integrates ready contributions without flattening their analysis.

### Handoff that preserves the work

Return the substantive output, its original evidence and relevant locations, conditions and assumptions, unresolved issues, and a short account of what the next owner can use or must resolve. Link full calculations and arguments rather than replacing them with status messages. Keep the previous version when revising a saved artifact.

Handoff applies from researcher to researcher, researcher to assembler, author to reviewer, reviewer to reviser, and one agent's completed phase to its next phase. Continuing in the same context can reuse the existing artifact and current notes; transferring to another context must make them accessible there. Send changed requirements and inputs explicitly. A spawn-time snapshot does not contain later corrections automatically.

When a context is compressed or replaced, preserve the effective requirements, outline, completed conclusions and their conditions, pending decisions, current artifacts and original-material locations. The short handoff is a navigation aid. The receiver reads the full relevant output and sources before relying on them; original texts and raw review replies remain accessible. Do not reconstruct missing history or overwrite originals with their summaries.

With CLI/MCP, use existing `status.work` to select requirements, claims, sources and files and retrieve `work_context`; use `methods` for the relevant guidance. `save` with `draft.kind="analysis"` registers a contribution and automatically retains that unit's prepared inputs; explicit `based_on` remains available and `host_task` records its real executor. Unit/dependency and handoff information belongs with that contribution, not in a parallel task-management system. See [the request interface](../docs/usage-modes.md#research-delegation-and-handoff). Skill-only work preserves the same substance in existing agent tool conversations and files.

The agent tool manages launching, waiting, messages, cancellation and recovery. Queue independent work within its available active slots. When a task completes, free the slot for the next assignment, preserving each independent context and its response. Make already-read evidence available when continuing a task. A saved contribution marks local progress. A production context cannot independently review its own work.
<!-- /method:delegate -->

<!-- method:review -->
## Assign Work by Perspective

Every complete report covers the seven perspectives below. New reports assign three independent, non-author contexts: requirements, structure and depth, and reader usefulness in one group, evidence and adversarial reasoning in one, and process language and natural expression in one. Add separate specialist review where the report makes consequential specialized claims. Use native subagents; author self-checks do not replace these assignments. Independence concerns the context and production role, not a different vendor or outside person.

| Perspective | Method and required output |
| --- | --- |
| Intent and requirements (`requirements`) | Read the original request and effective corrections. Match important questions, required objects and constraints to actual passages or tables; identify missing answers, scope drift and instructions lost in revision. Do not invent requirements or protect the intended thesis from contrary evidence. |
| Evidence and data (`evidence`) | Check consequential claims against original sources, dates, versions, populations, units, denominators and calculations. Distinguish facts, source claims and inference. State actual reading coverage, identifying the original sections or passages checked. |
| Adversarial reasoning (`adversarial_reasoning`) | Challenge central conclusions with counterexamples, alternative explanations, selection effects and missing assumptions. Look for conditions or exceptions in the original sources. When one would change a reader's decision, apply the draft's answer to a concrete case within scope. In the review, locate the source and passage and explain whether the resulting decision holds. A supported answer counts as a completed check. |
| Structure and depth (`structure_and_depth`) | Check how questions, outline, sections, evidence and synthesis form the answer. Locate missing mechanisms, incomparable measures, compressed reasoning and source repetition. Apply the task's expected depth, not a universal structure or length. |
| Reader usefulness (`reader_usefulness`) | Read the assembled text for its intended use: title and opening, argument continuity, introduced terms, tables, timelines and useful implications. Identify concrete understanding or decision problems. |
| Process-language removal (`process_language`) | Locate production logs, internal paths/IDs, review status and assistant dialogue in reader-facing prose. Retain methods, source attribution, uncertainty and operational details that the reader's question needs. |
| Natural expression (`natural_expression`) | Locate empty abstractions, repetitive caveats, vague actors, obstructive syntax and needless repetition. Explain the reading problem and a suitable remedy. Preserve facts, qualifiers, analytical depth and the user's style preferences; do not impose phrase bans or AI-detection targets. |
| Domain specialist | Apply the actual field's criteria: technical baselines and experimental conditions, financial assumptions, policy applicability, clinical populations or other specialized reasoning. State the domain and claims examined. Use a separate non-author context for the domain assignment. |

Start each review group in a fresh independent context that reads the complete current report, original request and effective changes, and the original evidence relevant to the assignment. Do not seed it with the author's self-rating, other initial reviewers' judgments, expected scores or a preferred review result. Relevant substantive research analyses remain available. Return revisions to that group's original context, reusing completed reading and analysis and examining the changes and their effect on the current whole report. If that context cannot continue, hand its original assessment and actually reviewed input to a new independent context. A local premise review names its limited scope and cannot substitute for final whole-report review. Review the artifact in its delivery format, including portable citations and table/figure meaning.

## Shared Assignment

Provide the question, reader, effective requirements, actual artifact and input versions, original-material access, assigned perspective and required output. The reviewer reports what was examined, locatable observations and their basis. Each finding identifies its location, applicable requirement, evidence, impact and severity, separating required corrections from optional preferences. When no defect is found, explain the supporting checks instead of returning a generic PASS.

Reviewers remain read-only. Keep original replies and observable execution identities separate from any structured extraction or author response. Skill-only work can retain them in the agent tool conversation or existing files; managed work uses the [review record interface](../docs/review-completion.md). Do not fabricate a missing session identity or source access.

## Complete Every Required Review

A complete review addresses its actual scope and version with substantive observations. Empty, truncated, wrong-version or generic replies leave the assignment open. Preserve failed attempts, correct the missing input or execution problem and resume that assignment. When required material exceeds one context, retain it in accessible originals and arrange complete scoped reading and synthesis, rather than silently replacing it with a summary.

Keep the first valid result for a given input and artifact version. A negative finding is a completed review, not a reason to rerun for a better verdict. An isolated mistaken finding is adjudicated; it does not invalidate the entire review. The auditor determines consequential invalidity and contested no-change decisions from the evidence. A reviewer who never received required material has incomplete work; an examined source that leaves an answer uncertain may support a complete, qualified assessment.

Authors apply necessary fixes and can explain why they disagree with a finding. They cannot approve their own work, dismiss a necessary correction or relabel an incomplete review as complete. Preserve findings and responses for the independent audit. Revisions go back to the affected reviewer with the current complete artifact and relevant changes; unchanged evidence remains available and prior results stay bound to their actual version.
<!-- /method:review -->

<!-- method:audit -->
## Check Reviewers and Sample Passed Work

Every complete research task has an explicitly assigned audit context separate from production and content reviewers. The auditor receives the complete report, effective requirements, original sources, contributions, raw reviews and revision/disposition evidence. Review validity and report readiness are separate judgments: a valid negative review can describe a report that still needs correction.

Check each required review for its actual execution and input version, assigned coverage, locatable observations, supported claims and absence of invented requirements. Inspect all consequential findings and disagreements, including decisions to leave text unchanged. Resolve them against original evidence and actual prose, not majority votes or average scores. Preserve each original finding with one evidenced disposition: confirmed defect, no change, unresolved or resolved.

When an edit touches a consequential finding, including one fixed in an earlier draft, ask the reader's original question again. Answer it from the current manuscript alone, then check the answer against the source and the change from the earlier draft. In the existing disposition, cite the current passage that gives the answer. Equivalent wording is sufficient. If the revision drops a condition, actor or step that changes the answer, mark the finding unresolved and tell the writer what the reader can no longer determine. Keep a shared disposition only when its evidence answers each member's substantive concern.

Audit all important requirements, decisive claims, key figures and citations, consequential counterevidence, major findings and necessary fixes. Also examine material marked passed or carrying no finding, including transformations from a worker's analysis into the report. The auditor chooses these samples from the complete artifact, not from an author's selected highlights.

For this additional sampling, retain the relevant population or report scope, selected locations, selection reasons, source checks and results in the existing audit output. Choose passages across relevant sections, evidence types and transformations; do not use a fixed percentage or first/last/hash-selected paragraphs as the default. A targeted sample is described as targeted, not random. When a discrepancy appears, check the same source, measure, branch or reasoning pattern wherever it affects the result; record that expansion and its outcome.

The auditor can request missing work from the existing researcher or reviewer and continue the same audit after repair. Necessary defects and unsupported important no-change decisions remain open. Evidence that genuinely cannot settle a research question is reported at the affected conclusion; it does not erase a missing mandatory reading or review assignment. Sampling is part of this audit and final acceptance, not a separate agent, score or approval process.
Check equivalent findings against the same passage once. Preserve each original ID and link the shared evidence-based decision to every covered ID. If an unresolved question can change delivery, ask a fresh independent context to verify just that point. The auditor adjudicates it against the returned original evidence and locations.
<!-- /method:audit -->

<!-- method:acceptance -->
## Stage Scheduling and Acceptance

1. **Outline and first premises:** the lead plans questions, coverage and dependencies; the requirements and structure reviewers examine the outline before extensive dependent writing. Evidence/domain reviewers examine consequential premises and calculations as they become usable. Early local checks are retained as local checks.
2. **Developing research units:** researchers produce evidence-backed arguments progressively. Resolve a premise that could change dependent work before treating it as settled; other independent units continue. The assembler updates the whole-report argument as contributions arrive and the outline changes.
3. **Complete report:** all three content review groups and applicable domain specialists read the complete report. Findings from the independent reader-usefulness and natural-expression reviews are applied without losing facts or depth. The independent audit examines the reviews, important findings, necessary repairs and selected passed content.
4. **Independent final check and delivery.** For the first final check, a fresh independent context reads the complete current report and primary evidence before seeing earlier verdicts. It then reconciles its own recorded concerns with the audit and actual revisions in the same context. The same checker can recheck eligible later corrections under the [review contract](../docs/review-completion.md#run-the-review-and-revision-loop). Agents resolve remaining consequential defects and deliver the checked report. In managed work, `finish` records completion for the current artifact.

The final acceptance agent verifies the delivered version, source/condition preservation, complete required coverage, developed analysis and reader usability. Cross-part contradictions or lost qualifications return to the responsible production/review assignment, with the affected scope and inputs. Keep the original findings and prior artifacts. Do not let a coordinator's summary stand in for this reading.

For a finding to block delivery, tie it to an effective requirement or a consequential error in a claim the report makes. Apply this test when reconciling a blind finding. Record nearby topics and additional detail as optional when the report meets the agreed scope and the reader can make the stated decision using the report and its sources.

Reader-ready delivery requires resolved necessary corrections, complete independent assignments and acceptance of the current whole report. A stage artifact may be delivered with its actual unfinished scope. Historical and evaluation artifacts retain their original defects and labels; their completion status remains tied to the criteria and work recorded at the time. Once the agreed result and required work are complete, optional preferences do not restart unchanged reviews.
<!-- /method:acceptance -->
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