references/visual-report-output-contract.md

# 본문형 판단 보고서 출력 계약

이 계약은 AI 백서가 현재 요청에 실제 적용되고, 안전 검사와 고영향 빈칸·충돌 해소가 끝난 뒤 **명시적 보고서·백서·파일 분석 산출물**을 만들 때만 사용한다. 호스트 Plan mode의 최종 Plan에는 이 계약 대신 `plan-output-contract.md`를 우선 적용한다.

## 1. 발동과 우선순위

명시적 보고서 경로는 다음 중 하나가 있을 때만 적용한다.

- `보고서`, `백서`, `분석 보고서`를 결과물로 직접 요청했다.
- 파일·표·차트·데이터를 제공하거나 가리키며 분석 산출물을 직접 요청했다.

`정리해줘`, `설명해줘`만으로는 이 경로를 발동하지 않는다. 안전·질문·충돌 해소가 항상 먼저이며, 그 단계에서는 예비 보고서·차트·권고를 만들지 않는다. 텍스트 전용 요청은 이 계약의 시각 기본값보다 우선한다.

최종 출력 우선순위는 다음과 같다.

1. 안전 검사와 질문·충돌 해소
2. 텍스트 전용
3. 호스트 Plan mode의 `plan-output-contract.md`
4. 이 본문형 보고서 계약
5. 일반 대화의 직접 답변

## 2. 본문 조립

길거나 구조적인 보고서는 [answer-clarity-output-contract.md](answer-clarity-output-contract.md)의 `## 핵심 답변`으로 시작한다. `결론`, `핵심 근거`, `다음 행동` 가운데 실제로 있는 항목만 한 문장씩 쓰며, 본문에서는 같은 뜻을 반복하지 않고 세부 근거·조건·예외만 확장한다.

`## 핵심 답변` 다음 본문의 기본 단위는 `관찰 문단 → 인라인 근거 시각물 → 해석 문단 → 다음 판단`이다. 관계 표현이 들어간 보고서는 짧아도 구조적인 답이므로 반드시 `## 핵심 답변`을 첫 비공백 내용으로 둔다.

- 관찰 문단은 자료에서 직접 확인되는 변화·비교·문제를 말한다.
- 시각물은 바로 앞 관찰을 검증하거나 비교한다. 시각물의 바로 아래에는 자료 범위·단위·출처 상태를 한 줄로 둔다.
- 해석 문단은 시각물에서 읽을 수 있는 사실과 모델의 해석을 구분한다.
- 다음 판단은 근거가 충분할 때만 권고하고, 부족한 근거는 `[확인 필요]` 또는 자료 한계로 남긴다.
- 보고서 본문의 주 표현은 하나만 둔다. 사용자가 요청한 독립 근거는 해당 출력 계약의 한도 안에서 보조 표로 유지할 수 있지만, 같은 사실을 반복하는 장식용 표현은 만들지 않는다.
- 변화 추적과 A 비교에는 새 시각물을 추가하지 않는다. 기존 결과 계약이 정한 위치와 형식을 유지한다.
- 텍스트만 읽어도 결론·근거·불확실성을 판단할 수 있어야 하며, 결정 정보를 시각물에만 남기지 않는다.

일반 대화에서는 시각화를 자동으로 넣지 않는다. 사용자가 직접 요청했거나 답변 끝에서 한 번 제안한 시각화를 사용자가 수락한 경우에만, 이미 확정된 내용을 다시 묻거나 이전 답변 전체를 반복하지 않고 관련 문단·필요한 시각물·한 문장 해석으로 짧게 정리한다. 같은 자료와 관계에서 거절한 제안은 새 판단 관계가 생기기 전까지 반복하지 않는다.

## 3. 고정폭 가로 텍스트 막대

0.5.0의 자동 차트는 외부 렌더러나 MCP를 사용하지 않는 **고정폭 가로 텍스트 막대** 한 종류다. 명시적 보고서·백서·파일·표·데이터 분석에서 다음 조건을 모두 만족하는 단순 비교에만 자동으로 사용한다.

- 검증된 항목과 값이 2개 이상이다.
- 같은 단위의 비음수 값이 2개 이상이며 모든 값이 그 단위를 공유한다.
- 전체 값이 0인 자료가 아니며 최댓값이 0보다 크다.
- 비교 대상의 정확한 값과 단위를 본문에 그대로 표시할 수 있다.

표현 규칙은 다음과 같다.

