@therocketcode/gsd-core 1.8.1 → 1.8.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "TheRocketCodeMX",

package/commands/gsd/discover-product.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:discover-product
 description: Optional product discovery — demand vs interest, the narrowest wedge, four risks, outcome-framed.
-argument-hint: "[--auto] [--text]"
+argument-hint: "[--auto] [--challenge [@doc ...]] [--text]"
 allowed-tools:
   - Read
   - Write
@@ -39,6 +39,7 @@ Define WHAT to build and WHY before building it — separating real demand from
 <context>
 **Flags:**
 - `--auto` — Skip the forcing interview; synthesize PRODUCT-BRIEF.md from any existing PROJECT.md / REQUIREMENTS.md using recommended defaults.
+- `--challenge [@doc ...]` — Existing specs/research/notes are upstream inputs: build a gap map (ANSWERED/WEAK/SILENT per block), confirm what the docs answer, challenge what's weak, interview only the gaps. Demand evidence and the user definition are always force-tested. The brief complements the docs and records proposed spec amendments.
 - `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions).
 
 **When to run:** when product value is uncertain (new market, no past-behavior evidence, demand asserted from a hypothetical, or a large/irreversible bet). **Skip** when a client/customer has explicit, evidenced requirements — then go straight to `/gsd:new-project` or lightweight prioritization. Runs standalone — does not require an existing project.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-core",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/gsd-core/references/product-discovery.md

@@ -19,7 +19,17 @@ Reference for `/gsd:discover-product`. An **optional** front-of-funnel step that
 
 ## The forcing posture
 
-The first answer is polished — push 2–3 times with concrete specifics, not soft exploration. "Name the *actual* human, the *actual* consequence." Reflect the answer back; confirm before moving on. One thread at a time.
+The first answer is polished — push 2–3 times with concrete specifics, not soft exploration. "Name the *actual* human, the *actual* consequence." Reflect the answer back; confirm before moving on. One *contested* thread at a time — but batch the rest: group already-evidenced reflect-backs and pair a confirmation with the next probe in the same turn. Batching cuts turns (~10–15 for a context-rich session), not rigor.
+
+## Challenge mode — when specs/research already exist
+
+Discovery recurs at every artifact maturity: nothing yet (greenfield) → meeting/levantamiento notes → research corpus → full design spec. One mechanism serves all of it — the **gap map**: classify each block of the question set against its named outputs as ANSWERED / WEAK / SILENT from the docs, confirm the ANSWERED, challenge the WEAK, interview the SILENT. Greenfield is simply the all-SILENT case.
+
+Two blocks are **never doc-answerable** (cap at WEAK however mature the docs):
+- **Demand evidence** — documents hold intentions and theses, not past behavior; the money-moved/usage record lives in people's heads and inboxes. A deep design process can run for weeks without ever surfacing the one paid consultation that validates the thesis — only the past-tense interview finds it.
+- **User definition** — specs smuggle the everyone-trap in writing (multi-stakeholder framings, personas-as-demographics). Re-test the documented user with the same pushback as a spoken claim.
+
+Challenge mode's brief **complements, never replaces** the upstream docs — and contradictions found must flow back as *proposed spec amendments* with explicit precedence, or the spec stays silently wrong while downstream agents read both.
 
 ## Distilled question set (ordered; skip a block only when its named outputs already exist at strong evidence — reflect the skipped conclusion back)
 
@@ -36,6 +46,7 @@ The first answer is polished — push 2–3 times with concrete specifics, not s
 - **Value uncertain** → run value-questioning (four risks, assumption tests, PMF).
 - **Value established / clear** → Impact-Effort or RICE, then build. (A low RICE *confidence* is itself a flag to return to discovery.)
 - **Overrides:** dependencies, table-stakes, and strategic bets legitimately beat the score — scoring just makes the trade-off explicit.
+- **RICE fits feature-list products.** When sequencing is strategy-driven (a milestone ladder, credibility-before-product), the ladder IS the prioritization — record the named override; don't force fake arithmetic onto a systems roadmap.
 
 ## Handoff
 

package/gsd-core/templates/product-brief.md

@@ -2,6 +2,7 @@
 
 **Created:** [DATE] via `/gsd:discover-product`
 **Scope:** Product definition (what/why) — feeds `PROJECT.md` and `/gsd:model-domain`. Outcome-framed so the domain and architecture stay open. **This brief is a hypothesis, not a verdict** — its open assumptions feed an ongoing discovery cadence (Torres), not a one-time gate.
+[Challenge mode: **This brief complements — does not replace — [upstream spec/docs paths]**. Where this brief is silent, the spec governs; on the amended points below, this brief governs until the spec is updated.]
 
 ## Outcome (not output)
 
@@ -56,6 +57,14 @@ State 2–3 as *direction + metric + object* so "is it working?" is answerable.
 - **Outcome metric + by when:** [the behavior/metric change and the date]
 - **PMF check (pre-registered):** [Sean Ellis criterion (≥40% "very disappointed") to survey once ≥N pilots used the core — planned measurement, not founder prediction]
 
+## Proposed spec amendments (challenge mode only — omit otherwise)
+
+Findings that contradict or materially extend the upstream docs. Apply them to the spec, or this brief governs on these points.
+
+| # | The spec says / omits | Discovery found | Recommended edit |
+|---|---|---|---|
+| 1 | [claim or silence] | [evidence-backed finding] | [the concrete spec change] |
+
 ## Handoff notes
 
 - **For `model-domain`:** [the job + journey steps and the key domain nouns/events to model]

package/gsd-core/workflows/discover-product.md

@@ -33,14 +33,15 @@ This skill is **front-of-funnel and standalone** — it does NOT require an exis
 
 ## Step 2: Optionality gate
 
-`/gsd:discover-product` is optional. Decide whether the full interview is warranted (`--auto` skips this gate and synthesizes from existing docs).
+`/gsd:discover-product` is optional. Decide whether the full interview is warranted (`--auto` skips this gate and synthesizes from existing docs; `--challenge` skips it too — straight to Step 2b).
 
-Use `AskUserQuestion` (header "Discovery"):
+**Honor an already-stated mode.** If `$ARGUMENTS` or the invocation itself already answers this gate (e.g. "--challenge", "challenge mode", "value is uncertain, run the full interview"), do NOT re-ask it — state the mode in one line ("Running in challenge mode against [docs] — gate answered by invocation") and route directly. Otherwise use `AskUserQuestion` (header "Discovery"):
 - question: "Is the product value already clear and **evidenced** (a client/customer asking for specific things, real usage data), or is value still uncertain?"
 - options:
   - "Value is uncertain — run discovery" (→ proceed to Step 3)
   - "Requirements are clear & evidenced" (→ Step 2a)
   - "Clear, but help me prioritize" (→ Step 2a, prioritization only)
+  - "Specs/research already exist — challenge them" (→ Step 2b)
 
 **Step 2a (clear/evidenced path):** First **audit the evidence** — two tests, BOTH must pass:
 1. **Strength:** the evidence is behavioral with *money moved or real usage* (a paying client, a live pilot), not *interest* (waitlists, likes, "people say it's great"). Signed non-binding LOIs are **medium** — never skip-qualifying alone.
@@ -51,22 +52,38 @@ If either fails, say so and route to the full interview — never honor "evidenc
 - Point them onward: "Requirements are clear — run `/gsd:new-project` to capture them, then `/gsd:model-domain`."
 Write a minimal PRODUCT-BRIEF.md (outcome + user + slice + the prioritized list + "discovery skipped: requirements pre-evidenced") and skip to Step 10. Exit early if they don't even want prioritization.
 
+## Step 2b: Challenge mode — build the gap map (`--challenge [@doc ...]`)
+
+For projects with existing definition artifacts (a design spec, research corpus, levantamiento notes, PRDs) at ANY maturity. The posture is **challenge and complement, never re-ask or restart**.
+
+1. **Read the upstream docs now** — every `@`-path passed with `--challenge`, plus `.planning/*.md` and an `ls docs/` scan for obvious spec/research files (confirm ambiguous ones with the user; don't ingest wholesale — that's `/gsd:ingest-docs`).
+2. **Build the gap map**: classify each discovery block against its named outputs (the same skip criteria as Step 3–9): **ANSWERED** (the named outputs exist in the docs, evidenced), **WEAK** (addressed but vague, unevidenced, or contradictory), or **SILENT** (not addressed). Blocks: frame/outcome · user+job · demand evidence · wedge · four risks/assumptions · scope · success metric.
+3. **Two blocks are never doc-answerable — cap them at WEAK regardless of what the docs assert:**
+   - **Demand evidence**: specs contain intentions and theses, not past behavior. Only *recorded past behavior with named actors* (who paid, who used, when) counts as ANSWERED — and that almost always lives in people's heads, not documents. Interview it.
+   - **User definition**: re-test it, don't inherit it — specs routinely smuggle the everyone-trap in writing (multi-user framings, "platforms", personas-as-demographics). Apply Step 4's pushback to the *documented* user as if the user had just said it.
+4. **Present the gap map** in one message ("the spec answers X and Y; W is weak — I'll challenge it; Z is silent — I'll interview it") and proceed: ANSWERED blocks → reflect the doc's conclusion back for confirmation (batched, no re-asking); WEAK → challenge with the block's forcing questions; SILENT → full interview for that block. Then continue at Step 3–9 covering only WEAK + SILENT.
+5. **Track contradictions**: whenever the interview contradicts or materially extends the upstream docs, record it — these become the brief's **Proposed spec amendments** (Step 10). A challenge that wins the argument but loses the record is worthless: downstream agents read both documents.
+
+Greenfield is the degenerate case (everything SILENT → the full interview); a mature spec is the other end (mostly ANSWERED → a confirmation pass + the two never-inherited blocks). The posture is derived from the gap map, never chosen by feel.
+
 ## Step 3–9: The forcing interview
 
-Run the ordered question set from the reference. **Posture: the first answer is polished — push 2–3 times for concrete specifics (the actual human, the actual consequence), reflect back, confirm. One thread at a time.** Ask about the PAST, never hypotheticals. Skip a block ONLY when its named outputs are already captured at **strong** evidence — Step 4: specific user + job story + measurable outcomes; Step 5: signals marked strong/medium/weak; Step 6: wedge + >1-solution check; Step 9: dated outcome metric — and reflect the skipped block's conclusion back for confirmation before moving on.
+Run the ordered question set from the reference. **Posture: the first answer is polished — push 2–3 times for concrete specifics (the actual human, the actual consequence), reflect back, confirm. One contested thread at a time — but batch the rest:** reflect already-evidenced conclusions back in groups and combine a reflection with the next probe in one turn (a context-rich session should take ~10–15 turns, not ~30; batching cuts turns, not rigor). Ask about the PAST, never hypotheticals. Skip a block ONLY when its named outputs are already captured at **strong** evidence — Step 4: specific user + job story + measurable outcomes; Step 5: signals marked strong/medium/weak; Step 6: wedge + >1-solution check; Step 9: dated outcome metric — and reflect the skipped block's conclusion back for confirmation before moving on.
 
 - **Step 3 — Frame (outcome):** "What customer behavior or metric do we want to change — not a feature?" (The betting-the-build assumption is covered in Step 7 — don't ask it here.)
 - **Step 4 — Job & user:** "Who *specifically* — and for whom is this most acute, frequent, expensive, unavoidable?" Capture the solution-free job and a job story ("When … I want to … so I can …"). Then capture **2–3 measurable desired outcomes** for the job as *direction + metric + object* ("reduce the time to find an open class slot") — these are what "better" is measured against later. If the job-population is heterogeneous, capture outcomes **per segment** (different segments want different things — don't average them away). If after 2–3 pushes the user still can't name a specific acute role (answers "everyone"/"all X"), do NOT record a generic user — record the target user as **UNRESOLVED** and make "identify the acute user" the first open question. A non-specific user is a discovery red flag, not a finding.
 - **Step 5 — Demand vs interest:** "Tell me about the *last time* you hit this." "What are you doing about it *today*, and what does it cost?" "What do they use today instead — including spreadsheets or nothing — and why hasn't it won?" "What *real* evidence exists — pre-pay, pilot in use, converted signups, signed LOIs?" Mark each signal **strong** (money moved / real usage / panic-when-it-breaks), **medium** (signed LOIs/unpaid pilots — real but not yet demand; convert to strong or treat as open), or **weak** (interest — waitlists, likes, "great idea"). **Never** ask hypotheticals — neither "would you use X?" nor "would you pay $Y?"; redirect any "they'd pay $Y" answer to "tell me about the last time someone actually paid for a workaround."
 - **Step 6 — Wedge:** "Which single opportunity, solved, most moves the outcome? What's the narrowest version that fully solves it for one user this week?" Check: can we imagine >1 solution? (If no, we smuggled in a solution — re-frame.)
 - **Step 7 — Four risks** (only the unvalidated): value / usability / feasibility / viability. First **enumerate the leap-of-faith assumptions** behind the chosen wedge (what must be true for it to work), order them by risk, and **specify** the cheapest test for the *riskiest* — record it in the brief with pass/fail threshold, kill criterion, owner, and by-when (tests run *after* this session, before building) — not just one test on the least-validated risk. Do not rely on the user's self-rating — if a risk is dismissed without evidence ("it's fine," "AI can do it"), treat it as **open**. **Value is never "validated" on founder testimony alone** — it requires customer-sourced evidence (a named customer's behavior, quote, or money). Independently name any obvious risk the user omitted (e.g., legal/consent, data privacy, platform dependency) and mark it open with a test. Record the surviving assumptions in the brief's "Assumptions to re-test" table — the brief is a hypothesis to keep testing, not a verdict.
-- **Step 8 — Scope & prioritization:** the end-to-end journey → the thin first slice; RICE the candidate list; record explicit "not in scope."
+- **Step 8 — Scope & prioritization:** the end-to-end journey → the thin first slice; RICE the candidate list; record explicit "not in scope." **RICE fits feature-list products.** When sequencing is strategy-driven (a milestone ladder, credibility-before-product, infrastructure-before-features), the ladder IS the prioritization — record it as a named strategic override and skip the arithmetic rather than forcing fake scores.
 - **Step 9 — Success:** the **outcome metric** (a change in customer behavior or business result) + by when; the PMF check, **pre-registered**: define now the Sean Ellis criterion (≥40% "very disappointed") to survey once ≥N pilots have used the core (only users who used it) — a *planned measurement*, never a founder prediction. **Reject vanity/output metrics — signups, waitlist size, downloads, page views, "launched" — and push to the behavior/result they proxy for (retained paying users, task completion, % of the target behavior achieved). A user-count is an output unless tied to retained value.**
 
 ## Step 10: Write PRODUCT-BRIEF.md
 
 Render `@~/.claude/gsd-core/templates/product-brief.md` (fill `[DATE]` with today's date, `[PROJECT_TITLE]` from PROJECT.md or — if none exists — a short **outcome-level** working title that does NOT encode the solution, marked "(working title)"). Keep the outcome at the behavior/metric level — **do not encode a solution or architecture**. Fill the **measurable desired-outcomes** table (per segment if heterogeneous), the **Assumptions to re-test** table (riskiest first, each with its cheapest next test), and the Handoff notes for `model-domain` (the job + journey + key domain nouns).
 
+**Challenge mode additions:** set the Scope line to the complement form ("complements — does not replace — [spec path]; where this brief is silent, the spec governs; on the amended points below, this brief governs until the spec is updated") and fill the **Proposed spec amendments** section from the contradictions tracked in Step 2b (each: what the spec said / what discovery found / the recommended edit). Offer to apply the amendments to the upstream doc now or leave them for the owner.
+
 Write to `.planning/PRODUCT-BRIEF.md`.
 
 ## Step 11: Commit
@@ -89,6 +106,7 @@ PRODUCT-BRIEF.md written — product defined.
   Wedge: [the narrowest paid slice]
   Demand: [strong | medium | weak — based on past-behavior evidence]
   Four risks: [N validated · M open]
+  Spec amendments: [N proposed — apply to [spec] or it stays governing]   (challenge mode only)
 
 Next: /gsd:new-project (capture it) → /gsd:model-domain (the domain) → /gsd:recommend-architecture
 ```
@@ -97,6 +115,8 @@ Next: /gsd:new-project (capture it) → /gsd:model-domain (the domain) → /gsd:
 
 <critical_rules>
 - **Optional and lightweight when evidenced.** If requirements are already clear/evidenced, do NOT run the full interview — prioritize and move on.
+- **Challenge, never restart.** With existing specs/research (`--challenge`), the gap map decides what gets interviewed; ANSWERED blocks are confirmed, not re-asked. But demand evidence and the user definition are NEVER inherited from documents — they cap at WEAK and get the forcing treatment.
+- **Contradictions flow back.** In challenge mode, every interview finding that contradicts the upstream docs lands in "Proposed spec amendments" with explicit precedence — never leave the spec silently wrong.
 - **Demand, not interest.** Ask about past behavior, money, and "panic when it breaks" — never hypotheticals ("would you use X?").
 - **Outcome-framed.** The vision is a behavior/metric to change and must admit more than one solution — never encode a specific solution or architecture here (that's later phases).
 - **Forcing posture.** Push past the first polished answer 2–3 times for concrete specifics; reflect back and confirm.
@@ -104,7 +124,8 @@ Next: /gsd:new-project (capture it) → /gsd:model-domain (the domain) → /gsd:
 </critical_rules>
 
 <success_criteria>
-- Optionality gate applied (skipped/lightweight path when requirements are evidenced)
+- Optionality gate applied (skipped/lightweight path when requirements are evidenced; honored without re-asking when the invocation states the mode)
+- In challenge mode: gap map built and presented; demand evidence + user definition force-tested regardless of docs; contradictions recorded as proposed spec amendments with precedence
 - Outcome framed as a behavior/metric, not a feature
 - Specific user + solution-free job + job story captured
 - Demand separated from interest via past-behavior evidence

package/gsd-core/workflows/help/modes/full.md

@@ -572,7 +572,7 @@ The commands above cover the most common day-to-day flows. Every command listed
 ### Discovery & Specification
 
 - **`/gsd:explore`** — Socratic ideation and idea routing. Think through ideas before committing to plans.
-- **`/gsd:discover-product [--auto] [--text]`** — Optional product discovery: demand vs interest, the narrowest wedge, four risks, outcome-framed; writes PRODUCT-BRIEF.md.
+- **`/gsd:discover-product [--auto] [--challenge [@doc ...]] [--text]`** — Optional product discovery: demand vs interest, the narrowest wedge, four risks, outcome-framed; `--challenge` audits existing specs/research via a gap map instead of re-asking; writes PRODUCT-BRIEF.md.
 - **`/gsd:spec-phase <phase> [--auto] [--text]`** — Clarify WHAT a phase delivers with ambiguity scoring; produces a SPEC.md before discuss-phase.
 - **`/gsd:model-domain [--auto] [--text] [--event-storming]`** — Capture ubiquitous language and classify subdomains (core/supporting/generic) for greenfield projects; strategic DDD before architecture.
 - **`/gsd:recommend-architecture [--auto] [--text]`** — Recommend an architecture matched to domain complexity and NFRs (two-axis) and capture it as an ADR; avoids over/under-engineering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@therocketcode/gsd-core",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "bin": {
     "gsd-core": "bin/install.js",