b3os-report

Files (22)

• SKILL.md
• b3-attn-cost.js · assets/components/
• b3-dow-trend.js · assets/components/
• b3-ma-cross.js · assets/components/
• b3-quant-formats.js · assets/components/
• b3-quant-scale.js · assets/components/
• b3-tf-steps.js · assets/components/
• components.css · assets/components/
• theme.css · assets/
• harness-pilot-report.html · examples/
• harness-pilot-report.md · examples/
• diagrams.md · references/
• interactive-components.md · references/
• reader-fit.md · references/
• ui-components.md · references/
• measure-diagram.js · scripts/
• measure-mobile.js · scripts/
• publish.sh · scripts/
• publish.test.py · scripts/
• render.mjs · scripts/
• render.sh · scripts/
• render.test.mjs · scripts/

SKILL.md (first lines)

# b3os-report — 팀 표준 보고서

## 언제 작동? (트리거 규율)
- **"보고해 / 현황 알려줘 / 어떻게 됐어"** = 그냥 **메신저로 답변**한다. 스킬 작동 X (단순 질의응답).
- **"보고서 작성해 / 리포트 만들어 / 문서로 정리해"** = 이 스킬 작동.

## /reports 대상 = "지식화되는 컨텐츠"만
- ✅ 대상: ①**외부지식 정리**(교육자료·해설·리서치 결과물) ②**내부 플젝하며 얻은 지식·경험**(노하우·교훈을 지식으로 정리한 것)
- ❌ 제외: 단순 논의결과·로그성·운영성(진행보고·리뷰메모·개발로그·툴평가) → **하던 대로 docs/작업카드에**. 포털엔 안 올림.

## 실행 전 확인 (confirm 게이트)
- **렌더 범위**: "①MD만? ②HTML까지? ③/reports 게시까지?" 물어보고 그 범위만.
- **/reports 게시는 컨펌 없이 진행한다**. `/reports` 는 팀 내부 포털이라 approval gate 대상이 아니다. **팀 밖으로 나가는 것(공개 포스팅·외부 이메일/DM·서드파티 API)은 그대로 승인 대상이다.**

## 문체 원칙 — humanize-korean 최종 패스
- 보고서는 **무조건 한글화하지 않는다**. 업계 표준 용어, 제품명, 모델명, API 이름, 검색/평가 용어처럼 영어가 더 정확한 표현은 살린다.
- 대신 한국어 독자가 자연스럽게 읽을 수 있게 아래 기준으로 최종 검수한다. (`humanize-korean` 스킬이 그 팀원의 런타임에 설치돼 있으면 그걸로 돌려도 된다 — ★이 저장소에 포함되어 있지 않고 `install.sh`가 설치하지도 않는 외부 스킬★이다.)
- 첫 등장 용어는 `영어 용어(한국어 뜻)`으로 설명한다. 이후에는 문맥상 자연스러운 쪽을 쓴다.
- 장 제목·실행 계획·판단 문장은 한국어 흐름을 기본으로 한다. `Result`, `Decision`, `Step`, `Default criteria` 같은 기계적 영어 라벨은 그대로 남기지 말고 필요한 경우 한국어로 풀어쓴다.
- 영어를 억지로 한국어로 바꾸지 않는다. 목표는 "영어 제거"가 아니라 **의미 보존 + 자연스러운 한국어 리듬**이다.
- 수치·날짜·고유명사·직접 인용은 바꾸지 않는다.

## 어떤 스킬을 언제 쓰나

설명 구성은 이 저장소의 `b3os-how-to-explain`을 따른다. `gd-explain-like-5`와 `humanize-korean`은 외부 스킬이므로 설치돼 있을 때만 사용하며, 없으면 아래 해당 절차를 직접 수행한다.

| 스킬 | 언제 | 무엇을 한다 | 무엇을 안 한다 |
|---|---|---|---|
| `b3os-how-to-explain` | **쓰기 전** — 어떻게 설명할지 정할 때 | 독자의 질문·사전 지식에 맞춰 대상·동작·조건을 연결하고 원자료 대조·재작성을 한다 | 별도의 외부 사실 검증이나 실제 독자의 이해 확인을 대신하지 않는다 |
| `gd-explain-like-5` | **남이 준 원문을 해설할 때** | 구절마다 원문 인용 → 용어 설명 → 원문 해석 → 의견·검토 포인트 4단으로 편다 | 내가 쓰는 보고서 본문에는 안 쓴다. 요약 스킬도 아니다 |
| `humanize-korean` | **렌더 직전** — 마지막 패스 | 번역투·기계적 병렬·AI 티 나는 리듬만 다듬는다 | **내용을 바꾸지 않는다.** 숫자·용어·인용은 그대로 |

