拷打式 복습 (Kaoda-style Review)

수동적인 학습 자료를 학습자가 진정으로 이해했는지, 전이할 수 있는지, 잘못된 해석을 식별할 수 있는지, 후속 질문을 견딜 수 있는지를 드러내는 상호작용형 복습 체크리스트로 전환합니다.

핵심 원칙

요약자나 일반 퀴즈 생성기처럼 행동하지 마세요. 제품 약속은 다음과 같습니다:

다 봤다고 해서 이해한 것은 아니다. 당신은 질문을 견뎌낼 수 있어야 한다.

모든 출력은 가짜 이해를 진단하는 데 도움이 되어야 합니다:

학습자가 메커니즘을 설명할 수 있는가?
경계와 실패 사례를 말할 수 있는가?
다른 사람의 잘못된 이해를 식별할 수 있는가?
아이디어를 다른 시나리오로 전이할 수 있는가?
개념을 실행 가능한 결정이나 행동으로 전환할 수 있는가?

기본 출력은 형식적인 시험이 아니라 부담 없는 복습 체크리스트입니다. 기본 권장 사항은 정상 모드 · 10분입니다: 약 20개의 체크포인트, 대부분 객관식이며, 학습자가 더 무거운 모드를 선택하지 않는 한 단답형/구술형 프롬프트는 없습니다.

워크플로우

사용자가 구체적인 자료를 제공하면 python scripts/kaoda.py ingest <input>을 실행하여 data/runs/<run_id>/segments.jsonl을 생성합니다.
- ingest가 status: needs_text를 반환하면, 추출 문제를 명확히 설명하고, 사용자가 manual_input.txt 또는 manual_transcript.txt에 텍스트를 제공하도록 도운 후 python scripts/kaoda.py ingest-manual <run_id>를 실행합니다.
사용자가 제목이나 주제만 제공하면 python scripts/kaoda.py research-topic "<topic>"을 실행하고, 집중 연구를 수행하며, topic_research.md와 source_links.json을 작성한 후 python scripts/kaoda.py ingest-topic <run_id>를 실행합니다.
data/runs/<run_id>/material_report.json을 읽습니다.
references/intake_and_research.md를 읽습니다.
모드/스타일 질문 전에 소스 분석과 필수 핵심 연구/심화를 완료합니다. 기본값은 확장 연구입니다. 학습자가 명시적으로 "只按原文/출처만"을 요청하면 출처 내부 연구만 수행합니다. 결과를 data/runs/<run_id>/deep_research.json에 작성합니다.
연구 후, 가벼운 선택만 묻습니다: 복습 모드/시간, 질문 스타일, 그리고 학습자에게 활성 오답 이력이 있을 때 오답-지식 정책.
python scripts/kaoda.py plan-exam <run_id> ...를 실행하여 review_choices.md, research_prompt.md, exam_brief.json을 생성합니다.
🔴 체크포인트: deep_research.json이 존재하고 완료된 연구와 출처 참조를 포함하지 않으면 plan-exam은 실패해야 합니다. exam_brief.json이 review_mode, question_style, review_selection.status, 그리고 필수 연구 상태 completed를 포함하지 않으면 build-exam을 실행하지 마십시오.
복습 체크포인트 디자인 규칙은 references/question_design.md를 읽으십시오.
개방형 답변 채점은 references/rubrics.md를 읽으십시오.
python scripts/kaoda.py build-exam <run_id>를 실행하여 exam.json, exam.html, grading_prompt.md를 생성합니다.
학습자가 exam.html에서 복습을 완료하도록 합니다. 보이는 UI는 흐름을 단순하게 유지해야 합니다: 제출, 그 다음 Agent 보고서 내보내기 버튼이 있는 보고서 페이지.
내보낸 kaoda_agent_report.md를 읽습니다. 여기에는 attempt.json, exam.json, 객관식 예비 채점, 답변, 그리고 Agent 채점/기록 지침이 포함되어 있습니다. python scripts/kaoda.py grade-report <kaoda_agent_report.md> --learner-id <id>를 실행하여 attempt.json, exam.json, grading_prompt.md, grade.json을 생성합니다.
grade.json.open_review.status가 pending_agent_review이면, agent_open_review.md를 사용하여 단답형/구술형 답변을 루브릭으로 채점한 후, open_review.status를 completed로 설정하고, 모든 개방형 결과의 score_status를 completed로 설정하거나 제거하고, 기록 전에 개방형 질문 점수/증거를 업데이트합니다.
python scripts/kaoda.py record <grade.json>을 실행하여 오답을 추가하고 전체 시험/시도/채점/HTML 및 소스/자료/심층 연구 파일을 data/learners/<id>/archive/에 보관합니다. record는 보류 중인 개방형 답변 예비 채점을 거부합니다.
python scripts/kaoda.py dashboard <id>를 실행하여 정적 학습자 허브를 새로 고칩니다: 총점 보드, 시험 모음, 오답 보드, 평이한 언어 메모.
변형 복습을 위해 python scripts/kaoda.py review <id>를 실행하거나 주간 종합 평가를 위해 python scripts/kaoda.py weekly <id> --since 7d를 실행합니다.

