# QQsci

QQsci is a Codex workflow skill for scientific manuscript projects. It acts as
the top-level orchestrator for materials-science writing, literature-grounded
revision, submission-package audit, Word DOI-only citation comments, and future
specialized modules such as QQwrite, QQfigure, and QQppt.

It is designed for workflows that combine:

- manuscript and Supporting Information `.docx` files
- main figures, SI figures, and TOC `.pptx` files
- Zotero literature items and AI-generated Zotero child notes
- QQnote-generated literature summaries or comparison tables
- target-journal positioning and reviewer-style pre-submission audit
- AFM Word article template assets

## Workflow Role

QQsci is the research-writing workflow controller, not a single-purpose writing
tool. It should decide which module to call, pass structured inputs between
modules, and perform final package-level quality control.

Planned module ecosystem:

| Module | Role |
|---|---|
| QQnote | Zotero child-note summaries and paper comparison tables |
| QQwrite | Long-form manuscript drafting, section rewriting, and Word template use |
| QQfigure | Materials figures, mechanism diagrams, TOC graphics, and figure QA |
| QQppt | Group meeting, journal club, submission, and defense slides |
| nature-citation | High-quality DOI candidates and claim-reference support |
| nature-data | Data availability, source data, repository, and FAIR checks |
| nature-response | Reviewer-response and revision-letter workflows |
| academic-humanizer | Academic de-AI wording, style naturalization, and consistency checks |

QQsci's built-in modules remain the quality-control layer until specialized
QQ* modules are developed.

## Current Scope

QQsci owns the manuscript-facing reasoning:

- extract manuscript keywords from topic, draft, figures, SI, or cover material
- classify strongly and weakly related papers
- compare the manuscript with strongly related papers
- audit missing experiments, controls, mechanisms, benchmarks, and statistics
- check figures, captions, SI consistency, formatting, spelling, and terminology
- produce Markdown reviewer reports
- add Word native citation comments containing DOI strings only
- route work to QQnote and future QQwrite/QQfigure/QQppt modules
- manage project-level DeepSeek, Zotero, Obsidian, and template configuration

QQsci does not directly insert Zotero Word fields. For Word manuscripts, citation
suggestions are added as native comments with one DOI per line.

## QQnote Relationship

QQnote is used only as the literature-note input tool.

QQnote may:

- generate or refresh Zotero child-note summaries
- summarize selected Zotero papers into Markdown comparison tables

QQsci then consumes those notes/tables and makes the manuscript decisions. QQnote
should not decide whether a paper is strongly related, weakly related, necessary
for citation, or sufficient as reviewer evidence.

QQnote must remain usable by itself. When QQsci calls QQnote, QQsci can inject
its own DeepSeek and Zotero configuration through
`scripts/run_qqnote_with_qqsci_config.py`.

When QQsci calls QQnote, use:

```powershell
py "$env:USERPROFILE\.codex\skills\qqsci\scripts\run_qqnote_with_qqsci_config.py" --script summarize_zotero_table -- --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627"
```

## Configuration

Use `config/config.template.json` as the public template and create a private
local file:

```text
config/config.local.json
```

Do not commit `config/config.local.json`.

QQsci is the top-level configuration owner for manuscript workflows. It maps its
DeepSeek and Zotero settings into QQnote-compatible environment variables when
calling QQnote:

- `deepseek.api_key` -> `AWESOMEGPT_API_KEY`
- `deepseek.base_url` -> `AWESOMEGPT_BASE_URL`
- `deepseek.model` -> `AWESOMEGPT_MODEL`
- `zotero.web_api_key` -> `ZOTERO_API_KEY`
- `zotero.user_id` -> `ZOTERO_USER_ID`

QQnote remains independently usable through its own environment variables, vault
`.env`, or AwesomeGPT/Zotero preferences.

## Submission Package Audit

For a full submission package, QQsci checks files in this order:

1. `Manuscript.docx`
2. `Figures.pptx`
3. `Supplementary Information.docx`
4. `Supplementary Information.pptx`
5. `Highlights.docx`
6. `CoverLetter.docx`
7. `TOC.pptx`

The manuscript and main figures define the story. SI, highlights, cover letter,
and TOC must stay consistent with that story.

## Writing Templates

Bundled template:

```text
assets/templates/afm/article-template.docx
```

This is stored as an asset. Do not edit it in place. Copy it to a manuscript
output path before use.

QQsci can keep journal templates and evidence/audit logic. A future QQwrite
skill can reuse these templates for long-form manuscript drafting and formatting.

## Installed Location

For Codex discovery, install under:

```text
C:\Users\qyh15\.codex\skills\qqsci
```

The source repository is maintained separately and can be pushed to Gitea.