셋이 겹치지 않는다 — `b3os-how-to-explain` 은 **내가 쓰는 글을 어떤 순서로 말할지**, `gd-explain-like-5` 는 **남의 원문을 구절별로 해설할 때**, `humanize-korean` 은 **다 쓴 뒤 문체**다. 대상이 다르다.

**보고서 본문에는 `b3os-how-to-explain` 과 `humanize-korean` 둘이 붙는다.** `gd-explain-like-5` 는 원문 해설물(논문·계약서·사양서를 풀어 주는 보고서)일 때만 해당한다. 그런 보고서가 아니면 안 쓴다 — 문단 하나가 어려운 것은 그 문단을 다시 쓰는 문제이지 해설 포맷을 붙일 자리가 아니다.

**`humanize-korean` 을 돌릴 때 잠글 것** — 숫자, 영어 기술 용어, 백틱 안 코드, 마크다운 강조, 절·그림 번호 참조, 예문. 이것들이 바뀌면 내용이 바뀐 것이다. 돌린 뒤 원문과 **숫자·백틱 전수 대조**를 하고, 바뀐 게 있으면 되돌린다. 입력이 길면 나눠서 돌리되 **줄 수와 줄 순서를 유지**하게 지시해야 나중에 합칠 수 있다.

**`b3os-how-to-explain` 을 쓰는 자리** — 보고서 본문 전체가 아니라 **독자가 되물을 만한 곳**이다. 새 용어를 처음 꺼내는 문단, 원인을 설명하는 문단, "왜 이렇게 했나" 를 적는 문단. 단순 현황·수치 나열에는 안 쓴다.

## 독자 수준과 설명 순서

지식 해설 보고서는 별도 독자 지정이 없으면 **중학생도 해당 분야의 배경지식 없이 이해할 수준**을 기본으로 한다. 유치한 말투나 부정확한 비유로 바꾸지 않는다. 사용자가 전문 독자·원문 순서·구현 중심을 지정했다면 그 범위를 우선한다.

작성 전·내용 리뷰 때 [독자 중심 보고서 점검](references/reader-fit.md)을 읽는다. 핵심은 단어를 풀어 쓰는 데 그치지 않고, **하나의 구체적인 예가 입력에서 결과까지 먼저 끝나도록** 구성하는 것이다. 근거에 붙은 중요한 조건은 본문에 남기고, 이해에 필요하지 않은 수식·코드·내부 구조는 선택해서 읽을 심화 부분으로 분리한다.

## 추론 레벨 — 보고서 작성만 높인다
보고서는 오래 남고 학습용으로 읽히므로 속도보다 정확도가 중요하다. 그래서 **보고서를 쓰는 작업만** 추론 레벨을 높인다(high).
- 대상: 본문 MD 초안 작성 · 숫자와 계산 검증(본문 값·표·재현 코드 대조) · 인터랙티브 컴포넌트 제작.
- 대상 아님: 팀원의 기본 추론 레벨, 메시지 답·운영 작업, 렌더·게시 같은 기계적 단계. 기본값은 바꾸지 않는다.
- 방법: 런타임이 작업 단위로 추론 레벨을 정할 수 있으면 그 작업만 high 로 돌린다(예: 서브에이전트 하나를 high 로 띄워 초안과 숫자 검증을 맡긴다). 작업 단위로 정할 수 없는 런타임이면 기본 레벨로 쓰고, 아래 3단계 리뷰에서 숫자 대조를 빠뜨리지 않는다.
- ★high 는 리뷰를 대신하지 않는다★ — 아래 3단계 팀원 리뷰는 그대로 한다.

