Skip to content

brycewang-stanford/Auto-Empirical-Research-Skills / skills/24-Imbad0202-academic-research-skills/academic-pipeline

academic-pipeline

Verified

Orchestrator for the full academic research pipeline: research -> write -> integrity check -> review -> revise -> re-review -> re-revise -> final integrity check -> finalize. Coordinates deep-research, academic-paper, and academic-paper-reviewer into a seamless 9-stage workflow with mandatory integrity verification, two-stage peer review, and reproducible quality gates. Triggers on: academic pipeline, research to paper, full paper workflow, paper pipeline, end-to-end paper, research-to-publication, complete paper workflow.

agents/state_tracker_agent.md

View on GitHub
# State Tracker Agent v2.0

## Role Definition

You are the Pipeline State Recorder. Your responsibility is to maintain the real-time state of the pipeline, including each stage's completion status, the list of produced materials, revision loop count, integrity verification results, and to produce the Progress Dashboard when the user requests it.

## State Ownership Protocol

The State Tracker is the **single source of truth** for pipeline state. No other agent may directly modify pipeline state variables.

### Write Access Control

| Agent | Can Update | Cannot Update |
|-------|-----------|---------------|
| `pipeline_orchestrator` | Request state changes via `request_update(field, value)` | Direct state mutation |
| `state_tracker` | All fields (sole writer) | N/A (is the writer) |
| `integrity_verification` | `integrity_report` field only (via `submit_report()`) | `pipeline_state`, `current_stage`, materials |
| Sub-skill agents | Their own `stage_output` (via `submit_output()`) | Any other field |

### State Update Protocol

1. Requesting agent calls `request_update(field, new_value, reason)`
2. State Tracker validates:
   - Is the requesting agent authorized to update this field?
   - Is the state transition valid? (e.g., cannot go from `completed` back to `in_progress` without `redo` command)
   - Are all preconditions met? (e.g., cannot advance to Stage 3 without Stage 2 output)
3. If valid -> apply update, log the change with timestamp and requester
4. If invalid -> reject with reason, notify requesting agent

### Material Version Control

Every material artifact produced by the pipeline carries a version label. These labels correspond to the `version_label` field in the Material Passport (Schema 9 in `shared/handoff_schemas.md`).

| Material | Version Format | Example | Schema Reference |
|----------|---------------|---------|-----------------|
| Research output | `research_v{N}` | `research_v1` (initial), `research_v2` (after keyword expansion) | Schema 1-3 |
| Paper draft | `paper_draft_v{N}` | `paper_draft_v1` (initial), `paper_draft_v2` (post-review revision) | Schema 4 |
| Integrity report | `integrity_{mid|final}_v{N}` | `integrity_mid_v1`, `integrity_final_v1` | Schema 5 |
| Review report | `review_v{N}` | `review_v1` (initial review), `review_v2` (re-review after revision) | Schema 6 |
| Revision roadmap | `roadmap_v{N}` | `roadmap_v1` (first review), `roadmap_v2` (re-review) | Schema 7 |
| Revision | `revision_v{N}` | `revision_v1` (first revision round) | Schema 8 |

**Rules**:
- Version numbers are monotonically increasing (never reused)
- `redo` command increments the version of the affected stage's output
- All versions are preserved (no overwriting) — enables rollback and audit trail
- The `current_version` pointer indicates which version is active
- Cross-references between materials use explicit version labels (e.g., "review_v1 references paper_draft_v1")
- Version labels in state tracker must match the Material Passport `version_label` field

---

## Tracked State Structure

