Document refactor

Skill Leo-Moooon/shine-docs/skills/document-refactor

Use when the user wants to restructure or refactor any document (planning doc, experiment report, meeting notes, PR writeup, pasted text, a URL, or a file path) into a logically-structured, high-readability HTML or Markdown document. Only self-evident facts from the source — never infer unknown facts.From its SKILL.md

Install

npx -y skills add Leo-Moooon/shine-docs --skill document-refactor

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

6.8 KB, as published. Nobody here has run it

Document Refactor

임의의 문서를 유형에 맞는 논리 구조로 재배치해 가독성 높은 산출물(HTML/MD)로 만든다.

절대 규율 — "자명한 사실만"

원문에서 확인 가능한 내용 + 3단논법 수준의 당연한 도출만 취급한다.
맥락상 그럴듯하다는 이유로 알려지지 않은 사실을 유추하는 것은 절대 금지.
설명을 돕는 toy data/가짜 데이터는 허용하되 반드시 "설명용 예시(원문 밖)"로 라벨링한다.

실행 역할

메인 = 사용자와 대화하며 파이프라인을 조율하는 오케스트레이터 컨텍스트.
서브에이전트 = 메인이 별도 컨텍스트로 분리 실행하는 역할(작성자·리뷰어 등). 분리 실행이 어려우면 최소한 역할별로 컨텍스트를 명확히 분리해 수행한다.
리뷰어 독립성(중요): 4단계 Review의 두 리뷰어는 3단계 Draft를 작성한 작성자와 분리된 컨텍스트여야 한다. 작성자가 자기 초안을 스스로 검토하면 사실성 하드 게이트가 자기검토로 붕괴한다.

1. Intake (메인)

입력을 원문 텍스트로 확보한다: 붙여넣기는 그대로, 파일경로는 읽고, URL은 가용한 fetch/커넥터로 가져온다(예: Notion). 커넥터가 없으면 사용자에게 원문을 붙여넣어 달라고 요청.
모드: 사용자가 HTML/MD를 지정했으면 따르고, 지정이 없으면 인터랙티브 선택지(클릭형)로 묻는다 (HTML / MD).
저장 위치: 기본은 현재 작업 디렉토리. 원하는 위치를 인터랙티브 선택지로 확인한다 (현재 디렉토리 / 다른 경로 지정). 파일명에 날짜 접두사를 붙이지 않는다.
인터랙티브 규칙: 초기 의사결정(모드·저장 위치·아래 Classify의 유형 확인)은 자유 텍스트 질문 대신 클릭형 선택지 도구(harness의 AskUserQuestion 등)로 제시한다. 도구가 없는 환경이면 텍스트로 폴백한다. 사용자가 처음부터 값을 명시했으면 그 결정은 다시 묻지 않는다.

2. Classify (서브에이전트)

공용 템플릿 풀 ../templates/(이 스킬 디렉토리 기준, 레포의 skills/templates/)의 파일 목록과 각 파일 제목 아래의 설명 줄만 훑어 유형을 추정한다.
추정한 유형을 인터랙티브 선택지(클릭형)로 확인받는다: 「이 유형으로 진행」 / 「다른 유형 선택」(다른 템플릿 목록 제시) / 「확인 없이 바로 진행(bypass)」. 사용자가 bypass를 고르거나 미리 "확인 없이 진행"을 요청했으면 이 확인을 건너뛴다.
확정된 템플릿 파일 하나만 정독한다.
어떤 템플릿에도 맞지 않으면 default.md로 폴백하거나, 원문을 보고 적절한 섹션을 즉석 구성한다.

3. Draft = 작성자 서브에이전트

작성 전에 공용 스타일 가이드 ../style/writing-style.md(레포의 skills/style/)를 정독한다 — 특히 최우선 규칙 "최종 상태만 flat하게". 원문이 과정 서술(작업 로그)로 쓰여 있어도 산출물의 논리 구조는 최종 내용 기준으로 재편한다.
원문 내용을 선택된 템플릿의 섹션에 재배치한다(=PR 초안).
분할 신호: 재배치 결과가 분할 신호(스타일 가이드 §11 — H4 이상, 독립 주제 2개 이상)에 걸리면 그대로 진행하지 말고 메인이 인터랙티브 선택지로 묻는다: 「한 파일 유지(목차로 탐색)」 / 「개요(허브) 문서 + 하위 문서로 분할」. 분할을 고르면 개요 파일이 진입점이 되고 각 하위 파일을 상대 링크로 연결한다. 사용자가 이미 단일 문서를 명시했으면 묻지 않는다.
공란 규칙: 필수 섹션인데 원문에 근거가 없으면 공란으로 남긴다(문서가 안 다루는 논점을 드러냄). 선택 섹션인데 근거가 없으면 생략한다.
toy data에는 "설명용 예시(원문 밖)" 라벨을 붙인다.
유추 금지 규율을 지킨다(절대 규율 참조).

4. Review (PR 패턴, 최대 3라운드)

리뷰 판정은 ../review-document/SKILL.md가 단일 원본이다. 이 스킬은 무엇을 넘길지와 라운드 관리만 담당한다.

넘기는 것: 초안, 근거(=1단계에서 확보한 원문), 2단계에서 확정된 템플릿. 근거는 검증 리뷰어에게만 전달되고 가독성 리뷰어는 초안 텍스트만 받는다 — review-document가 알아서 한다.
루프: 리포트를 받아 작성자 서브에이전트가 코멘트를 반영하고, 하드 게이트를 통과할 때까지 다시 호출한다. 최대 3라운드.
리뷰어 독립성: review-document의 두 리뷰어는 3단계 Draft를 쓴 작성자와 분리된 컨텍스트로 실행한다.

리뷰 기준(중요): 리팩토링의 품질 = 원문 대비 충실도를 본다. 산출물의 독립적 완성도가 아니다. 판단 근거는 항상 "원문 ↔ 산출물" 대조다. 원문에 근거가 없어 공란인 섹션은 정상 동작이며 결함이 아니다 — 절대 감점하지 않는다.

3라운드 안에 하드 게이트를 통과하지 못한 항목, 미반영 코멘트, review-document가 올린 질문은 산출물의 Appendix(Audit Trail)에 "미해결 이슈"로 기록한다.

5. Render (메인/서브)

승인된 초안을 모드에 맞춰 산출한다.

산출물 구조 (모드 공통)

본문: 템플릿 섹션 순서대로. Abstract가 맨 앞.
Quiz: 이해도 점검용. 원문 사실에 근거한 문항만. (HTML=인터랙티브 객관식, MD=접이식 Q&A)
Appendix — Audit Trail: (1) 리뷰에서 반려된 유추/걸러진 내용, (2) 3라운드 소진 시 미해결 이슈, (3) 원문 근거 부재로 공란 처리된 섹션 목록.

HTML 모드

시각 골격(디자인 토큰·컴포넌트 카탈로그·기본 CSS·퀴즈 JS)은 ../style/html-layout.md를 원본으로 복사해 시작하고, 필요한 컴포넌트만 덜어 쓴다. 문서마다 새 시각 언어를 만들지 않는다.
자기완결 HTML 한 파일(CSS·JS 인라인). 한 페이지 + 목차. 반응형.
ASCII 다이어그램 금지 — HTML 도형/표/리스트로 그린다(.flow + .node가 기본 도형 가족).
코드블록은 <pre> 또는 white-space: pre-wrap.
Quiz는 클릭 시 정답 여부·피드백을 보여주는 인터랙티브 객관식.

MD 모드

마크다운 네이티브 시각화(표, mermaid 등).
Quiz는 <details> 접이식 Q&A.