Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

skills(explore-unknowns): opt-in preference delegation

David Zhang5288ee4a3c3a
diff --git a/.agents/skills/explore-unknowns/SKILL.md b/.agents/skills/explore-unknowns/SKILL.md
index ec1306b..4ea5dbc 100644
--- a/.agents/skills/explore-unknowns/SKILL.md
+++ b/.agents/skills/explore-unknowns/SKILL.md
@@ -50,6 +50,44 @@ When the user moves on to build, review, or merge what the walk mapped, read
[after the walk](references/after-the-walk.md) — the map lives on past
planning.
+## Preference Checkpoint — Offer to Answer on Their Behalf
+
+Count questions the user has answered across the walk, not turns or answers
+found in the territory. After about five or six, if their preferences form a
+clear pattern and questions remain, pause the interview for this checkpoint.
+If the pattern is still unclear, continue targeted questions and offer once
+it becomes clear; do not manufacture questions just to reach the count.
+
+1. List the preferences you have inferred, grounded in their answers, and
+ invite corrections. Ask whether it would help for you to answer matching
+ questions on their behalf: **confirm or edit these preferences and opt in,
+ or keep answering yourself**. This replaces the next interview question.
+2. Wait for explicit opt-in. Confirming the preferences alone is not consent
+ to delegate; silence is not consent either. If they only confirm the
+ preferences, clarify the delegation choice once, then default to the
+ interview if it remains unanswered. If they decline, continue without
+ repeatedly offering.
+3. Once opted in, answer questions whose answers follow clearly from the
+ confirmed preferences, within the scope they delegated. Ask the user when
+ preferences conflict or a new tradeoff falls outside that scope. Investigate
+ missing facts in the territory first; ask only when it cannot resolve them.
+ Preferences cannot substitute for facts about the territory.
+4. Disclose every delegated answer as you make it: **question → answer →
+ preference and reason**, labeled **Answered by the agent on your behalf**.
+ Small batches are fine; never collapse distinct questions into a hidden
+ decision. Carry each entry into the map with that attribution, rather than
+ implying the user personally answered it. Invite corrections without
+ requiring approval of every answer.
+5. Honor corrections and withdrawal immediately. Corrections update the
+ preference summary and reopen decisions they invalidate. Withdrawal stops
+ future delegated answers; keep earlier answers attributed unless the user
+ asks to revisit them. Delegation lasts for this walk and does not
+ authorize implementation or skip the remaining quadrants.
+
+**Done when** the user has chosen whether to delegate and, if opted in, the
+confirmed preferences and delegation scope are recorded alongside the map's
+decision ledger.
+
## Rules
- Walk the quadrants in order, one stage at a time, naming the current
diff --git a/.agents/skills/explore-unknowns/references/stage-2-known-unknowns.md b/.agents/skills/explore-unknowns/references/stage-2-known-unknowns.md
index 73a8031..550b784 100644
--- a/.agents/skills/explore-unknowns/references/stage-2-known-unknowns.md
+++ b/.agents/skills/explore-unknowns/references/stage-2-known-unknowns.md
@@ -8,12 +8,16 @@ the answer lives with the user or in the territory.
1. Inventory the questions the task cannot proceed without, and disclose the
queue ("still queued after this: …") so the user sees how much walk
remains.
-2. Resolve them **one at a time, highest architectural blast radius first** —
- never a wall of questions. Give your recommended answer with each, as
- lettered options the user can answer in a few characters, so they react
+2. Before asking another question, apply the main skill's preference
+ checkpoint when due. Otherwise resolve them **one at a time, highest
+ architectural blast radius first** — never a wall of questions. Give your
+ recommended answer with each, as lettered options the user can answer in
+ a few characters, so they react
rather than compose.
-3. Close every question one of three ways:
+3. Close every question one of four ways:
- **Answered by the user.**
+ - **Answered by the agent on the user's behalf** — only under the
+ preference checkpoint's opt-in and disclosure rules.
- **Answered by the territory** — go read it instead of asking, then show
the user the question and the found answer. A question closed off-screen
isn't closed.
diff --git a/.agents/skills/explore-unknowns/references/stage-4-unknown-unknowns.md b/.agents/skills/explore-unknowns/references/stage-4-unknown-unknowns.md
index ae2c0ea..8713f9a 100644
--- a/.agents/skills/explore-unknowns/references/stage-4-unknown-unknowns.md
+++ b/.agents/skills/explore-unknowns/references/stage-4-unknown-unknowns.md
@@ -17,8 +17,9 @@ the code the task will touch and turns silent traps into map entries.
inherits; escalate them to the map rather than silently absorbing them.
2. Report each finding as a card: the **evidence** (file and line), **why it
bites**, and **what it changes** about the task. Worst first.
-3. A finding that needs a user decision closes like a stage-2 question:
- lettered options with your recommendation. A finding that only needs
+3. A finding that needs a decision follows the stage-2 closure rules,
+ including preference-based delegation when applicable. If asking the user,
+ give lettered options with your recommendation. A finding that only needs
awareness goes straight on the map as a sharp edge.
Remember the global rule: findings that bear on decisions already in flight
diff --git a/.agents/skills/explore-unknowns/references/stage-5-hand-over-the-map.md b/.agents/skills/explore-unknowns/references/stage-5-hand-over-the-map.md
index 02f520e..1bd93ae 100644
--- a/.agents/skills/explore-unknowns/references/stage-5-hand-over-the-map.md
+++ b/.agents/skills/explore-unknowns/references/stage-5-hand-over-the-map.md
@@ -9,8 +9,10 @@ One self-contained page holding all four quadrants:
- **Known knowns** — the settled ground, with file citations.
- **Known unknowns** — the decision ledger: every named question with its
- answer and who closed it (user / territory / OPEN). OPEN items state what
- unblocks them.
+ answer and who closed it (user / territory / agent on the user's behalf /
+ OPEN). Agent answers retain the preference and reason behind each choice,
+ alongside the confirmed preference summary and delegation scope. OPEN
+ items state what unblocks them.
- **Unknown knowns** — what got extracted: taste, consumers, environment,
tacit conventions, and what each reshaped.
- **Unknown unknowns** — the landmine cards with evidence, each marked