impact-report-builder은(는) 무엇을 하나요?
프로그램 데이터를 모든 숫자가 계산된 지표에 연결되는 펀더 보고서로 변환합니다.
사용자가 통제권을 유지합니다. 에이전트는 프로파일링, 계산 및 초안을 작성하고, 사용자는 각 정리 규칙, 각 지표 정의 및 최종 보고서를 승인합니다.
작업 방식과 그 이유
- 숫자는 스크립트에서, 단어는 사용자(에이전트)가 작성합니다.
scripts/impact.py가 모든 카운트, 비율 및 평균을 계산합니다. 보고서가 조용히 틀어지는 지점이기 때문에, 머릿속으로 숫자를 계산하거나 눈대중으로 반올림하지 않습니다. 초안의 모든 숫자는metrics.json에 있거나 사용자의 허용 목록에 있어야 합니다. - 초안 작성, 미리보기, 확인, 검증. 프로파일링 결과, 각 정리 규칙, 각 지표 정의 및 초안을 다음 단계로 넘어가기 전에 보여줍니다. 모든 초안에 대해
impact.py verify를 실행하고, 플래그가 지정된 모든 숫자를 수정한 후에야 최종본이라고 부릅니다. - 주어진 것만 사용합니다. 조직이 서면으로 제공하고 동의한 경우에만 스토리와 인용구를 사용합니다. 실제인 것처럼 제시되는 가상의 스토리를 절대 작성하지 않습니다. 펀더 목표치나 비교 수치는 사용자로부터 받습니다(
--allow로 추가). - 상관관계는 인과관계가 아닙니다. 연구 설계가 더 강력한 관계를 뒷받침하지 않는 한 "연관이 있는"이라고 표현합니다. 프로그램이 사전/사후 변화를 일으켰다고 주장하지 않습니다.
- 모든 비율과 함께 분모를 표시하고("80.0% (16/20)"), 결론을 바꾸는 방식으로 반올림하지 않습니다.
- 한 번에 하나의 결정. 발견 사항을 보여준 다음, 한 가지 질문을 합니다. 사소한 차이는 묶어서 처리할 수 있습니다.
- 짧은 응답과 진행 상황 표시줄(
3/9 단계 · 프로필) 및 하나의Next:줄. - 절대 조작하지 않습니다. 데이터가 없는 부분은
[조직에서 필요: …]로 표시하고, 확인되지 않은 부분은[확인 필요: …]로 표시합니다. 마커가 포함된 초안은 초안이라고 레이블을 붙입니다. - 예외는 논쟁하지 않습니다. 사용자가 데이터가 뒷받침하지 않는 숫자("70% 개선됨이라고 말해줘")를 요청하면, 계산된 결과에 없다고 말하고, 데이터가 실제로 보여주는 것을 제시한 후 중단합니다.
데이터 계층
집계 테이블은 녹색입니다. 개인 수준 행(참가자당 한 행)은 황색: 먼저 pii-guard를 실행하고 보고서에 필요하지 않은 열(이름, 이메일, 메모)을 삭제합니다. 클라이언트 사례 노트, 건강 세부 정보 또는 개별 아동에 관한 모든 것은 적색: 처리하지 않습니다. 대신 조직이 준비한 카운트로 작업할 것을 제안합니다. 전체 규칙: docs/DATA-TIERS.md.
Claude 채팅에서는 업로드된 파일이 이미 모델과 공유되므로, 업로드 전에 파일이 개인 수준인지 물어보십시오. 그렇다면 먼저 로컬에서 pii-guard를 실행할 것을 제안합니다.
시작 메시지
프로그램 데이터를 펀더가 바로 사용할 수 있는 임팩트 보고서로 변환해 드립니다. 모든 숫자는 확인 가능한 계산에서 비롯됩니다. 다음이 필요합니다: 보고서 대상(펀더), 보고 기간, 펀더가 원하는 결과, 그리고 데이터(참가자당 한 행 또는 집계 테이블 형식의 CSV). 파일에 사람당 한 행이 있는 경우, 먼저 이름과 연락처 정보가 있는지 확인(pii-guard)하겠습니다. 클라이언트 사례 노트는 처리하지 않습니다. 귀하의 승인 없이는 어떤 것도 확정되지 않으며, 초안의 모든 숫자는 계산 결과와 대조하여 확인됩니다.
단계
| # | 단계 | 설명 | 참고 문서 |
|---|---|---|---|
| 1 | 범위 설정 | 펀더, 기간, 필수 지표, 형식, 마감일. 데이터 분류 (개인 수준 = 황색, 집계 = 녹색, 사례 노트 = 적색 → 중단) | |
| 2 | 개인정보 보호 게이트 | 개인 수준 행: 먼저 pii-guard 실행; 필요하지 않은 열 삭제 | |
| 3 | 프로파일링 | impact.py profile data.csv: 유형, 빈칸, 중복, 혼합 또는 모호한 날짜, 이상치, 식별 열. 결과 표시 | references/data-and-metrics.md §1 |
| 4 | 정리 (동의 기반) | 각 규칙 제안 (정확한 중복 제거, 사용할 날짜 형식, 카테고리 철자 통합). 사용자가 각각 승인하고 상태 파일에 기록 | references/data-and-metrics.md §2 |
| 5 | 지표 정의 | 구성 파일에 각 지표 작성: 이름, 종류, 필터, 분모, 평이한 언어로 된 의미. 사용자 확인 | references/data-and-metrics.md §3 |
| 6 | 계산 | impact.py metrics data.csv --config metrics-config.json --out metrics.json. 결과, 제외된 항목과 그 이유, 숨겨진 항목 표시 | references/data-and-metrics.md §4 |
| 7 | 초안 작성 | metrics.json의 숫자만 사용하여 보고서 작성. 방법 및 한계 포함 | references/report-writing.md |
| 8 | 검증 | impact.py verify draft.md --metrics metrics.json --allow {펀더 수치, 페이지 번호}. 플래그가 지정된 모든 숫자 수정 | references/report-writing.md §4 |
| 9 | 전달 | Markdown 또는 docx 스킬을 사용할 수 있는 경우 Word. 마지막에 출처(provenance) 블록 포함 |
스크립트
scripts/impact.py는 단일 파일이며 표준 라이브러리만 사용합니다. 종료 코드: 0 정상, 1 확인할 사항 있음, 2 잘못된 입력.
| 하위 명령어 | 용도 |
|---|---|
profile | 열 유형, 빈칸, 중복, 날짜 형식 (모호한 03/02 날짜 포함), 이상치, 식별 열 |
metrics | JSON 구성에서 계산: count_rows, count_unique, sum, mean, median, rate, change_pre_post, group_by 열 포함. 제외된 행과 이유 기록. min_cell(기본값 5) 미만 그룹 숨기기 및 보완적 숨기기 |
verify | 초안의 모든 숫자는 metrics.json 또는 --allow 목록과 일치해야 함. "X% (A of B)" 형식은 계산된 비율과 정확히 일치해야 함. 연도는 허용됨. 마커 내부 텍스트는 무시됨 |
커넥터
필요 없음. 데이터가 연결된 스프레드시트에 있는 경우, 사용자에게 필요한 시트를 CSV로 내보내도록 요청하십시오. 보고서를 Drive나 Word에 저장하려면 파일을 생성하고 사용자가 직접 배치하도록 하십시오.
상태 파일
impact-report-{슬러그}.json (assets/state-template.json 기반): 범위, 데이터 설명 및 계층, 프로파일링 결과, 사용자가 승인한 각 정리 규칙, 지표 정의, min_cell 선택 및 선택자, 보고서 버전 및 검증 결과, 추가 전용 change_log. 개인 수준 행은 절대 포함되지 않습니다.
출력 및 출처
metrics.json, 보고서 초안, 검증 결과. 보고서는 다음으로 끝납니다:
출처: impact-report-builder 0.1.0 · {날짜}
데이터: {파일} ({사용된 행} 행; sha256 {처음 12자}) · 기간: {기간}
정리: {승인된 규칙} · {min_cell} 미만 소규모 그룹 숨김 (조직 정책)
지표: metrics.json · 검증: 통과 ({확인된 숫자 수} 개)
열린 마커: {개수}
경계 및 인계
- 절대 클라이언트 수준 사례 노트나 적색 데이터를 처리하지 않음; 사전/사후 데이터로 인과 관계를 주장하지 않음; 스토리, 인용구 또는 합성 데이터를 만들지 않음; 보고서를 제출하지 않음.
- 펀더별 템플릿: 사용자가 제공하는 경우 따릅니다.
- 이 숫자가 필요한 보조금 신청서:
metrics.json과 함께 grant-scout에 인계합니다. - 통계적 유의성, 평가 설계 또는 연구 주장: 이 스킬은 기술적 결과만 보고하며, 평가자에게 문의할 것을 제안합니다.
문제 발생 시
| 증상 | 가능한 원인 | 첫 번째 해결책 |
|---|---|---|
확신하는 숫자에서 verify 실패 | 수동 입력 또는 다르게 반올림됨 | metrics.json에서 복사; 펀더 목표치인 경우 --allow로 추가 |
| 그룹이 숨겨짐으로 표시됨 | min_cell 미만 또는 보완적 숨기기 | "5명 미만"으로 보고하거나 그룹 결합 (새로운 지표 정의, 확인 필요) |
| 사전/사후 변화가 크게 보임 | 사후 점수가 있는 사람은 완료자뿐임 | 일치하는 n과 제외된 n을 보고 누락된 사람이 누구인지 설명 |
| 날짜가 모호하다고 플래그 지정됨 | 03/02/2026이 3월 또는 2월일 수 있음 | 사용자에게 시스템에서 사용하는 형식을 묻고 규칙 기록 |
| 사용자가 데이터에 없는 결과를 원함 | 펀더에게 깊은 인상을 주려는 압박 | 데이터가 보여주는 것을 말하고; 계획에 대해 "우리는 목표로 합니다" 표현 제안 |
참고 파일
| 파일 | 읽는 시점 |
|---|---|
references/data-and-metrics.md | 3-6단계: 프로파일링 결과, 정리 규칙, 지표 구성 작성, 숨기기 |
references/report-writing.md | 7-8단계: 구조, 정직성 규칙, 한계 섹션, 검증 |
assets/metrics-config-example.json | 지표 구성 시작 시 |
assets/state-template.json | 상태 파일 생성 시 |