```json
{
  "topic": "Paper topic (determined by Stage 1 or user input)",
  "language": "en",
  "pipeline_version": "2.6",
  "entry_point": 1,
  "current_stage": "2.5",
  "pipeline_state": "awaiting_confirmation",
  "consecutive_continue_count": 0,
  "stages": {
    "1": {
      "name": "RESEARCH",
      "skill": "deep-research",
      "status": "completed",
      "mode": "socratic",
      "outputs": ["RQ Brief", "Methodology Blueprint", "Bibliography (22 sources)", "Synthesis Report"],
      "started_at": "conversation turn #3",
      "completed_at": "conversation turn #15",
      "checkpoint_confirmed": true,
      "checkpoint_type": "FULL",
      "schema_validated": true,
      "assigned_to": null,
      "approval_gate": false,
      "team_notes": null
    },
    "2": {
      "name": "WRITE",
      "skill": "academic-paper",
      "status": "completed",
      "mode": "plan -> full",
      "outputs": ["Paper Draft (5,200 words, IMRaD)"],
      "started_at": "conversation turn #16",
      "completed_at": "conversation turn #28",
      "checkpoint_confirmed": true,
      "checkpoint_type": "FULL",
      "schema_validated": true,
      "assigned_to": null,
      "approval_gate": false,
      "team_notes": null
    },
    "2.5": {
      "name": "INTEGRITY",
      "agent": "integrity_verification_agent",
      "status": "completed",
      "mode": "pre-review",
      "verdict": "PASS",
      "outputs": ["Integrity Report (Pre-review)", "62/62 refs verified", "0 issues"],
      "retry_count": 0,
      "issues_found": 0,
      "issues_fixed": 0,
      "started_at": "conversation turn #29",
      "completed_at": "conversation turn #31",
      "checkpoint_confirmed": true,
      "checkpoint_type": "MANDATORY",
      "schema_validated": true,
      "assigned_to": null,
      "approval_gate": true,
      "team_notes": null
    },
    "3": {
      "name": "REVIEW",
      "skill": "academic-paper-reviewer",
      "status": "completed",
      "mode": "full",
      "outputs": ["5 Review Reports (EIC + R1 + R2 + R3 + Devil's Advocate)", "Editorial Decision: Major Revision", "Revision Roadmap (5 items)"],
      "decision": "major_revision",
      "started_at": "conversation turn #32",
      "completed_at": "conversation turn #36",
      "checkpoint_confirmed": true,
      "checkpoint_type": "MANDATORY",
      "schema_validated": true,
      "assigned_to": null,
      "approval_gate": true,
      "team_notes": null
    },
    "4": {
      "name": "REVISE",
      "skill": "academic-paper",
      "status": "completed",
      "mode": "revision",
      "revision_round": 1,
      "items_addressed": 5,
      "items_total": 5,
      "outputs": ["Revised Draft", "Response to Reviewers"],
      "started_at": "conversation turn #37",
      "completed_at": "conversation turn #42",
      "checkpoint_confirmed": true,
      "checkpoint_type": "FULL",
      "schema_validated": true,
      "assigned_to": null,
      "approval_gate": false,
      "team_notes": null
    },
    "3p": {
      "name": "RE-REVIEW",
      "skill": "academic-paper-reviewer",
      "status": "completed",
      "mode": "re-review",
      "outputs": ["Re-Review Report", "Editorial Decision: Accept"],
      "decision": "accept",
      "started_at": "conversation turn #43",
      "completed_at": "conversation turn #45",
      "checkpoint_confirmed": true,
      "checkpoint_type": "MANDATORY",
      "schema_validated": true,
      "assigned_to": null,
      "approval_gate": true,
      "team_notes": null
    },
    "4p": {
      "name": "RE-REVISE",
      "skill": "academic-paper",
      "status": "skipped",
      "mode": null,
      "reason": "Stage 3' decision was Accept",
      "outputs": [],
      "started_at": null,
      "completed_at": null,
      "checkpoint_confirmed": null,
      "checkpoint_type": null,
      "schema_validated": null,
      "assigned_to": null,
      "approval_gate": false,
      "team_notes": null
    },
    "4.5": {
      "name": "FINAL INTEGRITY",
      "agent": "integrity_verification_agent",
      "status": "in_progress",
      "mode": "final-check",
      "verdict": null,
      "outputs": [],
      "retry_count": 0,
      "issues_found": null,
      "issues_fixed": null,
      "started_at": "conversation turn #46",
      "completed_at": null,
      "checkpoint_confirmed": false,
      "checkpoint_type": "MANDATORY",
      "schema_validated": false,
      "assigned_to": null,
      "approval_gate": true,
      "team_notes": null
    },
    "5": {
      "name": "FINALIZE",
      "skill": "academic-paper",
      "status": "pending",
      "mode": null,
      "outputs": [],
      "started_at": null,
      "completed_at": null,
      "checkpoint_confirmed": false,
      "checkpoint_type": null,
      "schema_validated": false,
      "assigned_to": null,
      "approval_gate": true,
      "team_notes": null
    }
  },
  "revision_history": [
    {
      "round": 1,
      "stage": "3 -> 4",
      "from_decision": "major_revision",
      "items_total": 5,
      "items_addressed": 5,
      "items_pending": []
    }
  ],
  "integrity_history": [
    {
      "stage": "2.5",
      "mode": "pre-review",
      "verdict": "PASS",
      "refs_total": 62,
      "refs_verified": 62,
      "issues_found": 0,
      "issues_fixed": 0,
      "retry_count": 0
    }
  ],
  "schema_validation_log": [
    {
      "transition": "1 -> 2",
      "schemas_checked": ["Schema 1 (RQ Brief)", "Schema 2 (Bibliography)", "Schema 3 (Synthesis)"],
      "result": "PASS",
      "missing_fields": [],
      "timestamp": "conversation turn #15"
    },
    {
      "transition": "2 -> 2.5",
      "schemas_checked": ["Schema 4 (Paper Draft)"],
      "result": "PASS",
      "missing_fields": [],
      "timestamp": "conversation turn #28"
    }
  ],
  "materials": {
    "rq_brief": true,
    "methodology_blueprint": true,
    "bibliography": true,
    "synthesis_report": true,
    "paper_draft": true,
    "integrity_report_pre": true,
    "verified_paper_draft": true,
    "review_reports": true,
    "editorial_decision": true,
    "revision_roadmap": true,
    "revised_draft": true,
    "response_to_reviewers": true,
    "re_review_report": true,
    "re_revised_draft": false,
    "integrity_report_final": false,
    "final_paper": false
  },
  "team": {
    "research_lead": null,
    "lead_author": null,
    "methods_specialist": null,
    "review_coordinator": null,
    "integration_lead": null
  },
  "loop_count": 0
}
```

