# adkid-zephyr/oral-paper-skill architecture

> Architecture diagram of the GitHub repository adkid-zephyr/oral-paper-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adkid-zephyr/oral-paper-skill
- Repository: https://github.com/adkid-zephyr/oral-paper-skill

## Overview

Oral Paper Skill is a research-writing aid: users provide an idea, draft, or experiment plan, then use the skill and its distilled paper examples to get bounded, evidence-aware improvement advice or a reflection exercise. Its included research pipeline collects oral-paper records, extracts per-paper lessons, checks and corrects them, and synthesizes reusable practices. The README documents the user-facing capabilities; sampled scripts show parts of the pipeline, but not every stage’s wiring, so uncertain links are omitted or marked unverified.

Main entry points: [`research/abstract_distillation/cards`](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/cards) (Oral paper records), [`skills/oral-paper-skill/references`](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/skills/oral-paper-skill/references) (Distilled references), [`scripts/distill_abstracts.py`](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/distill_abstracts.py) (Abstract extraction), [`scripts/run_astra_analysis.py`](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/run_astra_analysis.py) (Analysis runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_skill["Oral Paper Skill"]
  node_examples["Quick prompts"]
  node_patterns["Distilled references"]
end

subgraph group_corpus["Paper corpus"]
  node_papers[("Oral paper records")]
  node_corpuscollector["Corpus collection<br/>[collect_corpus.py]"]
  node_corpusdata[("Corpus manifests")]
end

subgraph group_extraction["Extraction and review"]
  node_distiller["Abstract extraction"]
  node_sourcecheck["Source review packets"]
  node_reviewsummary["Review summary"]
  node_correctionscompile["Compile corrections"]
  node_correctionsapply["Apply corrections"]
  node_verifier["Extraction verification"]
end

subgraph group_synthesis["Synthesis and guidance"]
  node_synthpackets["Synthesis packets"]
  node_synthbatches["Batch synthesis"]
  node_analysisrunner["Analysis runner"]
  node_finalinput["Final synthesis input"]
  node_behaviorchecks["Behavior check inputs"]
  node_synthesisdata[("Synthesis results")]
end

node_researcher(("Researcher"))
node_reviewer(("Source reviewer"))
node_codex{{"Codex model service"}}

node_researcher -->|"requests guidance"| node_skill
node_researcher -->|"uses prompt"| node_examples
node_skill -->|"uses practices"| node_patterns
node_patterns -->|"cites examples"| node_papers
node_corpuscollector -.->|"collects records"| node_corpusdata
node_corpusdata -.->|"supplies abstracts"| node_distiller
node_distiller -.->|"requests extraction"| node_codex
node_distiller -.->|"writes cards"| node_papers
node_papers -->|"provides cards"| node_sourcecheck
node_reviewer -.->|"reviews packets"| node_sourcecheck
node_sourcecheck -.->|"supplies reviews"| node_correctionscompile
node_correctionscompile -->|"provides corrections"| node_correctionsapply
node_correctionsapply -->|"updates cards"| node_papers
node_papers -->|"provides cards"| node_reviewsummary
node_papers -->|"provides cards"| node_verifier
node_papers -->|"provides cards"| node_synthpackets
node_synthpackets -.->|"provides batches"| node_synthbatches
node_synthbatches -->|"invokes analysis"| node_analysisrunner
node_analysisrunner -->|"runs analysis"| node_codex
node_analysisrunner -.->|"writes results"| node_synthesisdata
node_synthesisdata -->|"supplies syntheses"| node_finalinput
node_reviewsummary -->|"gates assembly"| node_finalinput
node_finalinput -.->|"informs guidance"| node_patterns
node_patterns -->|"supplies skill text"| node_behaviorchecks

click node_skill "https://github.com/adkid-zephyr/oral-paper-skill/tree/main/skills/oral-paper-skill"
click node_examples "https://github.com/adkid-zephyr/oral-paper-skill/tree/main/prompts"
click node_patterns "https://github.com/adkid-zephyr/oral-paper-skill/tree/main/skills/oral-paper-skill/references"
click node_papers "https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/cards"
click node_corpuscollector "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/collect_corpus.py"
click node_distiller "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/distill_abstracts.py"
click node_sourcecheck "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_source_review.py"
click node_reviewsummary "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/summarize_reviews.py"
click node_correctionscompile "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/compile_review_corrections.py"
click node_correctionsapply "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/apply_source_corrections.py"
click node_verifier "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/verify_distillation.py"
click node_synthpackets "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_synthesis.py"
click node_synthbatches "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/run_synthesis_batches.py"
click node_analysisrunner "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/run_astra_analysis.py"
click node_finalinput "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_final_synthesis.py"
click node_behaviorchecks "https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_behavior_checks.py"
click node_corpusdata "https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/corpus"
click node_synthesisdata "https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/synthesis"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_examples,node_patterns,node_reviewer toneBlue
class node_papers,node_corpuscollector,node_corpusdata toneAmber
class node_distiller,node_sourcecheck,node_reviewsummary,node_correctionscompile,node_correctionsapply,node_verifier toneMint
class node_synthpackets,node_synthbatches,node_analysisrunner,node_finalinput,node_behaviorchecks,node_synthesisdata toneRose
class node_researcher,node_codex toneIndigo
```

## Components

### User experience

- [Oral Paper Skill](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/skills/oral-paper-skill): `skills/oral-paper-skill`
- [Quick prompts](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/prompts): `prompts`
- [Distilled references](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/skills/oral-paper-skill/references): `skills/oral-paper-skill/references`

### Paper corpus

- [Oral paper records](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/cards): `research/abstract_distillation/cards`
- [Corpus collection](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/collect_corpus.py): `scripts/collect_corpus.py`
- [Corpus manifests](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/corpus): `research/abstract_distillation/corpus`

### Extraction and review

- [Abstract extraction](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/distill_abstracts.py): `scripts/distill_abstracts.py`
- [Source review packets](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_source_review.py): `scripts/prepare_source_review.py`
- [Review summary](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/summarize_reviews.py): `scripts/summarize_reviews.py`
- [Compile corrections](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/compile_review_corrections.py): `scripts/compile_review_corrections.py`
- [Apply corrections](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/apply_source_corrections.py): `scripts/apply_source_corrections.py`
- [Extraction verification](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/verify_distillation.py): `scripts/verify_distillation.py`

### Synthesis and guidance

- [Synthesis packets](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_synthesis.py): `scripts/prepare_synthesis.py`
- [Batch synthesis](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/run_synthesis_batches.py): `scripts/run_synthesis_batches.py`
- [Analysis runner](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/run_astra_analysis.py): `scripts/run_astra_analysis.py`
- [Final synthesis input](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_final_synthesis.py): `scripts/prepare_final_synthesis.py`
- [Behavior check inputs](https://github.com/adkid-zephyr/oral-paper-skill/blob/main/scripts/prepare_behavior_checks.py): `scripts/prepare_behavior_checks.py`
- [Synthesis results](https://github.com/adkid-zephyr/oral-paper-skill/tree/main/research/abstract_distillation/synthesis): `research/abstract_distillation/synthesis`

### Other components

- **Researcher**
- **Source reviewer**
- **Codex model service**

## Connections

- Researcher → Oral Paper Skill: requests guidance (evidence: `README.md`)
- Researcher → Quick prompts: uses prompt (evidence: `README.md`)
- Oral Paper Skill → Distilled references: uses practices (evidence: `README.md`)
- Distilled references → Oral paper records: cites examples (evidence: `README.md`)
- Corpus collection → Corpus manifests: collects records
- Corpus manifests → Abstract extraction: supplies abstracts
- Abstract extraction → Codex model service: requests extraction
- Abstract extraction → Oral paper records: writes cards
- Oral paper records → Source review packets: provides cards (evidence: `scripts/prepare_source_review.py`)
- Source reviewer → Source review packets: reviews packets
- Source review packets → Compile corrections: supplies reviews
- Compile corrections → Apply corrections: provides corrections (evidence: `scripts/apply_source_corrections.py`)
- Apply corrections → Oral paper records: updates cards (evidence: `scripts/apply_source_corrections.py`)
- Oral paper records → Review summary: provides cards (evidence: `scripts/summarize_reviews.py`)
- Oral paper records → Extraction verification: provides cards (evidence: `scripts/verify_distillation.py`)
- Oral paper records → Synthesis packets: provides cards (evidence: `scripts/prepare_synthesis.py`)
- Synthesis packets → Batch synthesis: provides batches
- Batch synthesis → Analysis runner: invokes analysis (evidence: `scripts/run_synthesis_batches.py`)
- Analysis runner → Codex model service: runs analysis (evidence: `scripts/run_astra_analysis.py`)
- Analysis runner → Synthesis results: writes results
- Synthesis results → Final synthesis input: supplies syntheses (evidence: `scripts/prepare_final_synthesis.py`)
- Review summary → Final synthesis input: gates assembly (evidence: `scripts/prepare_final_synthesis.py`)
- Final synthesis input → Distilled references: informs guidance
- Distilled references → Behavior check inputs: supplies skill text (evidence: `scripts/prepare_behavior_checks.py`)
