reference-analysis

Reference Analysis — Close Reading of Originals · Transform Contract

How reference-analyst produces the basis for a pack that "resembles the source text". Record only what was observed; mark inferences as inferences.

Why this skill exists

This project overhauled 10 premium Korean reference packs three times: v1→v2→v3. The reason was the same every time — it differs from the original. The procedure that actually worked in v3 (secure the original → read every page → mirror plan → rewrite → cross-check verification) was not documented in any skill, so it was reinvented from scratch each round. This skill is the SSOT for that procedure.

Reference modes (settle this first)

For each pack, choose one reference_mode. The mode determines the judgment criteria, so getting this wrong makes all downstream verification meaningless.

`reference_mode`	Target	Required level of evidence	Judgment criteria
`exact_document`	One specific public deck (e.g., a ministry work-report PPT, a corporate IR deck)	Original file must be secured	Against pages · transform contract fidelity
`official_system`	Official design system (Material, HIG, Carbon, etc.)	Official docs + component captures	Components · tokens conformance
`historical_canon`	Historical styles (Bauhaus, De Stijl, Swiss typography, etc.)	Academic · museum primary sources	Principles · motif inventory conformance
`style_synthesis`	Synthesis of multiple secondary sources (e.g., "consulting deck aesthetic")	Secondary sources permitted	`style_conformance`만. Does not claim fidelity to the source text

Strict: style_synthesis the pack cannot use source_depth: full, and neither meta nor the site may say anywhere that it "reproduced the original". If only secondary sources exist (slide sales sites, YouTube commentary, blogs), labeling it as fullis source forgery.

Original eligibility gate (for`exact_document` only)

Judge candidates mechanically before reading them closely. What is filtered out here is the cheapest.

Gate	Criterion	Judgment method
G-A Secured	The original file was actually downloaded	`curl -sL -o` Then verify file validity. Link existence alone is not enough
G-B Media form	PPT track requires aspect ratio ≥ 1.6 (16:9 = 1.778)	Measure page-1 mediabox
G-C Volume	Pages ≥ 8	Page count
G-D Design density	Render the first 5 slides and look directly to judge whether a visual language is present	Human/agent visual inspection
G-E rights	Publicly distributed material with primary source	Publisher/URL

G-B is the gate that failed most often in this project. An A4 portrait Korean document (aspect ratio ≈0.71) was mistaken for a deck, causing two packs (MOLIT and MOEL) to be discarded, and six candidates (MAFRA, MOIS, MFDS, Ministry of Climate and Energy, and Bank of Korea) were only rejected after download. Measure the ratio first.

Gate results are recorded per candidate — rejection reasons are assets for the next round.

{ "code": "mois", "gate_16x9": "fail", "aspect_ratio": 0.707,
  "drop_reason": "A4 세로 한글 문서. 디자인 덱 아님." }

Source manifest

Passing sources are pinned reproducibly. Sources are not committed to the repository, but identifiers are committed.

reference:
  mode: exact_document
  canonical_url: "https://..."        # 실제 다운로드에 성공한 URL 원문
  retrieved_at: "2026-08-15T14:20:00+09:00"
  sha256: "..."                        # 원본 파일 해시
  media_type: application/pdf
  page_count: 22
  page_box: { width: 960, height: 540, unit: pt }
  aspect_ratio: 1.778
  local_path: "_workspace/{batch}/pdf/{code}.pdf"   # 로컬 전용

sha256is the same, reuse the previous analysis — do not read the same source twice.

Full page inventory

Render every page of the source and view them all. Writing from samples alone was the direct cause of v1's failure.

pdftoppm -png -r 110 원본.pdf _workspace/{batch}/pages_src/{code}/p

Record observations for each page. As observed values, not adjectives.

{ "page": 13, "role": "policy-diagram",
  "observed": {
    "bg": "#001838→#0848A0 세로 그라데이션 풀스크린",
    "structure": "중앙 반원 호 + 3노드, 호 상단에 시안 글로우",
    "type": "캘리그래피 28pt 흰색 2행 + 노드 라벨 16pt",
    "chart": null,
    "notes": "이 덱에서 유일한 다크 배경 다이어그램 — 시그니처 후보" },
  "inferred": ["글로우는 외곽 blur 24px로 추정 (원본 벡터 확인 불가)"] }

observed와 inferredmust be separated. The fidelity verifier downstream observedaccepts only as evidence.

Signature motif extraction

Pick 3–7 things that "make this deck recognizable as itself," ranked. Each item has four fields.

signature_motifs:
  - rank: 1
    name: 캘리그래피 손글씨 슬로건 풀스크린
    evidence_pages: [1, 5, 12, 20, 21]     # 실제 관찰된 페이지. 필수
    where: 표지·섹션 인트로·종결. 본문 페이지에는 없음
    uniqueness: 다른 부처 덱은 고딕 제목만 씀 — 손글씨가 이 덱의 유일 식별자
    must_preserve: true

