kw-explore

# /kw-explore — drive a research project with the principle library This is the **problem-driven** loop. (`/kw` is the corpus-driven loop: absorb papers, synthesize globally. `/kw-explore` starts from the user's actual problem and pulls the library toward solving it.) It is the workflow that turns the engine from a knowledge library into a research accelerator. You are the orchestrator. Dispatch the `kw-*` subagents for reading/distilling (model boundary below); do the framing/mapping/assembly reasoning yourself. **Separation of concerns (hard rule).** Use-case outputs — the problem decomposition, the design, the handoff — go in the **user's project** (cwd). Reusable principles go into the **linked knowledge base** (`kw status` shows which one). Never mix: the knowledge base stays domain-general and reusable across projects. **Model boundary (same as /kw).** The orchestrator never reads PDFs or calls `read_*`/`search_*`/ `download_*` MCP tools. Acquisition → `kw-fetcher` (sonnet); reading → `kw-reader` (sonnet); distilling → `kw-distiller` (opus). Pass `model` explicitly on every Agent dispatch. Prerequisite: the project must be linked to a knowledge base. If `kw status` errors, run `kw link <name-or-path>` (or `/kw-init`) first. --- ## Phase 0 — Frame the problem (the most important step) A good decomposition is most of the value. Do not skip to fetching papers. **If a Question Card already exists** (`<project>/problems/<slug>/QUESTION.md`, produced by `/kw-question`): the question's *worth* is already validated — do NOT re-litigate stakes/ falsifiability. Read the card and go straight to extracting the structural signature (below). If the user only has a vague idea and no card, and it's unclear whether the question is even worth pursuing, suggest running `/kw-question` first. 1. Interview the user just enough to extract a **problem signature**: the *structural* axes of their problem, pushed toward the form the library indexes by — structural properties, not domain narrative. (E.g. not "vaginal microbiome typing" but "compositional/simplex-constrained data", "continuous spectrum + possible discrete sub-structure", "cross-population transferability", "must encode temporal dynamics".) 2. **Challenge the framing.** Find the load-bearing structural difficulty, not the surface complaint. (The CST example: the real defect was "resolution too low — classifying in a space where the signal has already been integrated out", not "the clusters are wrong".) 3. Write `<project>/problems/<slug>/PROBLEM.md`: the signature axes, plus what any solution MUST satisfy (the constraints — e.g. "must work on both targeted-amplicon AND shotgun data"). 4. **Show the decomposition to the user and confirm it before proceeding.** A wrong signature wastes the whole loop downstream. ## Phase 1 — Absorb the seed papers (if any) For each seed paper the user has (or names), run the standard absorb loop: `kw-fetcher` (if no local PDF) → `kw-reader` → `kw-distiller` → then `kw-verifier scope=all`. New principles land in the linked knowledge base. If the user has no papers yet, skip to Phase 2 (the library may already cover part of the problem) and lean on Phase 3. ## Phase 2 — Map the problem onto the library (coverage) For each axis of the problem signature, run `kw search "<axis keywords>"`. Build a **coverage map** and show it to the user: - **Covered:** axis → matching principle(s) by pid + one-line mechanism. - **Gaps:** axes with no matching mechanism — these are *this problem's* gaps (distinct from the global design-space gaps in `memory/synthesis/gaps.md`). "A pile of papers that's not enough" shows up here as gaps. That's expected — Phase 3 closes them. ## Phase 3 — Fill the gaps (iterate, user-gated) For each gap, propose specific papers or searches that would supply the missing mechanism (name candidate authors/titles/DOIs). On the user's pick: 1. `kw-fetcher` the chosen papers → absorb (reader → distiller → verifier). 2. Re-run the relevant `kw search` and update the coverage map. Report each round: which gaps closed, which remain. Loop until coverage is good enough OR the user stops. Never auto-run many fetch rounds without a pick — keep the human steering. ## Phase 4 — Assemble a principle-grounded design Compose the matched principles into a candidate design/solution for the user's project: - Each design decision **cites the principle(s) it rests on** — build a traceability matrix (module → primary pids → supporting pids). - Include concrete specs where the principles imply them (equations, data requirements, a validation plan). - **Mark every module still without principle support** as a remaining gap + risk. Write/update `<project>/docs/DESIGN.md`. (See the PRISM design as a worked example of the target shape: modules, math specs, data requirements, validation plan, traceability matrix, risks.) ## Phase 5 — Iterate / handoff The design is living — each future round of reading sharpens it. Write/update `<project>/plan/HANDOFF.md`: current state, decisions made (with rationale), the next gaps to fill, and the exact commands/prompts to resume. Also write a short `<project>/docs/RATIONALE.md` capturing WHY the design is shaped this way (the problem signature + the direction choices) so a fresh session can continue seamlessly. --- Reproducibility: after each phase, append a one-line run record (phase, ids touched, subagents+models, date) to `.kw/logs/runs.log`. After Phase 4, offer: "(a) 补更多 gap (b) 深化某个模块的设计 (c) 跑 L3 综合看全局 (d) 收尾写 handoff".