# stagsz/paper-explainer architecture

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

- Interactive diagram: https://gitdiagram.com/stagsz/paper-explainer
- Repository: https://github.com/stagsz/paper-explainer

## Overview

Paper Explainer is a Claude skill for turning a research paper into decision-ready materials: an interactive page and a verdict-first brief. Its documented workflow reads the paper, evaluates evidence, translates findings into operational implications, creates the appropriate interactive explanation, then checks claims against extracted numbers. The README describes the skill process, but SKILL.md was not sampled, so detailed step-to-step implementation links are omitted. The PDF extractor’s outputs and fallback backends are supported by source.

Main entry points: [`SKILL.md`](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md) (Explainer skill), [`scripts/extract_paper.py`](https://github.com/stagsz/paper-explainer/blob/main/scripts/extract_paper.py) (PDF extractor), [`references/extraction-sheet.md`](https://github.com/stagsz/paper-explainer/blob/main/references/extraction-sheet.md) (Extraction sheet), [`references/evaluation-rubric.md`](https://github.com/stagsz/paper-explainer/blob/main/references/evaluation-rubric.md) (Evaluation rubric)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Paper analysis"]
  node_skill["Explainer skill<br/>[SKILL.md]"]
  node_paper["Full paper"]
  node_extract["Read evidence<br/>[SKILL.md]"]
  node_appraise["Appraise evidence<br/>[SKILL.md]"]
  node_translate["Translate findings<br/>[SKILL.md]"]
  node_verify["Number cross-check<br/>[SKILL.md]"]
end

subgraph group_guidance["Reference guidance"]
  node_extraction_sheet["Extraction sheet"]
  node_rubric["Evaluation rubric"]
  node_visualization["Visualization patterns"]
  node_template["Brief template<br/>[brief-template.md]"]
end

subgraph group_extraction["PDF extraction"]
  node_pdf_tool["PDF extractor<br/>[extract_paper.py]"]
  node_text["Full-text dump"]
  node_index["Page index"]
  node_numbers["Numbers table"]
end

subgraph group_deliverables["Decision materials"]
  node_simulate["Interactive page<br/>[SKILL.md]"]
  node_brief["Two-page brief<br/>[SKILL.md]"]
end

node_reader(("Paper provider"))
node_manager(("Decision-maker"))

node_reader -->|"provides paper"| node_skill
node_skill -->|"guides reading"| node_extract
node_extract -->|"reads fully"| node_paper
node_skill -->|"guides appraisal"| node_appraise
node_appraise -->|"uses criteria"| node_rubric
node_extract -->|"records evidence"| node_extraction_sheet
node_skill -->|"guides translation"| node_translate
node_translate -->|"informs page"| node_simulate
node_simulate -->|"uses patterns"| node_visualization
node_skill -->|"produces brief"| node_brief
node_brief -->|"uses structure"| node_template
node_skill -->|"guides checking"| node_verify
node_verify -->|"checks figures"| node_extraction_sheet
node_manager -->|"uses decision brief"| node_brief
node_manager -->|"operates page"| node_simulate
node_reader -.->|"supplies PDF"| node_pdf_tool
node_pdf_tool -->|"writes text"| node_text
node_pdf_tool -->|"writes index"| node_index
node_pdf_tool -->|"writes numbers"| node_numbers
node_numbers -->|"supports cross-check"| node_verify

click node_skill "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_extract "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_appraise "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_translate "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_simulate "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_brief "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_verify "https://github.com/stagsz/paper-explainer/blob/main/SKILL.md"
click node_extraction_sheet "https://github.com/stagsz/paper-explainer/blob/main/references/extraction-sheet.md"
click node_rubric "https://github.com/stagsz/paper-explainer/blob/main/references/evaluation-rubric.md"
click node_visualization "https://github.com/stagsz/paper-explainer/blob/main/references/visualization-patterns.md"
click node_template "https://github.com/stagsz/paper-explainer/blob/main/references/brief-template.md"
click node_pdf_tool "https://github.com/stagsz/paper-explainer/blob/main/scripts/extract_paper.py"

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_paper,node_extract,node_appraise,node_translate,node_verify toneBlue
class node_extraction_sheet,node_rubric,node_visualization,node_template toneAmber
class node_pdf_tool,node_text,node_index,node_numbers toneMint
class node_simulate,node_brief toneRose
class node_reader,node_manager toneIndigo
```

## Components

### Paper analysis

- [Explainer skill](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`
- **Full paper**
- [Read evidence](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`
- [Appraise evidence](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`
- [Translate findings](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`
- [Number cross-check](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`

### Reference guidance

- [Extraction sheet](https://github.com/stagsz/paper-explainer/blob/main/references/extraction-sheet.md): `references/extraction-sheet.md`
- [Evaluation rubric](https://github.com/stagsz/paper-explainer/blob/main/references/evaluation-rubric.md): `references/evaluation-rubric.md`
- [Visualization patterns](https://github.com/stagsz/paper-explainer/blob/main/references/visualization-patterns.md): `references/visualization-patterns.md`
- [Brief template](https://github.com/stagsz/paper-explainer/blob/main/references/brief-template.md): `references/brief-template.md`

### PDF extraction

- [PDF extractor](https://github.com/stagsz/paper-explainer/blob/main/scripts/extract_paper.py): `scripts/extract_paper.py`
- **Full-text dump**
- **Page index**
- **Numbers table**

### Decision materials

- [Interactive page](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`
- [Two-page brief](https://github.com/stagsz/paper-explainer/blob/main/SKILL.md): `SKILL.md`

### Other components

- **Paper provider**
- **Decision-maker**

## Connections

- Paper provider → Explainer skill: provides paper
- Explainer skill → Read evidence: guides reading
- Read evidence → Full paper: reads fully
- Explainer skill → Appraise evidence: guides appraisal
- Appraise evidence → Evaluation rubric: uses criteria
- Read evidence → Extraction sheet: records evidence
- Explainer skill → Translate findings: guides translation
- Translate findings → Interactive page: informs page
- Interactive page → Visualization patterns: uses patterns
- Explainer skill → Two-page brief: produces brief
- Two-page brief → Brief template: uses structure
- Explainer skill → Number cross-check: guides checking
- Number cross-check → Extraction sheet: checks figures
- Decision-maker → Two-page brief: uses decision brief
- Decision-maker → Interactive page: operates page
- Paper provider → PDF extractor: supplies PDF
- PDF extractor → Full-text dump: writes text
- PDF extractor → Page index: writes index
- PDF extractor → Numbers table: writes numbers
- Numbers table → Number cross-check: supports cross-check