evidence_pagesis empty, that motif is invention, not observationand is deleted. must_preserve: trueIf even one motif marked as such is not reproduced, it is rejected at fidelity regardless of score — so attach this flag only to things that truly make that deck that deck.

Transform contract

Copying the source verbatim is not the goal. What we distribute is a specification of visual principles. Dispose of each element of the source in one of four ways, and record the decision.

action	meaning	예
`preserve`	reproduce as-is	grid ratios, color relationships, type hierarchy, diagram grammar
`adapt`	keep role, adjust values	paid font → metric-compatible open font
`substitute`	replace protected assets, keeping only the role	ministry emblem → neutral wordmark placeholder at same position and size
`drop`	do not reproduce	photos of specific people, source-specific illustrations

{ "source_page": 1, "element_id": "ministry-emblem", "class": "trademark",
  "action": "substitute",
  "preserve": ["우하단 배치", "슬라이드 폭 대비 5%", "다크 위 흰색 대비"],
  "prohibit": ["기관명 문자열", "엠블럼 기하", "전용 서체"] }

Protected asset categories (class) — trademark(logos, emblems, wordmarks) · proprietary_image(source photos, illustrations) · licensed_font(paid fonts) · slogan(official government/corporate wording). For these four, preserveis impossible. substitute or droponly is allowed.

Page mapping and honest naming

When moving N source pages into M pack pages, always note which source each came from.

page_mirror_plan:                  # ← 정본 필드명. 다른 이름을 쓰지 않는다
  original_pages: 22
  pack_pages: 10
  compression: merged              # identity | selected | merged
  map:
    - pack_page: 5
      source_pages: [9, 10, 11]
      kind: chart
      rationale: 3장이 같은 정책의 연속 화면 — 하나로 합쳐도 문법 손실 없음

Naming discipline. compression: mergedbut do not call it a "1:1 mirror." If 22 pages were merged into 10, that is transformed-principle fidelityIt is not an easy pixel mirror. Overstatement confuses the later verifier about what to expect.

identity — 1 original = 1 pack, cover for all pages
selected — select only part of the original (selection rationale + list of unselected pages required)
merged — multiple originals → 1 pack (merge rationale required)

Outputs

_workspace/{batch}/
  01_scout_candidates.json          # 게이트 판정 포함 (탈락분도 보존)
  pdf/{code}.pdf                    # 원본 (로컬 전용, 커밋 안 함)
  pages_src/{code}/p-NN.png         # 원본 전 페이지 렌더
  visual_spec/{code}.json           # 페이지 전수 인벤토리 + 시그니처 + reference manifest
  transform_contract/{code}.json    # 요소별 처분 계약

Canonical keys (required — do not rename)

Because this section was missing, the outputs of the first batch of 5 packs diverged immediately. In the inventory, inventory/page_inventory 2 kinds, in unselected pages, not_selected/unselected/unmapped_source_pages 3 kinds, and at the conversion contract root, 5 kinds appeared. Pack meta.yamlsuffered the same disease as the 28 kinds of orphaned fields incident. Use only the names below.

visual_spec/{code}.json Top-level keys:

Canonical	Required	Deprecated alias
`schema_version`	✓	—
`code`	✓	—
`reference`	✓	`manifest`
`pages_unreadable`	✓ (if absent, `[]`)	—
`page_inventory`	✓	`inventory` · `pages`
`signature_motifs`	✓	`signature_visual_motifs` · `signature_top5`
`page_mirror_plan`	✓	`mirror_plan` · `compression_plan`
`palette_measured`	Recommended	`palette`
`contrast_measured`	Recommended	`contrast`

page_mirror_plan Sub-keys: original_pages · pack_pages · compression · map · not_selected(← unselected·unmapped_source_pages·excluded deprecated).

transform_contract/{code}.json Top-level key: schema_version · code · reference_sha256 · elements(element array. Do not split by protected_assets·preserved_principles; distinguish by each element's class·action).

page_inventory Each element: page(integer) · role · observed(object) · inferred(array). Page numbers are always an integer array— "1,2,13-16 등 전 페이지" strings like this are forbidden. The later verifier cannot mechanically cross-check them.

If a new key is needed, do not create it on the fly in the output — fix this table first.

Do not

Judge the whole from a few sample pages. Look at all pages.
observedMix inference into . Put things you could not confirm in inferredor leave them empty.
Declare as exact_documentwhen the original could not be obtained. That is style_synthesis다.
Filling gaps in observation with general design common sense — if the original violates the rules, the original is right. That deviation is the identity of that deck.
Dispose of protected assets as preserve.