Merge pull request #28 from itsflaid/codex/refine-ask-output

Refine ask retrieval and init UX

Author: itsflaid

docs/for-me-personal/DEBUG.md

@@ -744,3 +744,51 @@ TypeScript. Retry rate limit memakai satu cabang `if`, bukan loop berbatas.
 
 TypeScript type assertion tidak memvalidasi data runtime. Semua data persisted
 harus melewati boundary validation sebelum dipakai oleh command lain.
+
+## 14. Ask Output Terlalu Ramai Dan Jawaban Berulang
+
+**Tanggal:** 2026-06-16
+**Status:** Selesai
+
+### Gejala
+
+`devmap ask` menampilkan `Relevant Files` dengan alasan scoring yang panjang
+dan jawaban AI dapat mengulang kalimat, memberi high-level outline terlalu
+panjang, atau menampilkan contoh kode padahal user hanya butuh arah file.
+
+### Akar Masalah
+
+Output human-readable memakai detail ranking internal yang lebih cocok untuk
+machine/debug output. Keyword extraction juga masih menyimpan connector word
+English seperti `to` dan `in`, sehingga partial match dapat menaikkan file yang
+tidak relevan. Prompt `ask` belum memberi kontrak format yang cukup tegas.
+
+### Solusi
+
+- Human output `Relevant Files` hanya menampilkan path.
+- Alasan scoring tetap dipertahankan pada `ask --json`.
+- Connector word English umum dikeluarkan dari keyword ranking.
+- Action word English dipisahkan menjadi intent generik, bukan hardcoded ke
+  satu topik atau satu file.
+- Path/export scoring lebih memprioritaskan exact search terms daripada
+  substring match.
+- Retrieval menambahkan confidence dan minimum relevance threshold. Jika tidak
+  ada file yang melewati threshold, `ask` berhenti dengan jawaban lokal
+  low-confidence tanpa memanggil Groq.
+- Context file menyiapkan field `exports`, `topFunctions`, dan `purpose` untuk
+  function-level navigation berikutnya tanpa mengubah scope extraction sekarang.
+- Prompt `ask` meminta direct answer, `Key Files`, `Evidence` jika perlu,
+  `Limits` jika context kurang, dan melarang repetisi serta code example panjang
+  kecuali diminta. Untuk pertanyaan implementasi, prompt mengarahkan jawaban ke
+  file/fungsi existing dalam context sebelum menyarankan file baru.
+
+### Verifikasi
+
+- `pnpm --filter devmap exec tsx --test test/context-builder.test.ts test/ask-command.test.ts test/ai-client.test.ts`
+
+### Pelajaran
+
+Informasi ranking bagus untuk agent dan debugging, tetapi terlalu bising untuk
+terminal manusia. Human mode harus ringkas; machine detail harus berada di JSON.
+Untuk MVP, `ask` adalah navigation helper berbasis snapshot, bukan coding
+agent. Low-confidence harus hemat token dan jujur, bukan meminta AI menebak.

docs/for-me-personal/PROGRESS.md

@@ -1,6 +1,50 @@
 # Progress DevMap
 
