feat(discuss-phase): adapt gray area language for non-technical owners via USER-PROFILE.md (#2125) (#2173)

When USER-PROFILE.md signals a non-technical product owner (learning_style: guided,
jargon in frustration_triggers, or high-level explanation_depth), discuss-phase now
reframes gray area labels and advisor_research rationale paragraphs in product-outcome
language. Same technical decisions, translated framing so product owners can participate
meaningfully without needing implementation vocabulary.

Closes #2125

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/FEATURES.md

@@ -201,6 +201,8 @@
 - REQ-DISC-05: System MUST support `--auto` flag to auto-select recommended defaults
 - REQ-DISC-06: System MUST support `--batch` flag for grouped question intake
 - REQ-DISC-07: System MUST scout relevant source files before identifying gray areas (code-aware discussion)
+- REQ-DISC-08: System MUST adapt gray area language to product-outcome terms when USER-PROFILE.md indicates a non-technical owner (learning_style: guided, jargon in frustration_triggers, or high-level explanation depth)
+- REQ-DISC-09: When REQ-DISC-08 applies, advisor_research rationale paragraphs MUST be rewritten in plain language — same decisions, translated framing
 
 **Produces:** `{padded_phase}-CONTEXT.md` — User preferences that feed into research and planning
 

docs/USER-GUIDE.md

@@ -831,6 +831,12 @@ Clear your context window between major commands: `/clear` in Claude Code. GSD i
 
 Run `/gsd-discuss-phase [N]` before planning. Most plan quality issues come from Claude making assumptions that `CONTEXT.md` would have prevented. You can also run `/gsd-list-phase-assumptions [N]` to see what Claude intends to do before committing to a plan.
 
+### Discuss-Phase Uses Technical Jargon I Don't Understand
+
+`/gsd-discuss-phase` adapts its language based on your `USER-PROFILE.md`. If the profile indicates a non-technical owner — `learning_style: guided`, `jargon` listed as a frustration trigger, or `explanation_depth: high-level` — gray area questions are automatically reframed in product-outcome language instead of implementation terminology.
+
+To enable this: run `/gsd-profile-user` to generate your profile. The profile is stored at `~/.claude/get-shit-done/USER-PROFILE.md` and is read automatically on every `/gsd-discuss-phase` invocation. No other configuration is required.
+
 ### Execution Fails or Produces Stubs
 
 Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.

get-shit-done/workflows/discuss-phase.md

@@ -461,6 +461,34 @@ Check if advisor mode should activate:
 
 If ADVISOR_MODE is false, skip all advisor-specific steps — workflow proceeds with existing conversational flow unchanged.
 
+**User Profile Language Detection:**
+
+Check USER-PROFILE.md for communication preferences that indicate a non-technical product owner:
+
+```bash
+PROFILE_CONTENT=$(cat "$HOME/.claude/get-shit-done/USER-PROFILE.md" 2>/dev/null || true)
+```
+
+Set NON_TECHNICAL_OWNER = true if ANY of the following are present in USER-PROFILE.md:
+- `learning_style: guided`
+- The word `jargon` appears in a `frustration_triggers` section
+- `explanation_depth: practical-detailed` (without a technical modifier)
+- `explanation_depth: high-level`
+
+NON_TECHNICAL_OWNER = false if USER-PROFILE.md does not exist or none of the above signals are present.
+
+When NON_TECHNICAL_OWNER is true, reframe gray area labels and descriptions in product-outcome language before presenting them to the user. Preserve the same underlying decision — only change the framing:
+- Technical implementation term → outcome the user will experience
+  - "Token architecture" → "Color system: which approach prevents the dark theme from flashing white on open"
+  - "CSS variable strategy" → "Theme colors: how your brand colors stay consistent in both light and dark mode"
+  - "Component API surface area" → "How the building blocks connect: how tightly coupled should these parts be"
+  - "Caching strategy: SWR vs React Query" → "Loading speed: should screens show saved data right away or wait for fresh data"
+- All decisions stay the same. Only the question language adapts.
+
+This reframing applies to:
+1. Gray area labels and descriptions in `present_gray_areas`
+2. Advisor research rationale rewrites in `advisor_research` synthesis
+
 **Output your analysis internally, then present to user.**
 
 Example analysis for "Post Feed" phase (with code and prior context):
@@ -590,6 +618,7 @@ After user selects gray areas in present_gray_areas, spawn parallel research age
       If agent returned too many, trim least viable. If too few, accept as-is.
    d. Rewrite rationale paragraph to weave in project context and ongoing discussion context that the agent did not have access to
    e. If agent returned only 1 option, convert from table format to direct recommendation: "Standard approach for {area}: {option}. {rationale}"
+   f. **If NON_TECHNICAL_OWNER is true:** After completing steps a–e, apply a plain language rewrite to the rationale paragraph. Replace implementation-level terms with outcome descriptions the user can reason about without technical context. The table option names may also be rewritten in plain language if they are implementation terms — the Recommendation column value and the table structure remain intact. Do not remove detail; translate it. Example: "SWR uses stale-while-revalidate to serve cached responses immediately" → "This approach shows you something right away, then quietly updates in the background — users see data instantly."
 
 4. Store synthesized tables for use in discuss_areas.