@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/commands/challenge-me/vision.md

@@ -0,0 +1,354 @@
+---
+model_tier: inherit
+name: challenge-me-vision
+pack: meta
+tier: 2
+cluster: challenge-me
+sub: vision
+description: "Stress-test a plan or idea by one-question-at-a-time interview until 95% confidence — emits a copyable Markdown vision pitch for tickets, roadmaps, or fresh-chat handoff."
+suggestion:
+  eligible: true
+  trigger_description: "challenge me on this plan, grill me, grill me on this, grill me on the vision, grill me on the idea, grill me until it's clear, grill me hard, frag mich durch, dreh mich durch die Mangel"
+  trigger_context: "user has a fuzzy plan/idea/feature draft and wants it sharpened interactively rather than reconstructed in one shot"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /challenge-me vision
+
+> Walk a decision tree by asking one question at a time, each with a
+> recommended answer, until the agent reaches **95% confidence** in what
+> the user actually wants — then emit a copyable Markdown pitch the user
+> can paste into a ticket, roadmap, or fresh-chat handoff.
+
+## Welcome
+
+If the user invokes `/challenge-me vision` (or `/challenge-me` defaulting
+here) with no body, render once:
+
+```
+Drop the seed — a plan, idea, ticket draft, or design sketch — and I'll
+walk you through a decision tree, one question per turn, until I'm 95%
+sure what you want. Then you get a copyable Markdown pitch.
+
+Stop early any time by typing `!pitch` (or `!Vision pitchen`).
+```
+
+Skip the welcome if the user invokes `/challenge-me vision <seed>` directly.
+
+## When NOT to use
+
+| Phrasing | Route to |
+|---|---|
+| "refine this prompt before /work" | [`/refine-prompt`](../refine-prompt.md) |
+| "refine this Jira ticket" | [`/refine-ticket`](../refine-ticket.md) |
+| "poke holes in my plan" (one-shot, no Q&A) | `adversarial-review` skill |
+| "ask another model" | `ai-council` skill |
+| "challenge me against existing docs/glossary" | `/challenge-me with-docs` |
+
+## Default stop condition — 95% confidence
+
+Unless the user names a different stop condition (`--until=N`,
+`--keep-going`, or natural-language equivalents like `"5 questions"` /
+`"keep going forever"`), the default is:
+
+```
+KEEP ASKING UNTIL CONFIDENCE ≥ 95% OR THE USER PITCHES.
+```
+
+### What "load-bearing" means
+
+A branch is **load-bearing** when its answer would change at least one of:
+
+- the **goal** sentence,
+- the **in-scope / out-of-scope** boundary,
+- a **hard constraint**, or
+- one of the **acceptance criteria**.
+
+A branch that only changes wording, tone, or cosmetics is **not**
+load-bearing — close it without asking. This is the same test for the
+"why it matters" line in every question block (see Step 1).
+
+**Examples — load-bearing vs cosmetic:**
+
+| Question | Load-bearing? | Why |
+|---|---|---|
+| "Should anonymous users see this page?" | yes | flips an AC + scope boundary |
+| "Soft-delete or hard-delete on cancel?" | yes | flips a hard constraint + rollback path |
+| "Should the button be primary or secondary colour?" | no | wording / cosmetic, no AC change |
+| "Should we name the column `cancelled_at` or `canceled_at`?" | no | naming, no behaviour change |
+
+### What "branch" means (for Condition 2)
+
+A **branch** = an entry in the agent's internal working list of open
+dimensions (Step 0.3 in the procedure). A branch is **new** when the
+agent's last applied answer would, on a re-evaluation of dimensions,
+add at least one entry that passes the load-bearing test above. A
+branch that only refines an existing entry's text without flipping
+goal / scope / constraint / AC is **not** new.
+
+### The four 95% conditions (AND, not OR)
+
+Confidence reaches 95% when **all four** hold simultaneously:
+
+1. Every load-bearing branch surfaced so far has a resolved answer
+   (recommendation accepted, alternative picked, explicitly skipped).
+2. The agent re-evaluated its internal working list (Step 0.3) after
+   applying the user's last answer, and **no new load-bearing branch**
+   (passing the load-bearing test above) was added.
+3. Goal, in-scope, out-of-scope, hard constraints, success criteria, and
+   **at least two edge cases that affect AC observability or rollback**
+   all have explicit answers (not "TBD", not "probably", not "we'll see").
+4. The agent has **cached a draft pitch** (Goal + In/Out + Constraints +
+   AC) at the end of every turn, and the user's **last two answers** did
+   not modify any of those four sections.
+
+Condition 4 is observable, not introspective: the agent maintains the
+draft pitch as state, diffs it against the previous turn's draft, and
+declares stable only when two consecutive turns produce identical
+sections.
+
+When all four hold, the agent does **not** ask another question — it goes
+straight to Step 4.
+
+## Flags
+
+- `--until=95%` (default) — stop when the four 95% conditions hold.
+- `--until=N` — stop after N answered questions, even if confidence is
+  lower. Emit the pitch with an `Open assumptions` block listing what
+  is still fuzzy.
+- `--keep-going` — never auto-stop; only the user's pitch trigger ends
+  the interview.
+
+## Steps
+
+### Step 0: Inspect (codebase first, ALWAYS)
+
+```
+EXPLORE THE CODEBASE BEFORE THE FIRST QUESTION.
+NEVER ASK WHAT `grep`, `view`, OR `codebase-retrieval` ANSWERS IN SECONDS.
+```
+
+1. **Read the seed.** The user's first message (or
+   `/challenge-me vision <seed>` body) is the artefact under examination —
+   a plan, idea, ticket draft, design sketch.
+2. **Look up before asking.** Existing routes, model fields, conventions,
+   feature flags, previous similar features → resolve from the repo.
+   Surface findings briefly in the next question block ("Repo says X
+   already exists at `path/to/file.php`"). The user should never have to
+   answer a question the codebase already answers.
+3. **List the open dimensions** internally — goal, scope, users, data,
+   constraints, success criteria, edge cases, rollback. Do not surface
+   this list; it is the agent's todo, not the user's.
+
+### Step 1: Ask one question per turn
+
+Every turn after Step 0 emits exactly **one** question block. Before
+writing the block, validate the question against the load-bearing test:
+**if the answer cannot change goal / scope / hard constraints / AC, do
+not ask** — close the branch and move to the next.
+
+````markdown
+**Question N · confidence ~XX%**
+
+<one-sentence question, anchored to a specific decision>
+
+**Why it matters:** <one line — which AC, scope boundary, or hard
+constraint this unblocks>.
+
+1. **<recommended option>** — recommended because <one line>.
+2. <alternative option>
+3. <alternative option>
+4. Skip / not relevant
+
+> Reply with a number, a free-form answer, or type **`!pitch`**
+> (or **`!Vision pitchen`**) to lock in the current understanding and
+> get the Markdown pitch.
+````
+
+**Rules for the question block.**
+
+- One question per turn — non-negotiable, per
+  [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) Iron Law.
+- The recommended option is always **option 1** and labelled **bold**.
+- 3–4 options total. More than 4 means the question is too broad — split it.
+- "Skip / not relevant" must always be present so the user can prune dead
+  branches.
+- Walk the tree depth-first: resolve a branch's children before moving
+  to the next sibling, unless the user explicitly jumps.
+- The `Why it matters` line MUST cite an AC number, a scope boundary, or
+  a named hard constraint. "Good to know" / "for context" / "to be safe"
+  are placeholders — rewrite or drop the question.
+
+### Step 2: Apply the answer
+
+1. Number reply (`1`, `2`, …) → adopt that option.
+2. Free-form reply → integrate verbatim, do not re-interpret.
+3. "Skip" / "skip" / "n/a" → branch closed, do not revisit unless reopened.
+4. Pitch trigger fired → jump straight to Step 4, even if confidence < 95%.
+
+#### Pitch trigger — strict matching
+
+The pitch trigger requires **explicit syntax** to avoid false positives
+on natural sentences like "I'd pitch this to the team".
+
+| Match | Example | Fires? |
+|---|---|---|
+| `!pitch` (or any `!`-prefixed variant) at line start | `!pitch`, `!Vision pitchen`, `!pitch it` | yes |
+| `/pitch` at line start | `/pitch` | yes |
+| Whole reply is exactly `pitch` (case-insensitive, no other words) | `pitch` | yes |
+| `pitch` inside a sentence | "I would pitch this on Monday" | **no** |
+| `pitch mich` / `ship vision` inside prose | natural-language fragment | **no** |
+
+`DE: "!Vision pitchen", "/Vision pitchen", "/pitche das", whole reply "pitch" · EN: "!pitch the vision", "/pitch the vision", whole reply "pitch"`
+
+If the agent is unsure whether the user pitched, it confirms once
+(numbered options: `1. emit pitch · 2. continue interview`) instead of
+guessing.
+
+### Step 3: Re-score and continue
+
+Re-evaluate the four 95%-conditions internally. If not yet reached, ask
+the next question. If reached, go to Step 4 without asking.
+
+### Step 4: Validate before pitching
+
+Before emitting the pitch, run this checklist internally:
+
+1. All four 95%-conditions hold (or the user fired the pitch trigger).
+2. Every adopted answer is reflected in the pitch — no orphan branches.
+3. Acceptance criteria are observable and testable in the project's
+   existing test surface — not "works correctly" / "looks better".
+4. The recommended next-step command actually exists in this project.
+
+If any check fails, ask one more question instead of pitching.
+
+### Step 5: Emit the pitch
+
+Output a single fenced Markdown block the user can copy verbatim. Shape:
+
+````markdown
+```markdown
+# <one-line vision title>
+
+**Goal:** <verb + object + observable result>
+
+**In scope:**
+- <bullet>
+- <bullet>
+
+**Out of scope:**
+- <bullet>
+
+**Constraints (hard):**
+- <bullet>
+
+**Acceptance criteria:**
+1. <observable, testable>
+2. <observable, testable>
+3. <observable, testable>
+
+**Open assumptions:**
+- assumes: <line>
+
+**Recommended next step:** <one sentence — e.g. "/work \"<pitch goal>\"" or
+"create roadmap with /roadmap-create">.
+```
+````
+
+The outer fence uses four backticks so the inner triple-backtick stays
+literal when the user copies it.
+
+### Step 6: Hand back
+
+After the pitch is emitted, end the turn. Do **not** propose to also
+implement the pitch, write it to a roadmap, or commit anything — the
+pitch is conversational output the user copies into the next command
+(`/work`, `/roadmap-create`, `/feature-plan`, …).
+
+If the user wants the next step run, they invoke it explicitly.
+
+## Output format
+
+1. **Per-turn question block** — one numbered question with a recommended
+   option, until 95% or pitch trigger.
+2. **Final pitch** — a single copyable fenced Markdown block (Step 5 shape).
+3. **One-line handoff suggestion** under the pitch — which command to run
+   next (`/work`, `/roadmap-create`, `/feature-plan`, etc.).
+
+## Examples
+
+```
+/challenge-me vision
+/challenge-me vision We need a shareable read-only view for non-paying users
+/challenge-me vision --until=5 Build a CSV export for the dashboard
+/challenge-me vision --keep-going Re-architect the notifications pipeline
+```
+
+## Gotchas
+
+- The model wants to ask *the user* what the codebase already answers
+  (existing routes, conventions, model fields). Run the lookup first;
+  only ask when the codebase is silent.
+- Confidence inflation — the model marks itself 95% after 2 questions
+  because the user nodded along. The four conditions are AND, not OR.
+  Recheck **all four** every turn before stopping.
+- Recommendation drift — the agent keeps changing option 1 across turns
+  because new context arrived. That is fine *within* the interview; it
+  is a red flag *at pitch time*. If the pitch shape changed in the last
+  turn, ask one more question.
+- Stacked questions — the model bundles "scope and rollback?" into one
+  block. Split. Always one decision per question.
+- Too many options — 7-option blocks are not a tree, they are a survey.
+  Cap at 4; split the question if 4 is not enough.
+
+## Rules
+
+- **One question per turn** — non-negotiable, per
+  [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) Iron Law.
+- **No auto-execution** — emit the pitch, not the implementation it
+  describes. Do not chain into `/work` or `/roadmap-create` without
+  explicit user invocation.
+- **No file writes** — the pitch is conversational. No commits, no
+  roadmap edits, no `agents/` writes.
+- **Codebase first** — Step 0 forbids asking what `grep`, `view`, or
+  `codebase-retrieval` would answer in seconds.
+- **Welcome once** — render the welcome only on the first no-body
+  invocation per session.
+- **Mirror the user's language** — the question blocks and pitch use
+  the language the user wrote in (`language-and-tone` Iron Law). The
+  pitch trigger syntax (`!pitch`, `/pitch`, whole reply `pitch`) stays
+  literal in any language.
+
+## Do NOT
+
+- Do NOT ask multiple questions in one turn.
+- Do NOT proceed past 95% without emitting the pitch — silent inflation
+  defeats the contract.
+- Do NOT paraphrase the user's free-form answers when applying them.
+  Verbatim or summarised-with-quote, never re-worded.
+- Do NOT include implementation steps in the pitch. The pitch is intent
+  + acceptance criteria; implementation is the next command's job.
+- Do NOT skip the "skip / not relevant" option — pruning is part of the
+  tree.
+- Do NOT re-emit the full pitch every turn. Pitch only fires at 95% or
+  on explicit trigger.
+
+## See also
+
+- [`/challenge-me with-docs`](with-docs.md) — sibling variant that adds
+  glossary / `CONTEXT.md` awareness and load-bearing claim-vs-code
+  verification.
+- [`/refine-prompt`](../refine-prompt.md) — one-shot prompt scoring before
+  `/work`.
+- [`/refine-ticket`](../refine-ticket.md) — ticket reconstruction.
+- [`/optimize-prompt`](../optimize-prompt.md) — sibling pattern (interactive
+  polishing).
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — the
+  one-question-per-turn Iron Law this command is built on.
+- Inspiration: `mattpocock/skills/skills/productivity/grill-me/SKILL.md`
+  — same spirit (relentless decision-tree interview, one question at a
+  time, recommended answer per question), restructured to our command
+  shape with explicit stop heuristic and copyable pitch contract.

package/dist/agent-src/commands/challenge-me/with-docs.md

@@ -0,0 +1,339 @@
+---
+model_tier: medium
+name: challenge-me-with-docs
+pack: meta
+tier: 2
+cluster: challenge-me
+sub: with-docs
+description: "Doc-aware /challenge-me — 95%-confidence interview with session glossary vs CONTEXT.md, load-bearing claim-vs-code verification, optional CONTEXT.md patch + ADR candidates in the pitch."
+suggestion:
+  eligible: true
+  trigger_description: "challenge me against the docs, grill me with our context, grill me against the docs, grill me against CONTEXT.md, grill me with the project context, frag mich durch und prüf gegen CONTEXT.md, challenge plan with domain docs"
+  trigger_context: "user wants the seed challenged against existing project glossary, CONTEXT.md, or ADRs — not a greenfield interview"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /challenge-me with-docs
+
+> Same one-question-at-a-time interview as `/challenge-me vision`, plus:
+> a **session glossary** against `CONTEXT.md`, **load-bearing claim-vs-code
+> verification**, and an optional `CONTEXT.md` **patch** + **ADR candidates**
+> appended to the final pitch. Nothing is written to disk — the pitch is
+> the only artefact.
+
+## Welcome
+
+If the user invokes `/challenge-me with-docs` with no body, render once:
+
+```
+Drop the seed and I'll grill it against your project docs. Per turn:
+one question, recommended answer. I'll surface glossary clashes vs
+CONTEXT.md and verify load-bearing claims against the code. At the end
+you get a pitch — plus an optional CONTEXT.md patch and ADR candidates
+to copy / apply yourself.
+
+Stop early any time by typing `!pitch` (or `!Vision pitchen`).
+```
+
+Skip the welcome if the user invokes `/challenge-me with-docs <seed>`
+directly.
+
+## When to use this instead of `vision`
+
+| Condition | Pick |
+|---|---|
+| Project has no `CONTEXT.md` and no ADR dir | `vision` |
+| Seed uses domain terms that may already be defined elsewhere | `with-docs` |
+| User says "check against our docs" / "make sure it matches CONTEXT.md" | `with-docs` |
+| User says "make sure this is consistent with the codebase" | `with-docs` |
+| Greenfield brainstorm, no existing constraints to honour | `vision` |
+
+If neither file exists and the user invoked `with-docs` anyway, fall
+back gracefully to `vision`-style flow and skip the doc inventory; note
+the absence in a single line at the end of Step 0.
+
+## Stop condition, flags, pitch trigger
+
+Inherits **verbatim** from [`vision.md`](vision.md):
+
+- Default stop = the four 95%-conditions (AND, not OR).
+- Load-bearing test = answer changes goal / scope / hard constraint / AC.
+- `--until=95%` (default) · `--until=N` · `--keep-going`.
+- Pitch trigger: `!pitch`, `/pitch`, or whole reply `pitch`.
+- Step 1 question-block shape, Step 4 pitch validation.
+
+The deltas below replace / extend Step 0, Step 1, Step 2, Step 4 and
+Step 5. Steps 3 and 6 are unchanged.
+
+## Steps
+
+### Step 0 — Inspect (read-only doc inventory + codebase)
+
+```
+EXPLORE THE DOCS AND THE CODEBASE BEFORE THE FIRST QUESTION.
+NEVER WRITE TO DISK IN STEP 0. NEVER ASK WHAT view / grep / codebase-retrieval ANSWERS.
+```
+
+1. **Read the seed** (same as `vision`).
+2. **Doc inventory** — read-only:
+   - `view CONTEXT.md` if it exists; init empty **session glossary** in
+     agent state (in-memory only).
+   - `view CONTEXT-MAP.md` if it exists. If the seed touches > 1 listed
+     context, **ask once** (numbered options listing each context) which
+     to focus on; record the choice, do not re-ask.
+   - Autodetect ADR directory by listing `docs/adr/`, `docs/decisions/`,
+     `docs/architecture/decisions/`, `agents/decisions/`. Pick the
+     **most-recently-modified** non-empty dir; if none exist, default to
+     `docs/adr/` for the patch output (do **not** create the dir).
+   - If `agent state` already holds a session glossary from a prior
+     `/challenge-me with-docs` invocation **in this same chat**, load
+     it. Then re-read `CONTEXT.md` — any term in `CONTEXT.md` overrides
+     the session glossary (disk wins over draft). Emit a delta line if
+     non-zero: `Loaded N draft terms; CONTEXT.md already has X — carrying
+     forward the rest as drafts.`
+3. **Codebase lookup** — same as `vision` Step 0.2 (existing routes,
+   model fields, conventions, feature flags).
+4. **List the open dimensions** internally — same as `vision` Step 0.3.
+
+### Step 1 — Glossary-aware questioning
+
+Every question block runs an extra check **before** emit:
+
+- **Glossary conflict** — does the seed (or a prior turn) use a term
+  that conflicts with the existing `CONTEXT.md` glossary, including a
+  case-insensitive match? → first question of the session is the
+  glossary disambiguation:
+
+  > Your `CONTEXT.md` defines **Account** as the billing entity. Your
+  > seed uses "account" for the logged-in person. Which is it?
+  > 1. **Match CONTEXT.md** — rename "account" in the plan to "user".
+  > 2. Override CONTEXT.md — the plan introduces a new meaning; we patch
+  >    the glossary at pitch time.
+  > 3. Skip / not relevant.
+
+- **Fuzzy / overloaded term** — propose a canonical term as option 1.
+
+- **No glossary present** → skip the check; behave like `vision`.
+
+The glossary check is itself **load-bearing only when the term flips an
+AC or scope boundary OR when it conflicts with an existing CONTEXT.md
+entry**. Pure naming preference with no conflict is closed silently
+(same load-bearing test as `vision`, with the conflict-extension).
+
+Otherwise the question-block shape, recommended-option rule, 3–4 option
+cap, and `Why it matters` requirement are identical to
+[`vision.md § Step 1`](vision.md#step-1-ask-one-question-per-turn).
+
+### Step 2 — Apply the answer + session glossary (in-memory)
+
+Adopt-the-answer rules are identical to
+[`vision.md § Step 2`](vision.md#step-2-apply-the-answer).
+
+When a term is resolved, write to **session glossary** (agent state
+only). **Never write to disk in this step.** Every turn's reply ends
+with a compact echo block when the glossary is non-empty:
+
+```
+**Session glossary (draft, not yet written):**
+- **Cancellation** — refund + reversal, excludes disputes (turn 3)
+- **Account** — maps to `User` entity (turn 5)
+```
+
+After the **fifth** session-glossary turn, condense the echo to:
+
+```
+**Session glossary (draft):** N terms · M ADR candidates — see pitch for full list.
+```
+
+If the session glossary is empty, omit the echo block entirely.
+
+### Step 3 — Re-score and continue
+
+Identical to [`vision.md § Step 3`](vision.md#step-3-re-score-and-continue).
+
+### Step 3.5 — ADR candidate check (no write)
+
+After each branch closes, run the three-test on the resolution:
+
+1. **Hard-to-reverse** — would unwinding it require code or schema rollback?
+2. **Surprising-without-context** — would a future contributor read the
+   choice and ask "why this and not the obvious alternative?"
+3. **Result of a real trade-off** — were the rejected options realistic?
+
+If **all three** pass, append the candidate to an in-memory ADR-candidate
+list. Do **not** ask, do **not** write. Surfaces only in Step 5.
+
+### Step 4 — Validate before pitching
+
+Identical to [`vision.md § Step 4`](vision.md#step-4-validate-before-pitching),
+plus:
+
+- Pitch uses the **canonical glossary spelling** for every term in the
+  session glossary.
+- The `CONTEXT.md` patch block is **always** appended when the session
+  glossary is non-empty — agent has no signal whether the user already
+  applied a previous patch in-chat. The patch block carries a header
+  the user reads before applying (see Step 5).
+
+### Step 5 — Emit the pitch with optional doc patches
+
+Emit the same fenced Markdown pitch as `vision`, then append up to two
+optional sections **inside** the same outer four-backtick fence:
+
+`````markdown
+````markdown
+# <one-line vision title>
+
+**Goal:** <verb + object + observable result>
+
+**In scope:**
+- <bullet>
+
+**Out of scope:**
+- <bullet>
+
+**Constraints (hard):**
+- <bullet>
+
+**Acceptance criteria:**
+1. <observable, testable>
+
+**Open assumptions:**
+- assumes: <line>
+
+**Recommended next step:** <one sentence — e.g. "/work \"<pitch goal>\"" >.
+
+---
+
+**CONTEXT.md patch (apply via `patch -p1` or your IDE's Apply Patch — only
+if you haven't already merged these terms):**
+
+```diff
+@@ ... @@
++ ## Cancellation
++ Refund + reversal, excludes disputes.
+```
+
+**ADR candidate(s) — apply only if useful:**
+- `docs/adr/0007-cancellation-semantics.md` — captures the soft-vs-hard
+  delete decision (hard-to-reverse · surprising · real-tradeoff).
+
+**Glossary touched this session:** Cancellation, Account, Refund (3 terms).
+````
+`````
+
+The outer fence uses **five backticks** so the inner four-backtick fence
+(which itself contains a triple-backtick diff) stays literal when the
+user copies the whole block.
+
+Omission rules:
+
+- Session glossary empty → omit the `CONTEXT.md patch`, `Glossary touched`,
+  and the preceding `---` separator entirely.
+- No ADR candidate qualified → omit the `ADR candidate(s)` section.
+- Both empty → pitch is identical to a `vision` pitch.
+
+### Step 6 — Hand back
+
+Identical to [`vision.md § Step 6`](vision.md#step-6-hand-back). Never
+auto-write the patches, never auto-invoke `/work`.
+
+## Code-vs-claim guard (gated)
+
+When the user states "X is implemented as Y" AND the claim is
+**load-bearing** (would change an AC, scope boundary, or hard
+constraint), agent runs `view` / `grep` / `codebase-retrieval` to
+verify. Mismatch → single question block:
+
+> Your seed says X works via Y. The code (`path/to/file.php:123`) shows
+> it via Z. Which is right?
+> 1. **Code is right, my seed was wrong** — recommended.
+> 2. Seed is right, code is stale — separate fix needed.
+> 3. Both — they're both real paths.
+
+Non-load-bearing claims (cosmetic, naming, internal style) — agent
+trusts the user's statement, no lookup. This gate keeps verification
+cost O(load-bearing-decisions), not O(every-statement).
+
+## Output format
+
+1. **Per-turn question block** — one numbered question with a
+   recommended option, until 95% or pitch trigger.
+2. **Session-glossary echo** — appended every turn while the glossary is
+   non-empty (full list in turns 1–5, condensed line from turn 6 on).
+3. **Final pitch** — a single copyable five-backtick fenced block
+   (Step 5 shape) holding the standard pitch + optional `CONTEXT.md`
+   patch + optional ADR candidates.
+
+## Examples
+
+```
+/challenge-me with-docs
+/challenge-me with-docs Add a per-tenant rate limit on the public API
+/challenge-me with-docs --until=5 Migrate cancellations from soft-delete to hard-delete
+/challenge-me with-docs --keep-going Re-architect the notifications pipeline
+```
+
+## Gotchas
+
+- Inherits every gotcha from
+  [`vision.md § Gotchas`](vision.md#gotchas) — confidence inflation,
+  recommendation drift, stacked questions, too many options.
+- **Glossary clutter** — if the agent echoes the full session glossary
+  past turn 5 the reply gets noisy. Condense per Step 2.
+- **Patch redundancy** — agent has no signal whether the user already
+  applied a previous in-chat `CONTEXT.md` patch. Always emit the patch
+  with the "only if you haven't already merged these terms" header so
+  the user can dedupe.
+- **ADR over-eager** — the three-test (hard-to-reverse · surprising ·
+  real-tradeoff) is the gate. A pure naming choice or a default that
+  could flip without rollback is **not** an ADR candidate.
+- **Multi-context confusion** — if `CONTEXT-MAP.md` lists multiple
+  contexts and the seed touches several, ask **once** in Step 0; never
+  re-ask which context to focus on.
+
+## Rules
+
+- Inherits every rule from [`vision.md § Rules`](vision.md#rules) —
+  one question per turn, no auto-execution, no file writes, codebase
+  first, welcome once, mirror the user's language.
+- **No file writes** — even though this variant produces glossary
+  patches and ADR candidates, those go **into the pitch block** for the
+  user to apply. Agent never writes `CONTEXT.md` or any `docs/adr/*`
+  file itself, per `non-destructive-by-default`.
+- **Two-gate verification** — the glossary check fires on AC-flipping
+  terms OR `CONTEXT.md` conflicts; the code-vs-claim check fires only
+  on load-bearing claims. Non-load-bearing trivia → no lookup, no
+  question.
+- **Session glossary persists within a chat** — a second
+  `/challenge-me with-docs` invocation in the same chat inherits draft
+  terms; disk state (`CONTEXT.md`) overrides drafts on every Step 0.
+
+## Do NOT
+
+- Inherits every prohibition from
+  [`vision.md § Do NOT`](vision.md#do-not).
+- Do NOT write to `CONTEXT.md` directly — emit the diff in the pitch.
+- Do NOT create files in `docs/adr/` — emit the path + rationale in the
+  pitch and let the user create the file.
+- Do NOT verify every user statement — only load-bearing claims trigger
+  the code-vs-claim guard.
+- Do NOT echo the full session glossary past turn 5 — condense.
+
+## See also
+
+- [`/challenge-me vision`](vision.md) — sibling without doc inventory,
+  glossary check, or claim verification.
+- [`/refine-prompt`](../refine-prompt.md) — one-shot prompt scoring.
+- [`/refine-ticket`](../refine-ticket.md) — ticket reconstruction.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — the
+  one-question-per-turn Iron Law.
+- [`non-destructive-by-default`](../../rules/non-destructive-by-default.md)
+  — why the patches live in the pitch block, not on disk.
+- Inspiration: `mattpocock/skills/skills/engineering/grill-with-docs/SKILL.md`
+  — same intent (interview against domain docs), restructured to honour
+  the project's non-destructive floor (session glossary in-memory,
+  patches emitted as copyable diffs in the pitch).