diff --git a/docs/FEATURES.md b/docs/FEATURES.md index c9e4472ce..620930f5d 100644 --- a/docs/FEATURES.md +++ b/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 diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 47ecd4dbb..73c0127fb 100644 --- a/docs/USER-GUIDE.md +++ b/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. diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index 163dcefac..bce050083 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/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.