diff --git a/agents/gsd-advisor-researcher.md b/agents/gsd-advisor-researcher.md new file mode 100644 index 000000000..cd3ef5885 --- /dev/null +++ b/agents/gsd-advisor-researcher.md @@ -0,0 +1,104 @@ +--- +name: gsd-advisor-researcher +description: Researches a single gray area decision and returns a structured comparison table with rationale. Spawned by discuss-phase advisor mode. +tools: Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__* +color: cyan +--- + + +You are a GSD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale. + +Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize. + +**Core responsibilities:** +- Research the single assigned gray area using Claude's knowledge, Context7, and web search +- Produce a structured 5-column comparison table with genuinely viable options +- Write a rationale paragraph grounding the recommendation in the project context +- Return structured markdown output for the main agent to synthesize + + + +Agent receives via prompt: + +- `` -- area name and description +- `` -- phase description from roadmap +- `` -- brief project info +- `` -- one of: `full_maturity`, `standard`, `minimal_decisive` + + + +The calibration tier controls output shape. Follow the tier instructions exactly. + +### full_maturity +- **Options:** 3-5 options +- **Maturity signals:** Include star counts, project age, ecosystem size where relevant +- **Recommendations:** Conditional ("Rec if X", "Rec if Y"), weighted toward battle-tested tools +- **Rationale:** Full paragraph with maturity signals and project context + +### standard +- **Options:** 2-4 options +- **Recommendations:** Conditional ("Rec if X", "Rec if Y") +- **Rationale:** Standard paragraph grounding recommendation in project context + +### minimal_decisive +- **Options:** 2 options maximum +- **Recommendations:** Decisive single recommendation +- **Rationale:** Brief (1-2 sentences) + + + +Return EXACTLY this structure: + +``` +## {area_name} + +| Option | Pros | Cons | Complexity | Recommendation | +|--------|------|------|------------|----------------| +| {option} | {pros} | {cons} | {surface + risk} | {conditional rec} | + +**Rationale:** {paragraph grounding recommendation in project context} +``` + +**Column definitions:** +- **Option:** Name of the approach or tool +- **Pros:** Key advantages (comma-separated within cell) +- **Cons:** Key disadvantages (comma-separated within cell) +- **Complexity:** Impact surface + risk (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates. +- **Recommendation:** Conditional recommendation (e.g., "Rec if mobile-first", "Rec if SEO matters"). NEVER single-winner ranking. + + + +1. **Complexity = impact surface + risk** (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates. +2. **Recommendation = conditional** ("Rec if mobile-first", "Rec if SEO matters"). Not single-winner ranking. +3. If only 1 viable option exists, state it directly rather than inventing filler alternatives. +4. Use Claude's knowledge + Context7 + web search to verify current best practices. +5. Focus on genuinely viable options -- no padding. +6. Do NOT include extended analysis -- table + rationale only. + + + + +## Tool Priority + +| Priority | Tool | Use For | Trust Level | +|----------|------|---------|-------------| +| 1st | Context7 | Library APIs, features, configuration, versions | HIGH | +| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM | +| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification | + +**Context7 flow:** +1. `mcp__context7__resolve-library-id` with libraryName +2. `mcp__context7__query-docs` with resolved ID + specific query + +Keep research focused on the single gray area. Do not explore tangential topics. + + + +- Do NOT research beyond the single assigned gray area +- Do NOT present output directly to user (main agent synthesizes) +- Do NOT add columns beyond the 5-column format (Option, Pros, Cons, Complexity, Recommendation) +- Do NOT use time estimates in the Complexity column +- Do NOT rank options or declare a single winner (use conditional recommendations) +- Do NOT invent filler options to pad the table -- only genuinely viable approaches +- Do NOT produce extended analysis paragraphs beyond the single rationale paragraph + diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index be37d214f..6830e23f1 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -362,6 +362,33 @@ Analyze the phase to identify gray areas worth discussing. **Use both `prior_dec 4. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation, or all already decided in prior phases), the phase may not need discussion. +**Advisor Mode Detection:** + +Check if advisor mode should activate: + +1. Check for USER-PROFILE.md: + ```bash + PROFILE_PATH="$HOME/.claude/get-shit-done/USER-PROFILE.md" + ``` + ADVISOR_MODE = file exists at PROFILE_PATH → true, otherwise → false + +2. If ADVISOR_MODE is true, resolve vendor_philosophy calibration tier: + - Priority 1: Read config.json > preferences.vendor_philosophy (project-level override) + - Priority 2: Read USER-PROFILE.md Vendor Choices/Philosophy rating (global) + - Priority 3: Default to "standard" if neither has a value or value is UNSCORED + + Map to calibration tier: + - conservative OR thorough-evaluator → full_maturity + - opinionated → minimal_decisive + - pragmatic-fast OR any other value OR empty → standard + +3. Resolve model for advisor agents: + ```bash + ADVISOR_MODEL=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-advisor-researcher --raw) + ``` + +If ADVISOR_MODE is false, skip all advisor-specific steps — workflow proceeds with existing conversational flow unchanged. + **Output your analysis internally, then present to user.** Example analysis for "Post Feed" phase (with code and prior context): @@ -451,10 +478,96 @@ For "Organize photo library" (organization task): ☐ Folder structure — Flat, nested by year, or by category? ``` -Continue to discuss_areas with selected areas. +Continue to discuss_areas with selected areas (or advisor_research if ADVISOR_MODE is true). + + + +**Advisor Research** (only when ADVISOR_MODE is true) + +After user selects gray areas in present_gray_areas, spawn parallel research agents. + +1. Display brief status: "Researching {N} areas..." + +2. For EACH user-selected gray area, spawn a Task() in parallel: + + Task( + prompt="First, read @~/.claude/agents/gsd-advisor-researcher.md for your role and instructions. + + {area_name}: {area_description from gray area identification} + {phase_goal and description from ROADMAP.md} + {project name and brief description from PROJECT.md} + {resolved calibration tier: full_maturity | standard | minimal_decisive} + + Research this gray area and return a structured comparison table with rationale.", + subagent_type="general-purpose", + model="{ADVISOR_MODEL}", + description="Research: {area_name}" + ) + + All Task() calls spawn simultaneously — do NOT wait for one before starting the next. + +3. After ALL agents return, SYNTHESIZE results before presenting: + For each agent's return: + a. Parse the markdown comparison table and rationale paragraph + b. Verify all 5 columns present (Option | Pros | Cons | Complexity | Recommendation) — fill any missing columns rather than showing broken table + c. Verify option count matches calibration tier: + - full_maturity: 3-5 options acceptable + - standard: 2-4 options acceptable + - minimal_decisive: 1-2 options acceptable + 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}" + +4. Store synthesized tables for use in discuss_areas. + +**If ADVISOR_MODE is false:** Skip this step entirely — proceed directly from present_gray_areas to discuss_areas. +Discuss each selected area with the user. Flow depends on advisor mode. + +**If ADVISOR_MODE is true:** + +Table-first discussion flow — present research-backed comparison tables, then capture user picks. + +**For each selected area:** + +1. **Present the synthesized comparison table + rationale paragraph** (from advisor_research step) + +2. **Use AskUserQuestion:** + - header: "{area_name}" + - question: "Which approach for {area_name}?" + - options: Extract from the table's Option column (AskUserQuestion adds "Other" automatically) + +3. **Record the user's selection:** + - If user picks from table options → record as locked decision for that area + - If user picks "Other" → receive their input, reflect it back for confirmation, record + +4. **After recording pick, Claude decides whether follow-up questions are needed:** + - If the pick has ambiguity that would affect downstream planning → ask 1-2 targeted follow-up questions using AskUserQuestion + - If the pick is clear and self-contained → move to next area + - Do NOT ask the standard 4 questions — the table already provided the context + +5. **After all areas processed:** + - header: "Done" + - question: "That covers [list areas]. Ready to create context?" + - options: "Create context" / "Revisit an area" + +**Scope creep handling (advisor mode):** +If user mentions something outside the phase domain: +``` +"[Feature] sounds like a new capability — that belongs in its own phase. +I'll note it as a deferred idea. + +Back to [current area]: [return to current question]" +``` + +Track deferred ideas internally. + +--- + +**If ADVISOR_MODE is false:** + For each selected area, conduct a focused discussion loop. **Research-before-questions mode:** Check if `research_questions` is enabled in config (from init context or `.planning/config.json`). When enabled, before presenting questions for each area: