research-architect

Research Architect Skill Suite

English | 简体中文

Research Architect is a research workflow skill suite for moving from a raw topic, partial materials, or scattered results to a coherent research-paper draft.

It provides an end-to-end research workflow for building a study from scratch: selecting a research question, conducting a focused literature review, identifying the research gap, designing the study, organizing evidence, controlling claims, planning evidence displays, managing citation support, and drafting an auditable manuscript. The skill turns early-stage research ideas into a structured, reproducible path from brainstorming to a credible first draft.

Mental model

Research Architect can run end-to-end or one branch at a time. The core idea is simple: preserve a transparent trail from raw idea to research spine, study design, evidence, claims, citation support, draft, and audit.

Quick start

After installation, start with:

research-architect

Example task:

I have a broad idea: genetic regulation in lung cancer.
I also have two target reference papers I want to learn from.
Use Research Architect to extract their research logic, propose feasible
research-question options, and build an adapted research spine.

Core idea

Research Architect helps you learn research design from target reference papers. It decomposes strong papers into reusable research logic: how they frame a problem, narrow scope, define the gap, choose a design family, set up comparison or warrant logic, organize evidence displays, and keep each claim within its evidence boundary.

The goal is to transfer the research logic behind good papers into your own project without copying their text, figures, data, results, citation choices, or claims.

Problems it addresses

• You have read many papers but still only have a broad topic.
• The direction sounds important, but the concrete research gap is unclear.
• The contribution can be described, but the evidence chain is weak.
• The topic keeps expanding and the experiment scope becomes hard to control.
• Results exist, but the paper story is loose.
• Figures look like result dumps instead of argument-bearing evidence.
• Claims are stronger than the design supports.
• References appear in the introduction but do not actually guide study design.

Workflow

Raw idea
  -> Terminology and object-identity ledger when needed
  -> Target-reference logic extraction
  -> Exemplar-to-project adaptation plan
  -> Research-question options and research gap
  -> Research spine
  -> Study design
  -> Study component and analysis plan
  -> Evidence bank
  -> Claim register
  -> Manuscript-wide display-system plan when multiple displays need coordination
  -> Panel-level evidence display map
  -> Citation support bank
  -> Promise-resolution map
  -> Evidence-first section blueprint and writing rationale matrix
  -> Evidence-first manuscript draft
  -> Audit and revision queue

How it learns from reference papers

Research Architect treats references as research-design examples. It analyzes:

• how a paper frames the problem;
• how it narrows the topic;
• how it controls difficulty;
• how it defines the research gap;
• how it expresses contribution;
• how contribution becomes field-appropriate study design;
• how comparison, counterfactual, negative-case, warrant, or validation logic is arranged;
• how figures, tables, quotation matrices, case maps, conceptual models, or other evidence displays are organized;
• how results become bounded claims;
• how citations and evidence support the manuscript narrative.

How it helps form research-question options

Research Architect pushes a broad topic into concrete research judgment by asking:

1. What design family does this direction belong to?
2. What has prior work already established?
3. Which gaps remain open and answerable?
4. Which gap fits the available data, methods, time, and resources?
5. Does difficulty come from data, method, validation, theory, or writing structure?
6. Does the contribution come from a new question, dataset, method, combination, validation strategy, or evidence framework?
7. What evidence, analysis, comparison, or warrant is needed for the central claim?
8. Which materials belong in core evidence displays and which belong in supplementary material?

How it helps design studies

Research Architect converts the design logic learned from references into a project-specific study design. It helps plan study components, analysis plans, comparison or warrant logic, negative cases, credibility checks, threats to validity, evidence displays, and claim-strength boundaries.

How it plans evidence displays

Research Architect plans the manuscript-wide display sequence before designing individual figures, tables, or panels. Each main display receives one reader question, one non-duplicative manuscript job, linked claims and evidence, and an explicit source-material/data, unit, comparator, uncertainty, and inference-boundary contract. Conceptual, system, technical, and evidence views are separated so the same explanation is not repeated across the graphical abstract, main figures, Methods, and supplement.

How it drafts from evidence

Research Architect locks recurring terminology and scientific-object identity, maps each material manuscript promise to evidence and a bounded closure, and orders the evidence-bearing units before prose. Empirical papers default to Results-first drafting; other design families start with their claim-bearing analysis, synthesis, case, or argument blocks. The Introduction, Discussion, title, and abstract are then framed around what the completed evidence or warrants actually support—not around claims the study was expected to prove.

How it helps define contribution

Research Architect breaks "contribution" into more concrete types, such as a clearer research question, a new data combination, a new analysis workflow, a new application context for an existing method, a stricter benchmark, more credible validation, a clearer evidence hierarchy, or a reusable framework that integrates scattered ideas.

Outputs

A complete run leaves a transparent trail under paper_output/, including project_config.json, source inventory, literature map, exemplar logic profile, exemplar adaptation plan, confirmed research spine, study design, analysis plan, evidence bank, claim register, citation support bank, panel-level evidence display map, promise-resolution map, writing rationale matrix, manuscript draft, audit report, run_manifest.json, and pipeline_state.json. When recurring terminology or scientific objects could drift, the run also includes a terminology and object-identity ledger; multi-display manuscripts include a manuscript-wide display-system plan before the panel map. Versioned artifact contracts and metadata sidecars keep required artifacts traceable through the workflow. The new artifacts augment the trail only where their triggers apply, so unrelated branch runs and simple projects do not inherit blanket requirements.

Installation

Run the installer from the repository root:

./install_skills.sh --codex
./install_skills.sh --claude

The installer skips an existing skill by default. Add --force to replace an existing installation.

For a manual Codex installation:

CODEX_SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$CODEX_SKILLS_DIR"
cp -R dist/codex/skills/. "$CODEX_SKILLS_DIR/"

For Claude Code, copy the same directory to ${CLAUDE_HOME:-$HOME/.claude}/skills. The release artifact can also be extracted into a Codex home:

mkdir -p "${CODEX_HOME:-$HOME/.codex}"
tar -xzf release/research-architect-codex-skills.tar.gz -C "${CODEX_HOME:-$HOME/.codex}"

After installation, call the main skill as:

research-architect

Branch skills can also be called directly when only one stage is needed.

Repository layout and source of truth

src/ is the single source of truth:

• src/skills/ stores skill definitions;
• src/references/ stores shared reference material;
• src/templates/ stores output templates;
• src/schemas/ stores versioned artifact contracts;
• src/scripts/ stores runtime helpers and package-building scripts.

Safety boundary

External papers are used to learn structure, problem framing, method logic, experiment sequencing, evidence standards, and writing organization. User-provided data, results, analyses, and evidence remain authoritative. Research Architect calibrates claim language to the strength of the available evidence.

License

This project is released under the MIT License. See LICENSE.

Release v0.5.0

Research Architect v0.5.0 adds evidence-first, promise-aware drafting; stable terminology and scientific-object identity tracking; and manuscript-wide display sequencing before individual figure or panel design. The new artifacts are conditional, preserving compatibility with simpler workflows.

Previous releases

Release v0.4.0 added versioned artifact contracts, workflow-state tracking, final-run validation, and the checked-in Codex package and installer.

Release v0.3.1 is now available. This update adds a deterministic reference-adaptation eval harness for scoring generated artifact bundles against the four fixture contracts, with unit coverage, documented pass thresholds, and rebuilt Codex release artifacts.

Release v0.3.0 made target reference papers first-class workflow inputs and added exemplar logic profiles, adaptation plans, design-family routing, and field-general study/evidence artifacts.