## 단계
1. **MD 소스 먼저** — Markdown 작성(`reports/<주제>-<YYYYMMDD>/<name>.md`). 재편집·버전관리·재렌더 원본.
2. **최종 윤문** — 렌더 전에 위 “문체 원칙”과 “어떤 스킬을 언제 쓰나” 기준으로 번역투·기계적 병렬·영어 라벨 남발을 줄인다. 내용 추가/삭제가 아니라 문체·리듬·표현만 다듬는다. (외부 `humanize-korean` 스킬이 설치돼 있으면 그걸로 돌려도 된다.)
3. **팀원 리뷰 — 내용과 표현 둘 다** (★건너뛰지 않는다★)
   렌더 전에 **다른 팀원 한 명**이 읽는다.
   - **내용** — 사실이 맞나, 근거가 붙어 있나, 빠진 것이 있나
   - **표현** — ★문장 하나를 앞뒤 가리고 읽었을 때 무엇에 대한 말인지 알 수 있나★
   - **이해 흐름** — `references/reader-fit.md`의 재설명 검사를 한다. 그림·용어 풀이의 개수가 아니라, 기초 본문만으로 입력→처리→결과와 중요한 한계를 설명할 수 있는지 확인한다.

   ★표현 리뷰를 글쓴이가 대신할 수 없다.★ 몇 시간 한 주제를 들여다본 뒤에는 자기가 지어낸 말이
   자기에게는 분명하게 읽힌다. 그래서 "이건 나만 아는 말인가" 를 글쓴이가 판정하면 그 시점의 글쓴이는 통과시킨다.
   읽는 팀원은 그 맥락이 없으므로 같은 문장에서 걸린다.

   **걸러야 하는 문장 다섯 갈래** — 어느 것도 특정 단어로 걸러지지 않는다. 다섯 갈래에 겹치는 단어가 없다.

   | 갈래 | 예 | 무엇이 빠졌나 |
   |---|---|---|
   | 글쓴이가 지어낸 말 | `화면이 6,180px 떨어진 곳에 선다` | 화면은 서지 않는다. 표준 용어나 화면에 보이는 이름을 쓴다 |
   | 가리키는 것을 안 밝힘 | `코드가 있으면 제자리입니다` | 어디가 제자리인지 글 어디에도 없다 |
   | 성분이 빠진 토막 | `여섯 다 잡혔습니다` | 무엇이 무엇을 잡았는지 없다 |
   | 문장이 아닌 명사 나열 | `탭 클릭 시 탭 줄이 화면 위` | 서술어가 없다 |
   | 사물을 사람처럼 | `이 검사는 그 단어가 있는지만 봅니다` | 검사는 보지 않는다. 무엇이 무엇을 하는지로 쓴다 |

   여기에 **지시관형사 반복**을 같이 센다 — `그 코드`·`그 값`·`그 장` 이 한 문단에 여러 번 나오면
   가리키는 것을 이름으로 바꾼다. 468자 보고 하나에서 8회가 나온 실측이 있다.

   걸리는 문장이 있으면 **그 문장을 그대로 인용해서 돌려준다.** 글쓴이는 왜 그렇게 썼는지 답하고 고친다.
   ★"짧게 줄여라" 를 처방으로 쓰지 않는다★ — 줄이면 주어와 목적어부터 지워져 같은 결함이 다시 난다.
   줄이는 것은 문장이 아니라 항목 수에서 한다.

   **자동 검사는 이 다섯 갈래를 못 잡는다.** `humanize-korean` 의 71개 패턴에 대응하는 것은 `E-4 단문 일변도` 하나뿐이고,
   지시관형사 축·지어낸 표현 축은 목록에 없다. 정량 점수에 위 예문들을 넣으면 **위험도 낮음(2점)** 이 나온다(실측).
   자동 검사는 번역투·쉼표 비율·한자어 밀도를 재므로 **사람이 읽는 단계를 대신하지 못한다.**

4. **HTML 렌더** — `scripts/render.sh <md> [out.html] [제목]` → 아이폰 반응형 HTML+SVG(자체완결, **다크/라이트 테마 토글**).
5. **포털 게시** — ★원본 md/html 은 `reports/` 밖(작업 폴더·임시 폴더)에 두고 publish.sh 가 복사하게 한다.★
   이미 `reports/<id>/` 안에 써 두면 자기 자신을 복사하다 `SameFileError` 로 죽는다(실측).
   `scripts/publish.sh --title "T" --author maintainer --summary "S" --md a.md --html a.html` → team-collab `reports/`에 복사 + 등록 → **<dashboard-url>/reports** 목록에 바로 뜬다. HTML이 있으면 포털 기본 form은 HTML이고, MD는 정본·다운로드용 보조 form으로 남는다.

두 스크립트는 **이 저장소 안에** 있다. clone 루트에서 실행한다(`install.sh`는 `~/.claude/skills/b3os`만 연결하므로 `~/.claude/skills/b3os-report/…` 경로는 없다).

```bash
skills/b3os-report/scripts/render.sh report.md report.html "제목"
skills/b3os-report/scripts/publish.sh --title "제목" --author maintainer --summary "한줄요약" --md report.md --html report.html
```
→ Telegram `.html` 첨부(아이폰 Safari) + /reports 포털 둘 다 가능.

## 왜
the team lead는 주로 아이폰에서 읽는다. 표·차트가 모바일에서 깨지지 않게 **SVG**로, 매 보고서 CSS 재발명 없이 **한 테마**로 통일. MD 소스를 남겨 추적·재렌더 가능. (메모리 규칙: 보고서=MD→HTML+SVG iPhone.)

