docs(handoff): mark brainstorming-needed items in v0.20.1 findings todo

각 todo 에 fix path classification 추가: - 🧠 필수: design / user expectation 결정 필요 — brainstorming skill 우선 - 🔧 mechanical: spec drift 또는 명확한 fix — 별 brainstorming X - 📝 mild discussion: spec drafter self-review 로 trade-off 결정 가능 Classification: - 🧠 필수 (2): #1 Ask 영어→한국어 response policy, #4 doc.lang semantic - 🔧 mechanical (4): #2 bulk schema, #5/#6 docs sync, #7 schema rename - 📝 mild (3): #3 list title, #8 Ollama default 추가 brainstorming 후보 (직접 finding 외): - BS-A: HTML corpus 지원 (1415 file skipped) - BS-B: Tier 1/2/3 chunker UX visibility - BS-C: kebab dogfood subcommand (자동화) - BS-D: 영문 code chunk 의 tokenized_korean_text 효율 - BS-E: builtin_blacklist 명세 노출 권장 워크플로: 1. brainstorming 단계 먼저 (#1, #4 + BS-x 별 검토) 2. mechanical batch (#2, #5, #6, #7) — 한 PR 3. mild discussion batch (#3, #8) 4. dogfood retest → v0.20.2 patch release
2026-05-28 19:45:53 +00:00
parent 6bf4e82e62
commit b08941d6ab
1 changed files with 130 additions and 41 deletions
--- 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 <id>` 의 응답에 `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 명세

 ---