1. fenced code block 안에서 `항목명 | █ 막대 | 정확한 값과 단위` 순서로 쓴다.
2. 가장 큰 값의 막대를 최대 20칸으로 두고, 나머지는 `값 ÷ 최댓값 × 20`을 가장 가까운 정수로 반올림한다.
3. 양수 최솟값은 1칸으로 보이고, 0은 빈 막대로 보인다.
4. 항목명과 막대 영역을 맞춰 비교 가능하게 하되 입력 순서를 정렬하거나 바꾸지 않는다.
5. 막대 길이가 근사 표현이라는 사실 때문에 정확한 값과 단위를 생략하지 않는다.
6. 코드 블록 바로 다음 줄에 자료 범위·단위·출처 상태를 둔다.
7. 사용자가 제공한 값의 단순 비교만 요청한 경우에는 요청하지 않은 합계·평균·구성비·비율·백분율·배수를 계산하지 않고, 자료 범위·단위·출처 상태 줄로 답을 끝낸다.

예시:

```text
5월 | ███████████████      | 100 백만원
6월 | ████████████████     | 108 백만원
7월 | ██████████████████   | 119 백만원
8월 | ████████████████████ | 132 백만원
```
자료 범위: 2026년 5~8월 확정 매출 · 단위: 백만원 · 출처: 사용자 자료(확인됨)

다음 경우에는 텍스트 막대를 만들지 않고 정확한 Markdown 표 또는 텍스트로 폴백한다.

- 음수가 하나라도 있거나 양수·음수가 섞여 있다.
- 혼합 단위이거나 단위를 확인할 수 없다.
- 구성비·부분 대 전체처럼 단순 크기 비교가 아닌 관계다.
- 전체 값이 0이다.
- 값이 누락됐거나 검증되지 않았다.
- 질문 단계이거나 결과 방향을 바꾸는 충돌이 남아 있다.
- 사용자가 텍스트 전용 또는 표·도식 금지를 요청했다.

## 4. 관계별 선택과 최소 자료 조건

| 관계 | 우선 표현 | 최소 자료 조건 |
|---|---|---|
| 추세 | 고정폭 가로 텍스트 막대 또는 값 표 | 순서가 있는 같은 단위의 비음수 값 2개 이상 |
| 비교·순위 | 고정폭 가로 텍스트 막대 또는 값 표 | 같은 단위의 비음수 값 2개 이상 |
| 구성비 | 구성 표 | 동일 총량의 부분 |
| 분포 | 분포 요약표 | 다수의 개별 관측값 |
| 상관관계 | 관계 표 | 짝지어진 수치 데이터 |
| 선택 기준 | 비교표·판단 매트릭스 | 출처가 있는 두 기준; 없으면 비교표 |
| 원인·영향 | 원인-영향 구조 | 인과 근거; 없으면 확인할 가설·관계로 표기 |
| 일정·의존성 | 타임라인 | 날짜 또는 명시적 순서·의존성 |
| 실행·예외 | 역할 흐름·병렬 게이트·결정 분기 | 조건·분기·책임 관계 |

실제 수치·관계·출처가 없으면 해당 시각물을 만들지 않는다. 자료에 없는 사람·권한·수치·날짜·정책·사실을 차트·표·도식에 추가하지 않는다.

텍스트 막대는 Markdown의 고정폭 코드 블록만 사용한다. 호스트 렌더링 지원을 추정하거나 렌더링 성공, 첨부 생성, 뷰어·다운로드 링크, UI 전환을 주장하지 않는다. 텍스트 막대로 표현하지 못하는 관계는 Markdown 표·텍스트 흐름·들여쓰기 구조로 보존한다.

파일 분석은 호스트가 이번 요청에서 읽을 수 있게 제공한 첨부 또는 사용자가 지정한 파일을 사용한다. 읽기 실패·단위 불명·자료 부족이면 재첨부 또는 자료 한계를 안내하고, 자체 저장·변환·보관 경로를 만들지 않는다.

## 5. 매출 분석의 일반 원칙과 예제

매출 자료의 날짜·값·채널·단위를 현재 입력에서 확인한다. 특정 과거 회귀 자료와 이름이 같아도 수치를 재사용하지 않는다. 관찰과 해석을 연결하되 동반 변화를 인과로 단정하지 않는다. 투자·개선 등 다음 판단은 `성장 요인 확인 후`처럼 실제 근거에 필요한 조건을 보존한다.

구체 예시는 [output-examples.md](output-examples.md)를 참고한다. 예문의 제목·본문 순서·수치·문장을 현재 보고서의 고정 형식으로 강제하지 않는다. 다음 AI 행동이 필요한 경우 next-action-contract.md를 적용한다.