docs: add onboarding design guideline (goal-over-role framing) - #2066
Open
kasiazjc wants to merge 4 commits into
Open
docs: add onboarding design guideline (goal-over-role framing)#2066kasiazjc wants to merge 4 commits into
kasiazjc wants to merge 4 commits into
Conversation
Capture the decision to reframe the onboarding wizard's first question around goals/outcomes instead of roles/personas, plus the locked goal cards, composable-block rec mechanism, brand-voice rules, and the known connector gap. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- MCP-rec merge: replace ambiguous "union, dedup, cap at 4" with an ordered 4-slot rule (2 primary, 2 secondary, dedup, refill from primary) since the union routinely exceeds 4. - Bootstrap merge: the user already picked both goals, so lead with a concrete action on the primary goal instead of reopening with "which matters more" — surface the secondary only after the first win. Aligns with the "prove value fast, conversation-driven" onboarding thesis and a recorded tester complaint. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Max decided the product noun is "teammate", not "assistant". Update card 1's title from "Finally, a personal assistant" to "Finally, a personal teammate", turn the flagged open naming question into a resolved note, and adjust the locked-copy framing + review checklist to match. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Data model: new preferences.onboarding.goals: string[] for redesigned completions; leave legacy persona string untouched (no clean mapping, read once at completion so absent value is harmless). - Order: selection state must be an order-preserving array (append/splice), not a Set, so first-picked = primary holds. - Step label: change the badge from "You" to "Goals". - Skip path: 0-goal selection falls back to a generic default block (PERSONA_MCP_RECS['_default'] spirit); 0/1/2-goal cases now all covered. - Propagate the resolved "teammate" rename to the reference table and known-gap section, and add matching review-checklist items. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context / Problem
Agor's onboarding wizard (shipped in #1609) opens with a persona step: four role-based cards (Developer / PM / Lead / Solo builder) that single-select into a hardcoded
PERSONA_MCP_RECSmap and the first teammate's bootstrap prompt.The product owner has decided (pending final stakeholder review) this framing is wrong:
That decision currently lives only in scattered chat and KB docs, so any future implementation PR would have to re-derive it.
Goal
Pin the decision as house style so a future implementation PR (not this one) has one fixed reference before touching the wizard. This is docs-only — no wizard/persona code is touched.
The new guideline covers:
Changes
context/guidelines/onboarding-design.md.context/README.mdunderguidelines/.🤖 Generated with Claude Code