Imported from hw725/korean-humanities (plugins/korean-humanities/skills/hanmun-research-assistant/SKILL.md). Install upstream with npx skills add hw725/korean-humanities --skill hanmun-research-assistant. Copyright stays with the author.

name: hanmun-research-assistant description: 한문학·전근대 한국 문헌 연구 비서의 라우터 — source-grounded Q&A, 사료 디지털화 라우팅, 문헌 지식관리(Obsidian), 학술 AI 도구 도입 심사, 슈트 공통 CJK 텍스트 계약(UTF-8·regex·NFC·폰트). Trigger: 한문학 연구 비서, 문집·한문 원문 질의, 한글 인코딩 깨짐·CJK 정규식. 논문 집필·심사는 academic-research-workflow, 구결·옛한글 복원은 gugyeol-decode. metadata: author: custom version: 0.9.1 category: cjk-research suite: korean-humanities tier: portable share: korean-humanities

Hanmun Research Assistant

구 cjk-research-assistant — 2026-08-26 개명. 사용자 전공은 한문학(한국의 전근대 한문 기록 문학)이라 C·J 학문까지 암시하는 cjk가 과대 표기였다. 아래 «CJK Text Handling Contract» 절 이름의 CJK는 학문 범위가 아니라 문자 층위(유니코드 CJK Unified Ideographs·확장 평면)를 가리키므로 유지한다.

Overview

Use this skill as the single router for the user research assistant. It does not replace specialist skills; it selects and coordinates them around a CJK humanities contract grounded in local sources, Obsidian structure, JSONL logs, and explicit claim verification.

Operating Contract

• Treat the assistant as a research workflow, not a generic chatbot.
• Prefer local evidence first — your vault, corpus pipeline, vector index, and reference manager — then authoritative external databases. (이 문서는 네 가지를 역할 이름으로 부른다; 실제 설치물 대응은 맨 아래 «Local Instance Binding» 절이 정의한다.)
• Keep source facts, scholarly claims, user decisions, and agent events separate.
• Never convert OCR, translation, NER, or RAG output into a fact without source status and verification scope.
• Use JSONL for work logs, retrieval evaluation, screening decisions, and tool adoption decisions.
• For 100 or more records, require shard, checkpoint, and resume from the first run.

CJK Text Handling Contract (슈트 전체 필수 — 인코딩·정규식)

한문·옛한글·구결을 다루는 모든 작업의 기반 계약이다. CJK 문자 파이프라인의 만성 사고를 규율이 아니라 기계 검사로 차단한다. 슈트의 모든 스킬·스크립트에 적용된다.

1. 모든 텍스트 파일 I/O에 encoding="utf-8"을 명시한다. Windows에서 미명시 기본값은 locale(cp949)이라 한자·옛한글·구결 PUA가 예외 없이 조용히 깨진다. py -X utf8 / PYTHONUTF8=1 실행은 권장 사항일 뿐 방어선이 아니다 — 코드가 그것에 의존하면 안 되고, 명시가 정본이다. (열려는 대상이 바이너리면 "rb"/"wb"로 그 사실을 드러낸다.) 1-b. 한글·한자를 출력하는 스크립트는 stdout/stderr도 UTF-8로 고정한다. 파일 I/O만 막고 표준 출력을 두면 같은 사고가 콘솔에서 난다 — Windows에서 python foo.py --help가 UnicodeEncodeError: 'cp949' codec can't encode character로 중단된다(2026-08-26 실측: verify_manuscript_numbers.py --help가 argparse 도움말의 em dash에서 실패했다). 진입점 상단에 다음을 둔다:

   for _s in (sys.stdout, sys.stderr):
       if hasattr(_s, "reconfigure"):
           _s.reconfigure(encoding="utf-8", errors="replace")

   PYTHONUTF8=1이나 py -X utf8은 사용자 환경에 의존하므로 방어선이 아니다(§4 참조).
2. CJK 문자 클래스·프로퍼티 매칭은 stdlib re 금지, regex 모듈을 쓴다 (pip install regex 전제). re는 유니코드 프로퍼티를 지원하지 않아 [가-힣]· [一-鿿] 하드코딩으로 흐르는데, 그 범위는 옛한글 첫가끝 자모(U+1100·U+A960· U+D7B0), 한자 확장 B 이상(U+20000+), 한양 PUA 구결을 전부 놓친다. regex의 \p{Han}·\p{Hangul}을 쓴다. ASCII 구조 패턴(XML 태그·ID 형식·공백·파일명 새니타이즈)은 stdlib re로 충분하며 의존성 0을 유지한다.
3. 한글 비교·검색 전 NFC 정규화. NFD 유입원(macOS 파일명·일부 PDF 추출기)이 섞이면 눈에 같은 문자열이 매칭에 실패한다. unicodedata.normalize("NFC", s)를 입구에서 한 번.
4. 터미널·환경 기본값 고정. 코드의 encoding= 명시(§1)와 별개로, 환경 자체의 깨짐 뿌리 3곳을 사용자 수준에서 영구 차단한다 — tools/setup-terminal-utf8.ps1(idempotent, -Check 지원)이 실행체다: ① PYTHONUTF8=1 사용자 환경변수(파이썬 파일 I/O 기본값이 cp949→utf-8; §1의 대체가 아니라 이중 방어선) ② PowerShell 프로필(5.1·7)에 콘솔 입출력 UTF-8 + chcp 65001 ③ git core.quotepath=false(한글 파일명이 \354... 이스케이프로 깨지는 것 차단). 시스템 ACP(레지스트리 Beta UTF-8)는 의도적으로 건드리지 않는다 — HWP 등 구형 한국어 앱을 깨뜨릴 수 있다. 새 PC 셋업 시 이 스크립트를 돌린다.
5. 서지 제목 동일성은 scripts/cjk_title_match.py로 판정한다. 색인 DB(KCI·CrossRef· OpenAlex)의 제목과 우리 제목이 어긋나는 원인은 내용이 아니라 표기 잡음 — NFD 한글, 서명 부호 《》「」, 꼬리 。, 한자 사이 공백, 전각 구두점 — 이므로 그것만 제거하고 비교한다 (normalize_cjk_title·title_key·cjk_titles_match). §3의 NFC만 쓰고 NFKC·casefold 광역 정규화는 하지 않는다(「Ⅱ」≠「II」는 제목에서 내용 차이다). 양쪽 모두 CJK일 때만 판정하며 한쪽만 CJK면 「다르다」가 아니라 「판정 불가」(False)다 — 국문·영문 병기 제목은 DOI·연도· 저자로 따로 본다. --selftest가 회귀 케이스 11건. 개념 출처는 NOTICE §3(코드 미참조).

폰트 정책 (산출물 공통 — 사용자 편집 지점)

HTML·artifact·다이어그램·문서 산출물의 폰트는 아래 역할 표를 따른다. 이 표가 SSOT다 — 바꾸고 싶으면 이 표를 고치면 슈트 전체가 따른다. 여기 없는 폰트를 산출물에 임의로 쓰지 않는다.

• 터미널 폰트는 자동 설정하지 않는다(Windows Terminal 설정은 사용자 소유) — 고정폭 1순위를 수동 지정하라고 안내만 한다.
• HWP/HWPX 문서는 제출처 서식 요구가 이 표보다 우선한다(기관 지정 서체가 있으면 그것).
• 한계(신뢰도 보통): 위 폰트들의 옛한글 첫가끝 조합·한자 확장 B+ 커버리지는 완전하지 않을 수 있다. 옛한글 표시가 필요한 산출물은 렌더 확인 후 필요 시 옛한글 지원 폰트를 해당 산출물에만 예외 지정하고, 예외 사실을 산출물에 기록한다.

기계 검사: tools/check_cjk_text_contract.py가 E1(open 인코딩)·E2(read_text/write_text 인코딩)·R1(CJK 패턴의 stdlib re 매칭)을 AST로 검사한다. 이 배포물은 빌드 시 이 검사 게이트를 통과했다. 수동 실행:

py -3 tools/check_cjk_text_contract.py skills/<skill>/scripts

적용 경계: 슈트(suite: korean-humanities) 소속 스킬. 슈트 밖 스킬(예: humanize-korean — 현대 한국어 산문 전용이라 [가-힣]이 정당)에는 강제하지 않는다.

Evidence Access Layers (증거 접근 계층)

모든 산출물은 세 계층 중 하나에 속하고, 승격은 한 방향(게이트 통과)만 가능하다. Layer 3는 답을 생성하는 에이전트의 컨텍스트에 절대 포함시키지 않는다(epistemological firewall). 이 모델은 ARS v3.3.2의 ground-truth isolation(Imbad0202/academic-research-skills, CC BY-NC 4.0; Anthropic automated-w2s-researcher 2026에서 유래)을 CJK 인문학으로 재구성한 것이다.

• Layer 3(평가 기준): gold sample, 충실성 감사 정답셋, retrieval eval gold. repo에 임베드하지 말고 런타임에 제공한다.
• source-grounded-qa·deep search 같은 raw 소비 모드는 어떤 사실도 검증 없이 하류로 넘기지 않는다. primary_data/ 읽기 전용과 100건+ shard·checkpoint는 이 계층의 하위 규칙이다.

Mode Router

Partner skills 열은 권장 조합이다 — 설치돼 있지 않으면 해당 역할을 수동으로 수행하거나 생략하면 되고, 이 스킬의 라우팅 자체는 단독으로 동작한다.

graph 재랭킹은 사람이 만든 링크 기반 (CJK-safe). source-grounded-qa의 graph 신호(centrality/activation)는 사용자가 직접 작성한 vault 링크·MOC·태그(Shadow Graph)에서만 나온다. 한문 텍스트에 엔티티 추출(NER)을 하지 않으므로 약한 hanmun NER이 retrieval을 저하시키지 않는다. microsoft식 entity-GraphRAG(엔티티·커뮤니티 추출 인덱싱)는 도입하지 않는다 — graph는 추가 비용 없이 얻는 사용자 작성 링크만 사용한다.