## 기본 작동 방식 — 팀원들이 따라야 할 기준
- 사용자가 “보고서/리포트/문서로 정리”를 요청하면 기본은 **MD 원본 작성 → HTML 렌더 → /reports 등록**까지다. 단순 현황 답변은 메신저 답변으로 끝낸다.
- **보고서는 설명그림을 적극적으로 쓴다.** 글로만 된 보고서는 기본값이 아니다 — 구조·비교·상태변화가 나오면 그림을 먼저 생각한다. 다만 **장식은 넣지 않는다**: 판별은 "이 그림만 보고 개념을 남에게 설명할 수 있나" 한 줄이고, 못 하면 뺀다. 그리는 법은 `references/diagrams.md`.
- 보고서 첫 화면은 항상 `# 제목` + 메타줄 + 첫 `>` 인용의 **한 줄 결론**으로 시작한다. 독자가 iPhone에서 열었을 때 5초 안에 “무슨 문서인지/결론이 뭔지” 알아야 한다.
- 영어 약어·전문 용어가 처음 나오면 별도 풀이 섹션을 만들기보다 **원래 표현과 짧은 설명을 괄호로 바로 붙인다**. 예: `API(Application Programming Interface, 프로그램끼리 요청을 주고받는 접점)`, `ARR(Annual Recurring Revenue, 연간 반복 매출)`. 모든 용어를 다 풀지 말고 독자가 막힐 가능성이 높은 약어·전문어만 고른다.
- 수식·개발·경제·투자처럼 문장 안 괄호만으로 부족한 복잡한 개념은, 해당 문단 바로 아래에 **5줄 이내의 작은 풀이 박스**를 붙인다. 이때만 `gd-explain-like-5` 흐름을 축약 적용한다: 원래 표현 → 쉬운 해석 → 왜 중요한지.
- 팀원이 디자인 기준을 모르겠으면 먼저 `/reports/file/differential-privacy/html`을 reference로 본다. 그 보고서의 장점은 **다크 editorial 톤, 짧은 섹션, 카드형 설명, 복잡한 개념을 바로 아래에서 짧게 풀어주는 방식**이다.
- 단, `differential-privacy`의 KaTeX/수식 전용 HTML을 그대로 복사하지 않는다. 일반 보고서는 이 스킬의 renderer와 `assets/theme.css`를 source of truth로 쓴다.

## 디자인 기준
- 기본 톤은 `differential-privacy` 보고서처럼 **다크 editorial 페이지**다: 큰 종이 카드가 아니라 어두운 캔버스 위 900~960px 본문, 초록 accent, 넉넉한 섹션 여백, 카드형 표/인용/코드 블록.
- 폭 규격: 표준은 **960px 상한**이다. 표·코드가 많은 보고서는 960px이 적당하고, 더 넓히면 line length가 길어져 읽기가 흐트러진다. 차분 프라이버시 같은 순수 해설형은 820~880px이 더 좋을 수 있지만, 기본 스킬은 표준 960px을 쓴다.
- 색 규칙: **초록/세이지를 primary accent**, amber/orange를 보조 강조로 쓴다. 하늘색/파랑은 다크 그린 배경에서 튀므로 링크·코드 같은 보조 정보에만 muted sage 톤으로 제한한다.
- 배경은 아주 연한 grid texture를 기본으로 쓴다. 라이트 모드는 종이 느낌이 나도록 은은하게 보이게 하고, 다크 모드는 같은 grid를 낮은 대비로 유지하되 눈을 집중하면 인지되는 수준이어야 한다. 본문 가독성을 해치면 안 된다.
- 다크 모드 표·인용·코드·figure·요약 카드는 검정 drop shadow만 쓰지 않는다. `--surface-shadow`/`--surface-shadow-soft`로 아래 방향 그림자, 위쪽 1px inset highlight, 분명한 외곽선을 함께 써서 라이트 모드와 같은 깊이 구조를 만든다.
- 탭이 필요하면 큰 pill 버튼을 쓰지 않는다. `report-tabs/report-tab`의 **작은 segmented navigation**을 써서 탭임은 인지되지만 본문보다 튀지 않게 한다. 세부 컴포넌트 예시는 `references/ui-components.md`, 다이어그램은 `references/diagrams.md`를 따른다. 긴 보고서를 탭으로 나누는 것은 렌더러가 해 준다 — 아래 「긴 보고서는 탭으로 나눈다」.

From b3rys/b3rys-team-os, Apache-2.0.

More from b3rys/b3rys-team-os