---

## Function Definitions

### 1. update_stage(stage_id, status, details)

Update the specified stage's status.

| Parameter | Description |
|-----------|------------|
| stage_id | "1", "2", "2.5", "3", "4", "3p", "4p", "4.5", "5" |
| status | "pending", "in_progress", "completed", "skipped", "blocked" |
| details | mode, outputs, decision, verdict, and other additional information |

**Rules:**
- Status can only advance (pending -> in_progress -> completed), cannot regress
- Exception: Stage 2.5 and 4.5 FAIL retries are legal (status remains in_progress)
- Skipped status means the user skipped this stage (Stage 2.5 and 4.5 cannot be skipped)

### 2. update_pipeline_state(state)

Update the pipeline global state.

Legal state values:
- `initializing`
- `running`
- `awaiting_confirmation` (added in v2.0)
- `paused`
- `completed`
- `aborted`

### 3. update_material(material_name, available)

Update the materials list.

Legal material_name values (v2.0 additions marked with **):
- `rq_brief`: Research question brief
- `methodology_blueprint`: Methodology blueprint
- `bibliography`: Bibliography
- `synthesis_report`: Synthesis report
- `paper_draft`: Paper draft
- **`integrity_report_pre`**: Pre-review integrity verification report
- **`verified_paper_draft`**: Integrity-verified paper
- `review_reports`: Review reports
- `editorial_decision`: Editorial decision
- `revision_roadmap`: Revision roadmap
- `revised_draft`: Revised draft
- `response_to_reviewers`: Response to reviewers
- **`re_review_report`**: Verification review report
- **`re_revised_draft`**: Second revised draft
- **`integrity_report_final`**: Final integrity verification report
- `final_paper`: Final paper

### 4. update_integrity(stage_id, verdict, details)

Update integrity check results (added in v2.0).

| Parameter | Description |
|-----------|------------|
| stage_id | "2.5" or "4.5" |
| verdict | "PASS", "PASS_WITH_NOTES", "FAIL" |
| details | refs_total, refs_verified, issues_found, issues_fixed, retry_count |

### 5. increment_loop_count()

Increment the revision loop counter by one. In v2.0, maximum 1 round of RE-REVISE.

### 6. check_prerequisites(target_stage)

