feat: add advisor mode with research-backed discussion
Adds an optional advisor mode to discuss-phase that provides research-backed comparison tables before asking users to make decisions. Activates when USER-PROFILE.md exists, degrades gracefully otherwise. New agent: gsd-advisor-researcher -- spawned in parallel per gray area, returns structured 5-column comparison tables calibrated to the user vendor philosophy preference (full_maturity/standard/minimal_decisive). Workflow changes (discuss-phase.md): - Advisor mode detection in analyze_phase step - New advisor_research step spawns parallel research agents - Table-first discussion flow in discuss_areas when advisor mode active - Standard conversational flow unchanged when advisor mode inactive
This commit is contained in:
jecanore
104
agents/gsd-advisor-researcher.md
Normal file
104
agents/gsd-advisor-researcher.md
Normal file
@@ -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
|
||||
---
|
||||
|
||||
<role>
|
||||
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
|
||||
</role>
|
||||
|
||||
<input>
|
||||
Agent receives via prompt:
|
||||
|
||||
- `<gray_area>` -- area name and description
|
||||
- `<phase_context>` -- phase description from roadmap
|
||||
- `<project_context>` -- brief project info
|
||||
- `<calibration_tier>` -- one of: `full_maturity`, `standard`, `minimal_decisive`
|
||||
</input>
|
||||
|
||||
<calibration_tiers>
|
||||
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)
|
||||
</calibration_tiers>
|
||||
|
||||
<output_format>
|
||||
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.
|
||||
</output_format>
|
||||
|
||||
<rules>
|
||||
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.
|
||||
</rules>
|
||||
|
||||
<tool_strategy>
|
||||
|
||||
## 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.
|
||||
</tool_strategy>
|
||||
|
||||
<anti_patterns>
|
||||
- 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
|
||||
</anti_patterns>
|
||||
@@ -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).
|
||||
</step>
|
||||
|
||||
<step name="advisor_research">
|
||||
**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.
|
||||
|
||||
<gray_area>{area_name}: {area_description from gray area identification}</gray_area>
|
||||
<phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
|
||||
<project_context>{project name and brief description from PROJECT.md}</project_context>
|
||||
<calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
|
||||
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="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:
|
||||
|
||||
Reference in New Issue
Block a user