Workflow

1. Classify the request into one mode from the router.
2. Identify evidence boundaries: local source, local derived artifact, external authority, or unverified.
3. Choose the narrowest existing specialist skill or local script before inventing a new tool.
4. Produce a concrete artifact: note, evidence matrix, tool comparison table, JSONL log, connector plan, or edit.
5. If a new external tool is involved, read references/tool-benchmark.md and route through /audit-config.
6. If a reusable behavior emerges, update this skill or its references instead of adding scattered prompt text.

Execution Model: Dynamic Harness

The default Claude Code harness is built for coding (Thariq, “A harness for every task: dynamic workflows in Claude Code,” 2026-06-02). Research work writes its own task-specific harness instead of forcing every task through one fixed loop.

• Simple or conversational request: answer through the mode router. Do not build a harness.
• Large, repeated, or deterministic work (100+ witness collation, corpus embedding, batch punctuation or translation, citation audit): generate a task-specific harness with the Workflow tool.
  • State lives in the filesystem: a layered directory convention plus git, the vault, and JSONL logs as the single source of truth. Do not pull raw data into context.
  • Compute runs as code: heavy steps (CollateX alignment, Scrapling intake, aggregation) run in subprocesses, not in model context. Solve non-coding tasks with code too.
  • Decompose with subagent fan-out: parallel per witness, document, or source. Before any expensive step, run one independent critique (cross-validation, design-review) to kill dead ends early (AutoScientists pattern).
  • Persist across sessions: shard, checkpoint, and resume. Within a live session, iterate to the completion goal with /goal or /loop; both stop when the session or PC closes. Work that must survive a closed session goes to cloud /schedule (or an OS scheduled task), resuming from the checkpoint. A passing happy path is not verification — see cc-workflow’s primitive selection table and deterministic gates.
• Log the harness choice as an event so the next run can reuse or improve it.

Imported Tool Patterns

Use external tools as design evidence, not automatic dependencies.

• From Open Notebook: project notebooks, source containers, multi-source ingestion, REST/API automation, provider choice.
• From PaperQA2: search, evidence gathering, answer synthesis, citation checking, local paper index, lower-token deterministic call paths before agentic paths.
• From Khoj: Obsidian-first second brain, custom agents, scheduled research, local or cloud model choice.
• From NotebookLM, Elicit, and Consensus: source-grounded chat, sentence-level citation expectations, screening and extraction tables, but closed tools stay benchmark references.
• From MARKUS, HERITAGE, Chinese Text Project, and INCEpTION: CJK annotation, entity linking, hanja NLP, TEI/export, and human-in-the-loop correction.

For the current baseline, read references/tool-benchmark.md. For the assistant behavior contract, read references/assistant-contract.md.

Output Contract

Always report (대화형 첫 응답·온보딩에서는 mode·decision·next 3필드 요약으로 충분하다 — 전체 6필드는 산출물이 있는 턴에):

• mode: selected mode.
• verified_inputs: what was read or checked.
• decision: keep, cherry-pick, install candidate, build connector, watchlist, or drop.
• artifact: file, note, table, log, or plan created.
• residual_risk: what remains unverified.
• next_audit_trigger: when to compare again.

Guardrails

• Do not install a new assistant stack merely because it is new or popular.
• Do not route CJK source criticism through STEM benchmark defaults without a local evaluation sample.
• Do not treat social-science evidence synthesis tools as adequate for premodern texts unless original text handling, annotation, and source provenance are tested.
• Do not leave a superseded, expensive model as a default; replace it with approved model choices or local endpoints.

Local Instance Binding (역할 이름 → 내 환경의 실물)

본문은 설치물 이름이 아니라 역할 이름으로 말한다. 이 스킬을 다른 환경에 이식할 때는 이 표만 바꾸면 된다.

바인딩이 비어 있으면(신규 설치): 있는 척하지 않는다. 각 모드는 축소 동작한다 — source-grounded Q&A는 「매 질문마다 원문 직접 재독」의 저효율 경로로, 지식 축적·재랭킹은 불가로 명시하고, 부트스트랩 순서를 안내한다: ① 원자료를 읽기 전용 폴더로 ② 자료 인벤토리(스캔 vs 텍스트층) ③ 바인딩 4칸 채우기 — 도구 선정은 즉석 추천하지 않고 tool-adoption-audit 모드로 거친다. 위임 대상 스킬(예: academic-research-workflow)이 미설치면 대행하지 말고 설치를 안내한다.

references/ 두 문서(assistant-contract·tool-benchmark)는 이 바인딩이 채워진 로컬 인스턴스 기준으로 서술돼 있다 — 이식자는 자기 스택으로 대응 항목을 치환해 읽는다.