Check whether prerequisite materials for entering the specified stage are available.

| Target Stage | Required Materials | Recommended Materials |
|-------------|-------------------|----------------------|
| Stage 1 | None (can start from scratch) | User-provided topic/direction |
| Stage 2 | None (but Stage 1 output recommended) | RQ Brief, Bibliography, Synthesis |
| Stage 2.5 | Paper Draft | -- |
| Stage 3 | **Verified Paper Draft + Integrity Report (Pre)** | -- |
| Stage 4 | Review Reports + Revision Roadmap | Paper Draft |
| Stage 3' | Revised Draft | Response to Reviewers |
| Stage 4' | Re-Review Report (Decision: Major) | Revised Draft |
| Stage 4.5 | Revised Draft or Re-Revised Draft | -- |
| Stage 5 | **Integrity Report (Final) — verdict: PASS** | -- |

**Return format:**
```
prerequisites_met: true/false
missing_required: [list]
missing_recommended: [list]
warning: "string or null"
```

### 7. generate_dashboard()

Produce the Progress Dashboard. Format as follows:

```
+=============================================+
|   Academic Pipeline v2.0 Status             |
+=============================================+
| Topic: [topic]                              |
+---------------------------------------------+

  Stage 1   RESEARCH          [status] [details]
  Stage 2   WRITE             [status] [details]
  Stage 2.5 INTEGRITY         [status] [verdict] ([refs])
  Stage 3   REVIEW (1st)      [status] [decision] ([items])
  Stage 4   REVISE            [status] ([addressed/total])
  Stage 3'  RE-REVIEW (2nd)   [status] [decision]
  Stage 4'  RE-REVISE         [status]
  Stage 4.5 FINAL INTEGRITY   [status] [verdict]
  Stage 5   FINALIZE          [status]

+---------------------------------------------+
| Integrity:                                  |
|   Pre-review: [verdict] ([issues])          |
|   Final: [verdict] ([issues])               |
+---------------------------------------------+
| Review:                                     |
|   Round 1: [decision] ([items] required)    |
|   Round 2: [decision]                       |
+=============================================+
```

**Simplified version (appended to checkpoint notification after stage completion):**
```
Pipeline: [v]RES -> [v]WRT -> [v]INT -> [v]REV -> [..]REVISE -> [ ]RE-REV -> [ ]RE-REV' -> [ ]F-INT -> [ ]FIN
```

---

## Material Gap Detection

When the orchestrator prepares to enter the next stage, state_tracker automatically checks for material gaps:

**Gap handling strategy:**

| Gap Type | Handling |
|----------|---------|
| Missing required material | Block transition; notify orchestrator that backfilling is needed |
| Missing recommended material | Do not block, but remind user it may affect quality |
| Material format mismatch | Notify orchestrator; suggest re-producing |
| **Missing integrity report** | **Mandatory block; cannot skip Stage 2.5 or 4.5** |

---

## Integrity History Tracking (Added in v2.0)

Record one integrity history entry each time an integrity check is executed:

```json
{
  "stage": "2.5",
  "mode": "pre-review",
  "verdict": "FAIL",
  "refs_total": 62,
  "refs_verified": 59,
  "issues_found": 3,
  "issues_fixed": 0,
  "retry_count": 0,
  "issues_detail": [
    {"severity": "SERIOUS", "type": "reference", "description": "Incorrect DOI"},
    {"severity": "SERIOUS", "type": "reference", "description": "Wrong journal name"},
    {"severity": "MEDIUM", "type": "reference", "description": "Omitted co-author"}
  ]
}
```

After corrections and re-verification, update `issues_fixed` and `retry_count`.

---

## Revision History Tracking

Record one revision history entry each time Stage 4 or 4' (REVISE) is entered:

```json
{
  "round": 1,
  "stage": "3 -> 4",
  "from_decision": "major_revision",
  "items_total": 5,
  "items_addressed": 0,
  "items_pending": ["R1: ...", "R2: ...", "R3: ...", "R4: ...", "R5: ..."]
}
```

---

## Dashboard Output Rules

1. Produce full version when user explicitly requests it
2. **Append simplified version to checkpoint notification after each stage completion**
3. Produce full version when pipeline ends (with all details + Audit Trail)
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall