diff --git a/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md b/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md index 0f8ccbe..5a9b87b 100644 --- a/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md +++ b/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md @@ -32,24 +32,39 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 ## 1. 발견된 todo (severity + priority) +각 todo 의 `Brainstorming?` 필드는 fix path 가 mechanical 인지 (구현 만 필요), 아니면 사용자 expectation / design trade-off 검토 가 필요한지 표시. + +- **🧠 brainstorming 필수**: 사용자 의도 / trade-off 가 명확하지 않아 단순 구현 전에 spec drafter + critic 또는 사용자 confirmation 필요. `superpowers:brainstorming` skill 우선 invoke. +- **🔧 mechanical**: spec drift 또는 명확한 fix path. 별 brainstorming 없이 spec → plan → execution. +- **📝 mild discussion**: 작은 trade-off 가 있으나 spec drafter 의 self-review 로 결정 가능. + + + ### 🐛 P0 — bug 또는 사용자 expectation 과 다른 동작 #### Todo #1: Ask 영어 query 의 응답이 한국어 (Finding O) - **Severity**: medium +- **Brainstorming?**: 🧠 **필수** (response language policy = design 결정) - **Scenario**: `kebab ask 'What is RAG architecture?' --mode hybrid` - **Observed**: 답변이 `"RAG는 ... 정의됩니다 [#1]"` (한국어) - **Expected**: 답변이 input query 의 언어 (영어) 와 매칭 - **Suspected cause**: `prompt_template_version: rag-v2` 가 응답 언어를 한국어로 강제. `crates/kebab-rag/` 의 prompt template 또는 system message 검토 필요. -- **Action**: +- **Brainstorming 의 핵심 질문**: + - 한국어 corpus 위주 user 가 영어 query 던질 때 응답 언어는? (사용자 의도 = "영어로 답해줘" vs "내 KB 의 한국어 content 기반 한국어로 정리해줘") + - 한국 + 영어 혼합 query → 어느 언어 우선? + - LLM 의 자동 language matching (예: gemma4 의 default 다국어 응답) vs prompt 의 명시 강제? + - 사용자 명시 옵션 (`kebab ask --response-lang ko/en/auto`) 도입 적절한지? + - RAG citation 의 source 가 다른 언어 일 때 인용 표기 형식? +- **Action (brainstorming 후)**: 1. `crates/kebab-rag/src/prompt.rs` (또는 등가 location) 의 system prompt 확인. - 2. Input query 의 language detection (`kebab-core` 의 lang detection 모듈) → response language 매칭 옵션 또는 default 변경. - 3. 한국어 user 의 default 한국어 응답 유지 + 영어 user 의 영어 응답 보장. -- **Test scenario**: handoff 시점의 `/build/dogfood/kb/` 에서 `kebab ask 'What is RAG?' --hide-citations` 응답 언어 영어 확인. + 2. Brainstorming 결과 따라 default policy 결정 → spec drafter → plan → implementation. + 3. Test scenario: handoff 시점의 `/build/dogfood/kb/` 에서 영어/한국어/혼합 query 응답 언어 확인. #### Todo #2: bulk search input format 불명확 (Finding V) - **Severity**: medium (docs + wire schema) +- **Brainstorming?**: 🔧 **mechanical** (실제 input shape 가 코드 안에 정의됨 — documentation + help 갱신만 필요) - **Scenario**: ```bash echo '{"text":"한국","mode":"lexical","k":3}' | kebab search --bulk --json @@ -67,6 +82,10 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 #### Todo #3: list docs 의 title 중복 (Finding Q) - **Severity**: low (UX) +- **Brainstorming?**: 📝 **mild discussion** (3 가지 옵션 trade-off — spec drafter self-review 로 결정 가능) + - Option A: human-readable 출력에 `doc_path` 보조 표시 (현재 `--json` 에만) + - Option B: title 의 unique 화 (`"Registry — Registry.java"` 처럼 file basename suffix) + - Option C: title 의 source 변경 — 첫 H1 → frontmatter title → 파일명 fallback 의 우선순위 명시 - **Scenario**: `kebab list docs --json | jq '.[0:5]'` - **Observed**: 여러 다른 file 이 `title: "Registry"`, `title: "dispatch"` 등 동일 title 로 반환 — heading-based title 추출이 unique 안 됨. - **Expected**: 사용자가 list 만 보고 어느 file 인지 식별 가능. @@ -78,19 +97,28 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 #### Todo #4: doc.lang = "und" 53% (Finding U) - **Severity**: low (UX + accuracy) +- **Brainstorming?**: 🧠 **필수** (doc.lang 의 의미 자체 재정의 필요 — semantic 결정) - **Scenario**: `kebab schema --json | jq '.stats.lang_breakdown'` → `{en: 1358, ko: 89, und: 2493}` - **Observed**: Java/Kotlin/C++ 등 code file 에서 자연 언어 감지 실패율 53%. -- **Expected**: code file 의 source language (예: `lang: "rust"`, `lang: "python"`) 를 우선 사용하거나, code chunk 의 comment 만 추출해서 lang 감지. -- **Action**: - 1. `crates/kebab-core/src/lang.rs` (또는 등가) 의 lang detection 의 doc 적용 위치 확인. - 2. Code chunk 의 `code_lang` 이 이미 정확 (rust, python, typescript 등) — `doc.lang` 도 code 의 source language fallback 권장. - 3. 자연 언어 doc.lang 의 의미 명확화 — code file 의 doc.lang 은 source code lang vs comment NL 중 어느 것? +- **Brainstorming 의 핵심 질문**: + - `doc.lang` 의 user-facing 의미 = "자연 언어" (natural language of comments / prose) vs "source language" (rust/python/etc.) vs "primary language" (혼합 시 dominant) 중 어느 것? + - 사용자가 `kebab search --lang ko` 할 때 의도 = "한국어 prose 문서 찾기" vs "한국어 주석 포함 code 도 같이"? + - Code 의 자연 언어 (예: Rust 코드의 한국어 주석) 처리 — comment 만 추출해서 lang detect 가 옳은지? + - Tier 1 (AST) / Tier 2 (resource) / Tier 3 (paragraph) chunker 별로 doc.lang 의 의미 차이 허용 가능한지? + - 별 `doc.code_lang` (source code language) + `doc.nl_lang` (natural language) 분리 도입? +- **Action (brainstorming 후)**: + 1. `crates/kebab-core/src/lang.rs` (또는 등가) 의 lang detection 위치 확인. + 2. Code chunk 의 `code_lang` 이 이미 정확 — `doc.lang` 도 fallback 으로 활용할지 결정. + 3. 결정된 semantic 따라 spec drafter → plan → implementation. ### ⚠ P1 — Documentation drift +(모든 P1 todo 는 🔧 **mechanical** — wire schema 의 실제 동작이 source-of-truth, README/docs 만 sync) + #### Todo #5: fusion_score 위치 표기 (Finding H/L) - **Severity**: low +- **Brainstorming?**: 🔧 **mechanical** - **Scenario**: README 의 wire schema 예시 - **Observed**: README 의 `fusion_score` 가 top-level 같이 표기되어 있으나, 실제 wire schema 의 `.retrieval.fusion_score`. - **Action**: @@ -101,6 +129,7 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 #### Todo #6: score_kind="bm25" 의 의미 (Finding X) - **Severity**: low +- **Brainstorming?**: 🔧 **mechanical** - **Scenario**: `kebab search --mode lexical 'tokenizer'` → `score_kind: "bm25", score: 0.943, fusion_score: 0.943, lexical_score: 0.943` - **Observed**: lexical mode 에서 `fusion_score == lexical_score == score` 동일. - **Expected**: `fusion_score` 는 hybrid 전용임이 docs 에 명확. @@ -109,6 +138,7 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 #### Todo #7: schema --json 의 index_version vs lexical_index_version (Finding G) - **Severity**: low +- **Brainstorming?**: 📝 **mild discussion** (rename 옵션 결정 — 별 brainstorming 없이 spec self-review 로 가능) - **Observed**: `kebab schema --json | jq '.models.index_version'` → `"v1"` (wire schema 의 v1) - **Expected**: `lexical_index_version` (`fts5-v009-korean-morphological`) 가 별도 필드. 두 의미 다름 — 사용자 혼동 가능. - **Action**: `schema.v1` JSON 의 `index_version` 이름 또는 documentation 변경. 가능 옵션: @@ -121,6 +151,7 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 #### Todo #8: Ollama endpoint default 가 localhost (Finding M) - **Severity**: low (setup) +- **Brainstorming?**: 📝 **mild discussion** (default 유지 vs env var override vs auto-ping 의 작은 trade-off) - **Scenario**: `kebab init` 의 default `config.toml` - **Observed**: `endpoint = "http://127.0.0.1:11434"` (localhost) - **Expected**: 사용자 environment 가 remote ollama (192.168.0.47) 인 경우 init 후 수동 갱신 필요. @@ -168,14 +199,28 @@ priority: dogfood 단계 발견 findings 의 fix / docs / behavior 검토 ### 2.2 우선 순위 + 작업 흐름 +**🧠 Brainstorming 필수 todo (2개)** — `superpowers:brainstorming` skill 우선 invoke 후 spec 진입: + +- **Todo #1** (Ask 영어→한국어 응답): response language policy 가 design 결정. user intent / RRF 영향 / `--response-lang` flag 옵션 등 논의. +- **Todo #4** (doc.lang=und 53%): `doc.lang` 의 user-facing semantic 재정의 (자연 언어 vs source language vs primary language). 별 field 분리 가능성도. + +**🔧 Mechanical todo (4개)** — brainstorming 없이 spec drafter → plan → execution 진입 가능: + +- Todo #2 (bulk search input format) — wire schema + help docs 갱신 +- Todo #5/#6 (fusion_score / score_kind 의 docs 위치) — README + schema docs sync + +**📝 Mild discussion todo (3개)** — spec drafter 의 self-review 로 trade-off 결정 가능: + +- Todo #3 (list docs title 중복) — 3 옵션 (doc_path 보조 / title unique / source 변경) +- Todo #7 (schema index_version) — rename vs documentation 만 +- Todo #8 (Ollama endpoint default) — localhost 유지 + hint 갱신 vs env var override + 권장 순서 (P0 → P1 → P2): -1. **Todo #2 (bulk search input)** — wire schema + help docs 빠른 정리 (S spec 없이 small fix PR 가능). -2. **Todo #1 (Ask 영어 응답 한국어)** — rag prompt template 의 system message 갱신. 별 spec/plan 필요할 수 있음 (사용자 expectation 변경). -3. **Todo #3 (list docs title 중복)** — UX 작은 fix. -4. **Todo #4 (lang=und 53%)** — 의미 명확화 + code lang fallback. 별 spec. -5. **Todo #5/#6/#7** — README + wire schema docs 한 PR 으로 묶어 정리. -6. **Todo #8** — init hint 메시지 한 줄. +1. **Brainstorming 단계 먼저** (Todo #1, #4) — `superpowers:brainstorming` skill 로 design 의도 명확화. 사용자 confirmation 받은 후 spec → plan → execution. +2. **Mechanical batch** (Todo #2, #5, #6, #7) — 한 PR 으로 docs/wire-schema/v1 + README + bulk help 갱신. +3. **Mild discussion batch** (Todo #3, #8) — spec drafter self-review 후 small PR. +4. **dogfood retest** — 전체 v0.20.2 patch release 컷 직전. ### 2.3 branch + workflow @@ -193,6 +238,43 @@ git checkout -b fix/v0.20.2-dogfood-findings --- +## 2.4 추가 brainstorming 후보 (직접 finding 외) + +도그푸딩 단계에서 부각된 미래 design 결정 후보. 위 todo 의 fix 와 별 — 별도 spec 으로 다룰 가능성: + +### 🧠 BS-A: HTML corpus 지원 + +- **Status**: 도그푸딩 corpus 의 1415 HTML file 가 모두 skip (extension 미지원). +- **Question**: HTML 가 일반 user KB 의 흔한 source format (saved web pages, ref docs, etc.). 지원 안 함이 의도된 omission 인지 / Tier 3 paragraph fallback 으로 처리할 가치 있는지? +- **Trade-off**: HTML parser (markup stripping + heading extraction) 의 추가 dependency vs corpus coverage 확장. Tier 3 fallback 으로 충분? +- **Spec scope**: 한 sub-item 의 1 file 인 fixture 검증 시작 → real corpus 도그푸딩 확대. + +### 🧠 BS-B: Tier 1/2/3 chunker 의 사용자 visibility + +- **Status**: `kebab schema --json` 의 `active_chunkers` 에 14 chunker 노출. 사용자는 어느 file 가 어느 Tier 로 처리됐는지 모름. +- **Question**: `kebab inspect doc ` 의 응답에 `tier_used: "Tier 1 (AST)"` / `"Tier 3 (paragraph fallback)"` 같은 field 추가 가치 있는지? +- **Trade-off**: wire schema 확장 vs UX 명확성. Tier fallback debug 시 유용. + +### 🧠 BS-C: 도그푸딩 자동화 (`kebab dogfood` subcommand?) + +- **Status**: 도그푸딩이 수동 ad-hoc — `/build/dogfood/corpus` 으로 manual setup → CLI 명령들 sequential 실행. +- **Question**: `kebab dogfood --scenario all` 같은 sub-command 도입해서 DOGFOOD.md §1~§13 의 시나리오 자동 실행 + JSON evidence summary? release 마다 사용자 가 한 명령으로 검증 가능. +- **Trade-off**: CLI 표면 확장 vs 도그푸딩 reproducibility 자동화. 별 `kebab-eval` crate 와 overlap 가능 (eval = goldens 비교, dogfood = release 검증). + +### 📝 BS-D: Code chunk 의 N-gram supplement 의미 + +- **Status**: 도그푸딩 통계 — Korean tokenized chunks 34847/34896 (99.86%). 즉 영문 code chunk 도 `tokenized_korean_text` 가 populated. ko-dic 의 영문 처리 결과 (영문 token + N-gram 미적용) 가 빈/유의미한지? +- **Question**: 영문 code chunk 의 `tokenized_korean_text` 가 항상 raw text 의 duplicate 면 storage 낭비. populate 안 하고 NULL 두는 게 더 효율? +- **Trade-off**: ko-dic 호출 비용 (이미 chunk 마다 발생) vs storage 절약. + +### 📝 BS-E: Ingest 의 .git/ 자동 제외 명세 (Finding A 확장) + +- **Status**: `.git/` 디렉토리는 자동 builtin_blacklist 로 제외 (현재 의도된 동작), 그러나 `.kebabignore` 또는 docs 에 explicit 표기 없음. 사용자가 추가 builtin_blacklist 가 무엇인지 모름. +- **Question**: `node_modules/`, `target/`, `.git/` 같은 builtin_blacklist 의 명세를 schema 의 `capabilities.builtin_blacklist` 또는 wire schema 에 노출? +- **Trade-off**: wire 확장 vs UX 명확성. + +--- + ## 3. 도그푸딩 재실행 (regression 방지) 새 finding fix 후 도그푸딩 재실행 절차: @@ -231,32 +313,39 @@ $KB --config $CFG schema --json | jq '.models.index_version' # To ## 5. 발견 finding 의 cumulative summary table -| # | Finding | Severity | Category | Target todo | -|---|---|---|---|---| -| A | scan vs corpus 21 file 차이 | none | `.git/` 자동 제외 (의도) | — | -| B | html 1415 skipped (extension) | none | 의도 — html 미지원 | — | -| C | size_exceeded 5 files | none | 의도 — config 의 max_size_kb 제한 | — | -| D | lang_breakdown und=53% | low | UX | #4 | -| E | pdf=8 from ts-zod logos | none | 부산물, 정상 동작 | — | -| F | Korean tokenized 34847/34896 | none | N-gram supplement 정상 | — | -| G | schema index_version="v1" | low | docs | #7 | -| H | fusion_score location | low | docs | #5 | -| I | Korean queries hit | none | V009 closure 확인 | — | -| J | English whole-token regression | none | V009 회귀 정상 | — | -| K | Vector search semantic | none | 정상 | — | -| L | fusion_score location docs | low | docs | #5 | -| M | Ollama endpoint default localhost | low | setup | #8 | -| N | (skipped, M 와 동일) | — | — | — | -| O | Ask 영어 query → 한국어 응답 | medium | behavior | #1 | -| P | fetch chunk target.text path | none | jq query 실수, 실제 정상 | — | -| Q | list docs title duplicate | low | UX | #3 | -| R | Edge case error handling | none | 정상 | — | -| S | jq error in test script | none | 내 query 실수 | — | -| T | Korean + punct OK | none | 정상 | — | -| U | doc.lang = und | low | UX | #4 | -| V | bulk search input shape | medium | docs+schema | #2 | -| W | code-lang filter | none | 정상 | — | -| X | score_kind="bm25" 의미 | low | docs | #6 | +| # | Finding | Severity | Category | Target todo | Brainstorming? | +|---|---|---|---|---|---| +| A | scan vs corpus 21 file 차이 | none | `.git/` 자동 제외 (의도) | — | BS-E (선택) | +| B | html 1415 skipped (extension) | none | 의도 — html 미지원 | — | BS-A (선택) | +| C | size_exceeded 5 files | none | 의도 — config 의 max_size_kb 제한 | — | — | +| D | lang_breakdown und=53% | low | UX | #4 | 🧠 필수 | +| E | pdf=8 from ts-zod logos | none | 부산물, 정상 동작 | — | — | +| F | Korean tokenized 34847/34896 | none | N-gram supplement 정상 | — | BS-D (선택) | +| G | schema index_version="v1" | low | docs | #7 | 📝 mild | +| H | fusion_score location | low | docs | #5 | 🔧 | +| I | Korean queries hit | none | V009 closure 확인 | — | — | +| J | English whole-token regression | none | V009 회귀 정상 | — | — | +| K | Vector search semantic | none | 정상 | — | — | +| L | fusion_score location docs | low | docs | #5 | 🔧 | +| M | Ollama endpoint default localhost | low | setup | #8 | 📝 mild | +| N | (skipped, M 와 동일) | — | — | — | — | +| O | Ask 영어 query → 한국어 응답 | medium | behavior | #1 | 🧠 필수 | +| P | fetch chunk target.text path | none | jq query 실수, 실제 정상 | — | — | +| Q | list docs title duplicate | low | UX | #3 | 📝 mild | +| R | Edge case error handling | none | 정상 | — | — | +| S | jq error in test script | none | 내 query 실수 | — | — | +| T | Korean + punct OK | none | 정상 | — | — | +| U | doc.lang = und | low | UX | #4 | 🧠 필수 | +| V | bulk search input shape | medium | docs+schema | #2 | 🔧 | +| W | code-lang filter | none | 정상 | — | — | +| X | score_kind="bm25" 의미 | low | docs | #6 | 🔧 | + +### Brainstorming summary + +- **🧠 필수 (2 todo)**: #1 Ask response language, #4 doc.lang semantic +- **🔧 mechanical (4 todo)**: #2 bulk input docs, #5 fusion_score docs, #6 score_kind docs, #7 schema field rename +- **📝 mild discussion (3 todo)**: #3 list docs title, #8 Ollama default +- **별 brainstorming 후보 (선택)**: BS-A HTML 지원, BS-B Tier visibility, BS-C 도그푸딩 자동화, BS-D code chunk N-gram, BS-E builtin_blacklist 명세 ---