paper-summary-to-notion - SKILL.md Agent Skill

name: paper-summary-to-notion description: Summarize research paper PDFs and upload to Notion with strict formatting/QA. Use when user asks to 정리/요약 논문 PDF를 Notion에 올리기. Trigger examples: "논문 요약해서 노션에", "paper summary to notion", "문제상황/제안방법/결과 정리 후 노션 업로드".

Paper Summary → Notion (API-only, No Browser)

Scope

대상은 논문 PDF만.
브라우저 자동화 금지. (Notion/API 기반으로만 처리)

Output Contract (고정)

본문 섹션 순서/제목을 아래로 고정한다:

## 논문 정보
## 초록
## 문제 상황
## 제안하는 방법
## 결과
## 논문 이미지
## 원본 PDF

절대 규칙: 제안하는 방법을 강화하더라도, 앞선 섹션(논문 정보, 초록, 문제 상황)의 필수 항목을 누락/축약하지 않는다.
모든 실행은 "메타데이터 완성 → 초록(원문 번역) 반영 → 전체 구조 충족 → 방법 섹션 심화" 순서를 지킨다.

Critical Rules

페이지 제목은 반드시 원문 논문 제목 (연도)
- 축약/의역 금지
## 논문 정보 필수 항목 누락 금지
- 연도, 저널/학회, citation 수(불명확 시 "본문 확인 필요"), DOI(있으면), APA, BibTeX
## 초록은 원문 abstract의 직역 번역으로 작성
- 의역/요약/내용 추가·삭제 금지
- 인용(quote) 블록을 사용하지 않고 일반 문단(paragraph)으로 작성
중복 검사 최우선
- 동일 논문 페이지가 이미 논문 부모 페이지 아래 있으면 스킵
- 판정 기준: (제목 + 연도) 또는 source_fingerprint(sha256) 일치
이미지는 선별이 아니라 전체 삽입
- 단, max(width, height) >= 300px만 추출/삽입
- 삽입 순서는 논문 원문 순서(페이지 오름차순 → 페이지 내 이미지 인덱스 오름차순)
표 사용은 기본 지양
- 불릿/자식 불릿 중심
Notion 문법 오염 절대 금지
- heading 본문 침범 금지
- 가짜 불릿(- 텍스트 노출) 금지

Workflow

입력 PDF canonical path 1개 확정
sha256 fingerprint 계산
동시 실행 락 확보
- lock key: paper-summary-to-notion:<sha256>
- 동일 key 실행 중이면 대기/스킵 (중복 쓰기 금지)
중복성 검사 (부모: IROL / 민동규 - (가제)Soft Robotics Sim To Real Transfer / 논문)
- 중복이면 생성/수정 없이 스킵 보고
메타데이터 수집 (scripts/paper_metadata.py)
텍스트 추출 (pdftotext 등)
기본 골격 먼저 완성
- 논문 정보(필수 항목), 문제 상황, 결과를 먼저 채운 뒤
- 마지막으로 제안하는 방법 심화 작성을 수행한다.
요약 작성 (특히 제안하는 방법 최우선 품질 영역)
- 이 섹션은 가장 많은 노력/토큰을 배분한다. (다른 섹션보다 상세하게)
- 강제 형식(열거 나열 금지):
  1. 먼저 1개 짧은 문단으로 방법의 전체 목적/핵심 원리를 설명
  2. 그 다음 단계형 흐름(예: 입력 → 처리 → 판단/전환 → 출력)을 불릿으로 정리
  3. 마지막에 왜 이 흐름이 유효한지(기존 대비 장점/의도)를 연결 문장으로 마무리
- 불릿 구조 규칙:
  - 최상위 불릿은 "큰 단계"(모듈/파이프라인)로 작성
  - 각 최상위 불릿 아래 자식 불릿으로 입력/처리/출력/조건/예외를 분해
  - 즉, 큰 내용 → 작은 내용으로 내려가는 계층형 설명을 만든다.
- 최소 가이드:
  - 최상위 불릿 4개 이상
  - 자식 불릿 총합 6개 이상
- 제안하는 방법은 "흐름이 보이는 설명"이 반드시 포함되어야 하며, 단순 요소 나열만으로 끝내지 않는다.
- 필요 시 이 섹션만 별도 재요약(2차 압축/확장)해서 디테일을 보강한다.
Notion 페이지 upsert
- 제목: 원문 논문 제목 (연도)
- source_fingerprint: <sha256>는 사용자 본문 영역에 노출하지 않는다.
- 구조상 반드시 필요하면 페이지 최하단 메타 영역에만 기록한다.
이미지 추출 (scripts/extract_pdf_images.py)
- 300px 규칙 통과 이미지 전체를 ## 논문 이미지 섹션에 인라인 삽입
- 삽입 순서: 페이지 오름차순 → 페이지 내 이미지 인덱스 오름차순
- ## 논문 이미지 섹션 하위로 넣어야 하며, 페이지 최하단 임의 추가 금지
- 이미지 caption은 사용하지 않는다. (caption 비움)
## 원본 PDF 섹션에 원본 PDF file block 첨부
- ## 원본 PDF 섹션 하위로 넣어야 하며, 별도 말미 추가 금지
요약 지시 문장(예: (아래에 ... 첨부))은 최종 페이지에 남기지 않는다.
구조 검증 (scripts/validate_notion_page.py --page-id <id>)

실패 시 성공 보고 금지 + rollback(in_trash)

임시 파일 등록

실제로 사용된 파일만 등록
TTL 1주일(168시간)
scripts/register_temp_artifacts.py <paths...> --ttl-hours 168

락 해제 (성공/실패 모두)

Formatting Guard

각 섹션(## ...) 사이에는 빈 문단 1줄을 넣어 시각적으로 구분되게 한다.
## 논문 정보, ## 초록, ## 문제 상황, ## 제안하는 방법, ## 결과 아래는 본문 시작 전 한 줄 공백 유지
heading 텍스트는 단일 라인만 허용

Cron Hardening (품질 편차 방지)

배치/크론 실행 시에도 동일 QA를 적용한다. (수동 실행과 예외 없이 동일)
다건 실행 전 canary 1건을 먼저 수행하고 통과 시에만 나머지를 진행한다.
인터벌은 처리시간보다 충분히 길게 잡고(권장 10분+), 이전 실행 미종료 시 다음 작업 시작 금지.
보고는 성공 URL만; 실패는 실패 원인 + rollback 여부를 분리 보고.

Checklist

references/checklist.md를 최종 게이트로 사용한다.
체크리스트 미완료 항목이 하나라도 있으면 완료 보고 금지.