-Terakhir diperbarui: 2026-06-15
+Terakhir diperbarui: 2026-06-16
+
+## Update 2026-06-16
+
+### Ask Output Polish
+
+- Human-readable `devmap ask` sekarang hanya menampilkan path pada bagian
+  `Relevant Files`; alasan scoring tetap tersedia di `--json`.
+- Query understanding memisahkan intent umum (`add_feature`, `change`,
+  `debug`, `explain`, `navigate`, `general`) dari keyword pencarian agar
+  action word seperti `add`, `change`, atau `where` tidak mengganggu ranking.
+- Retrieval sekarang menyimpan `confidence` (`high`, `medium`, `low`) dan
+  `topScore` pada `QuestionContext`.
+- Minimum relevance threshold mencegah file dengan skor lemah dikirim hanya
+  karena menjadi kandidat terbaik dari hasil yang sama-sama tidak relevan.
+- Jika tidak ada file melewati threshold, `relevantFiles` kosong dan `ask`
+  memberi jawaban lokal low-confidence tanpa memanggil Groq.
+- Context keyword extraction mengabaikan connector word English seperti `to`
+  dan `in` agar file seperti `doctor.ts` tidak menang hanya karena partial
+  stop-word match.
+- Scoring path/export sekarang memprioritaskan exact search term dibanding
+  substring match, sehingga ranking lebih stabil untuk berbagai jenis
+  pertanyaan.
+- Prompt `ask` sekarang meminta jawaban langsung, tidak mengulang pertanyaan,
+  tidak mengulang section/sentence, dan tidak memberi contoh kode panjang
+  kecuali user memintanya eksplisit.
+- Prompt `ask` menerima intent generik dan diarahkan untuk memulai dari file
+  atau fungsi existing yang tersedia di context sebelum menyarankan file baru.
+- Context file sudah menyiapkan field future-oriented seperti `exports`,
+  `topFunctions`, dan `purpose`; extraction fungsi lengkap belum masuk scope.
+- Scoring kembali memakai data project map utama seperti route metadata dan
+  entry points agar `ask` tetap navigation helper berbasis snapshot.
+- Focused tests mencakup keyword extraction, ranking anti stop-word, output
+  terminal ringkas, intent extraction generik, relevance confidence, threshold
+  low-confidence, dan prompt contract.
+- Verification lulus untuk `pnpm test:cli`, `pnpm build:cli`, dan
+  `git diff --check`.
+
+### Init UX Polish
+
+- `devmap init` human-mode sekarang menampilkan DevMap welcome brand panel di
+  awal command.
+- Provider tidak lagi diprompt terpisah karena MVP hanya mendukung Groq.
+  Output cukup menampilkan `Provider Groq`, lalu meminta Groq API key.
+- Focused verification lulus untuk init dan welcome tests.
 
 ## Update 2026-06-15
 

docs/for-me-personal/TEST.md

@@ -23,13 +23,30 @@ Jalankan focused test ranking dan evaluation:
 pnpm --filter devmap exec tsx --test test/context-builder.test.ts test/context-builder-eval.test.ts
 ```
 
+Untuk polish output `ask`, jalankan focused contract test:
+
+```powershell
+pnpm --filter devmap exec tsx --test test/context-builder.test.ts test/ask-command.test.ts test/ai-client.test.ts
+```
+
 Expected result:
 
 - Pertanyaan produk tidak memilih `test/`, `tests/`, `__tests__/`, fixture,
   `*.test.*`, atau `*.spec.*`.
 - Pertanyaan testing dalam English dapat memilih file tersebut.
 - Pertanyaan navigasi English memilih maksimal dua file dan 60 baris per file.
 - Istilah CLI dan web UI memprioritaskan package yang sesuai.
+- Connector word English seperti `to` dan `in` tidak menjadi keyword ranking.
+- Action word English seperti `add`, `change`, dan `where` dipakai sebagai
+  intent, bukan keyword ranking.
+- Query perubahan fitur yang berbeda topik tetap memilih file existing yang
+  relevan berdasarkan path/export/import, bukan special-case satu framework.
+- Query tanpa match kuat mengembalikan `confidence: "low"`, `topScore: 0`,
+  dan `relevantFiles: []`, bukan fallback ke critical file acak.
+- Query low-confidence tidak memanggil Groq. Command memberi template lokal
+  agar hemat token dan tidak mengarang file.
+- Human-readable `Relevant Files` hanya menampilkan path; alasan scoring tetap
+  dicek melalui output `--json`.
 - Evaluation tetap top-1 accuracy 20/20 dan top-3 recall 20/20.
 
 Manual source-mode check:
@@ -43,6 +60,12 @@ pnpm dev:cli ask "where is the web UI dashboard component?"
 Periksa `Relevant Files` dan prompt token usage. Query pertama seharusnya
 memprioritaskan production CLI source dan memakai context jauh lebih kecil
 daripada default lama lima file dengan maksimal 200 baris per file.
+Untuk pertanyaan implementasi, jawaban seharusnya langsung menyebut file yang
+perlu diperiksa/diedit lebih dulu dan tidak menampilkan contoh kode panjang
+kecuali diminta.
+Jika confidence rendah, jawaban seharusnya mengatakan tidak ada strong match,
+tidak menampilkan `Asking Groq`, dan tidak menyebut file random sebagai sumber
+pasti.
 
 ## Model Routing And Override