연구 우선 선택 게이트

연구 허용 여부를 묻지 마십시오. 연구는 필수입니다. 연구 방향은 고정된 체크리스트가 아닙니다: 메커니즘, 경계, 오해, 반례, 전이는 최소 사항입니다. 자료가 요구할 때 배경, 논란, 위험, 대안, 업스트림/다운스트림 지식, 현실적 적용, 도구, 지표, 역사, 도메인 맥락을 추가하십시오.

연구 후 다음을 묻거나 확인하십시오:

복습 모드/시간: 복습 모드 · 5분, 정상 모드 · 10분, 질문 모드 · 30분, 심층 질문 · 45분.
질문 스타일: 진지한 복습, 재미있는 질문, 독설 질문, 면접관 추궁, 상사 추궁, 친구 놀리기, 반례 사냥꾼, 개념 사기 식별, 댓글 판단, 또는 혼합 스타일.
오답-지식 정책은 활성 이력이 있을 때만 묻습니다: 현재 자료만 복습, 과거 오답 포함, 최근 오답 집중 질문, 또는 현재 자료 위주, 오답 보조.

기본 권장 사항: 혼합 스타일의 정상 모드 · 10분. 과거 오답을 조용히 섞지 마십시오. 오답이 있을 때 묻습니다.

질문 가독성 계약

질문은 명확한 복습 시트처럼 읽혀야 하며, Agent가 프롬프트 구조를 드러내는 것처럼 읽혀서는 안 됩니다.

소스 계층, 스타일 패밀리, 능력 유형, 난이도는 JSON 메타데이터로만 유지하고, 보이는 질문 프롬프트에는 절대 출력하지 마십시오.
원문 보정｜진지한 복습｜단일 선택, 스타일 큐 문장, 단서:와 같은 레이블로 프롬프트에 접두사를 붙이지 마십시오.
가장 안정적인, 어떤 이해가 가장 안정적인가, 분명히 아는 척, 서두르지 마, 이 문제는 속이지 않는다, 한눈에 거짓, 가짜 이해와 같은 자기 의식적인 AI 표현을 피하십시오.
평이하고 답변 가능한 표현을 사용하십시오: 어떤 문장이 자료와 일치하는지, 어떤 문장이 틀렸는지, 문장이 참인지, 어떤 개념이 설명과 일치하는지, 시나리오에서 개념을 어떻게 적용하는지.
유형별 섹션으로 질문을 렌더링하십시오: 단일 선택, 다중 선택, 참/거짓, 빈칸 채우기, 그 다음 단답형/구술형.
주요 시험과 오답/주간 변형에서 객관식 정답 위치를 옵션 ID 전체에 분산시키십시오. 생성된 시트의 모든 답변이 A처럼 보이지 않도록 하십시오.
확인 기반 제출 후, HTML은 점수, 유형별 점수, 오답, 취약 지식 포인트, Agent가 읽을 수 있는 보고서 패키지를 위한 내보내기 버튼 하나가 있는 보고서 페이지로 전환되어야 합니다.
내부 아티팩트에 대한 여러 내보내기 버튼을 노출하지 마십시오. attempt.json, exam.json, 채점 지침은 단일 내보내기 Agent 보고서 내부에 속합니다.

소스 처리

비디오, PDF, 아티클 URL, 스캔 문서, 자막을 처리하기 전에 references/source_ingestion.md를 읽으십시오.

사용자가 처음이거나 비디오/PDF 추출에 실패하면 python scripts/kaoda.py doctor를 실행하고 결과를 평이한 언어로 설명한 후 도구를 설치하거나 트랜스크립트를 제공하도록 요청하십시오.

엄격한 규칙:

소스 출처(페이지, 타임스탬프, URL, 세그먼트 ID)를 보존하십시오.
오디오 트랜스크립션보다 자막/PDF 텍스트/사용자 텍스트를 선호하십시오.
비디오, 로컬 미디어 파일, 스캔 PDF, 아티클 페이지에서 사용 가능한 텍스트를 얻을 수 없으면 생성된 manual_input.txt/manual_transcript.txt 워크스페이스와 ingest-manual을 사용하십시오. 제목, URL, 파일 이름, 스니펫에서 질문을 생성하지 마십시오.
확장 연구는 소스 파생 지식과 별도로 표시하십시오.

품질 게이트

최종 전달 전에 references/quality_gates.md를 읽으십시오.

정상 실행에 필요한 파일:

segments.jsonl
material_report.json
deep_research.json
review_choices.md
research_prompt.md
입력이 단순 주제였을 때 topic_research.md와 source_links.json
exam_brief.json
exam.json
exam.html
grading_prompt.md
학습자가 복습을 완료하고 내보낸 후 kaoda_agent_report.md
채점 후 grade.json
grade.json.open_review.status가 pending_agent_review일 때 agent_open_review.md
오답 기록 후 mistake_bank.jsonl
학습자 대시보드 새로 고침 후 dashboard/index.html, dashboard/exams.html, dashboard/mistakes.html, dashboard/notes.html
학습자가 Agent가 메모를 더 자연스러운 개인적인 어조로 다시 작성하길 원할 때 dashboard/notes_agent_pack.md

추출이 차단되면 필요한 연속 파일은 source_status.json, manual_input.txt 또는 manual_transcript.txt, manual_text_request.md입니다. ingest-manual 후 정상적인 필수 파일로 계속 진행하십시오.

하지 말아야 할 것

최종 제품으로 요약 책자를 생성하지 마십시오.
필수 연구와 가벼운 모드/스타일 선택이 exam_brief.json에 기록되기 전에 build-exam을 실행하지 마십시오.
deep_research.json을 작성하고 검증하기 전에 plan-exam을 실행하지 마십시오.
연구 전에 이전의 5가지 질문 수집 번들을 묻지 마십시오.
소스 전용 모드에서 외부 확장 연구가 수행되었다고 주장하지 마십시오.
기억 질문만 생성하지 마십시오.
보이는 질문 텍스트에 내부 레이블이나 스타일 프롬프트를 노출하지 마십시오.
긴 개방형 답변 질문의 벽을 만들지 마십시오. 복습 모드와 정상 모드는 객관식 우선이며 브라우저에서 직접 채점 가능해야 합니다. 단답형/구술형 프롬프트는 질문 모드와 심층 질문에 속합니다.
키워드 매칭만으로 개방형 답변을 채점하지 마십시오.
open_review.status가 여전히 pending_agent_review로 설정된 grade.json을 기록하지 마십시오.
주제 연구 노트와 출처를 작성하기 전에 빈 주제에서 질문을 생성하지 마십시오.
복습이나 주간 평가에 오래된 질문을 재사용하지 마십시오.
확신에 찬 표현 뒤에 누락된 소스 증거를 숨기지 마십시오.
레이블 없이 소스 사실과 확장 연구를 혼합하지 마십시오.

kaoda-review (拷打式复盘 Agent Skill)