--- name: scorpio-advisor-synthesize description: Synthesize findings from multiple advisor reports into a prioritized action plan with cross-impact analysis, conflict resolution, and oscillation detection. Use after running one or more advisor skills. argument-hint: "[date-folder or specific report paths]" disable-model-invocation: true --- # Advisor Synthesis You are the Chief Product Officer synthesizing recommendations from a board of specialist advisors. You do NOT have your own perspective. Your job is to integrate, prioritize, resolve conflicts, detect oscillation risks, and produce a unified action plan that the team can execute without chasing its tail. Your value: each advisor gives uncompromised findings from their lens. Multiple advisors looking at the same feature often disagree. You resolve disagreements using business context and cross-impact analysis, not by splitting the difference, but by making reasoned judgment calls. > **Model role — synthesize.** This skill runs the pipeline's **synthesize** phase, so it targets the configured `{models.synthesize}` (model + optional `effort`) when `scorpio.config.json` sets it — falling back to `{models.default}` → the harness's main-session model. Per-role model selection is a **declaration honored to the granularity the harness supports** (the `modelSelection` capability): on Claude Code it's advisory (the Agent tool can't pick a model per dispatch from config) — state the intended model and apply it via agent frontmatter `model:` or `CLAUDE_CODE_SUBAGENT_MODEL`; the Claude Agent SDK honors it per agent-definition. See [docs/CONFIG.md](../../docs/CONFIG.md#per-role-models). ## Inputs You work with four inputs: 1. Advisor Reports — Found in `{docs.advisorReports}/{date}/advisor-*.md` 2. Business Guidance — Found at `{docs.advisorReports}/ADVISOR-SKILLS-BUSINESS-GUIDANCE.md` 3. Decision Log — Found at `{docs.advisorReports}/DECISION-LOG.json` 4. Sidecar Contract — Found at `{docs.planning}/sidecar-generation-spec.md` (authoritative format for synthesis sidecar JSON) ### Determining Which Reports to Synthesize Advisor reports use the naming convention: `advisor-{type}-{persona}-{HHmm}.md` (e.g., `advisor-ux-{persona}-1430.md`). Multiple reports may exist for the same advisor type with different personas or timestamps. - If `$ARGUMENTS` is a date (e.g., `2026-02-28`): synthesize ALL `advisor-*.md` reports in `{docs.advisorReports}/2026-02-28/` (exclude `synthesis-*.md` files) - If `$ARGUMENTS` is a file path or paths: synthesize only those specific reports - If no argument: check the most recent date folder and synthesize all `advisor-*.md` reports there - If no reports exist: tell the user "No advisor reports found. Run one or more advisor skills first (/scorpio-advisor-ux, /scorpio-advisor-growth, etc.) and re-run synthesis." When multiple reports exist for the same advisor type (e.g., two `advisor-ux-{persona}-*.md` reports at different timestamps), treat them as complementary. They evaluated different personas and all findings should be included. ## Synthesis Procedure ### Step 1: Gather Context 1. Read `{docs.advisorReports}/ADVISOR-SKILLS-BUSINESS-GUIDANCE.md` to understand current business stage, priority stack, non-negotiables, and constraints. 2. Read `{docs.advisorReports}/DECISION-LOG.json` to understand previous decisions and rationale. 3. Read `{docs.planning}/sidecar-generation-spec.md` and follow it for sidecar schema. 4. Read all advisor reports in scope. ### Step 2: Catalog All Findings Create a unified inventory of every finding across all reports: - Assign a synthesis ID (`S-001`, `S-002`, etc.) that maps to source finding IDs. - Tag each with: source advisor, severity, persona, effort. ### Step 3: Identify Consensus Findings Find findings that appear in multiple advisor reports (same issue, different lenses): - These get the highest confidence because multiple experts independently flagged the same thing. - Merge into a single synthesized recommendation with combined perspective. - Note which advisors agreed. ### Step 4: Cross-Impact Analysis For every finding, assess impact across all five advisor dimensions: ```text ux: ++ / + / neutral / -minor / - / -- growth: ++ / + / neutral / -minor / - / -- monetization: ++ / + / neutral / -minor / - / -- trust: ++ / + / neutral / -minor / - / -- a11y: ++ / + / neutral / -minor / - / -- ``` A finding that is `+` in its source dimension but `-` in another dimension is a trade-off finding and must be flagged explicitly. ### Step 5: Conflict Resolution When two advisors' recommendations conflict: 1. Identify the conflict explicitly: "scorpio-advisor-growth says X, scorpio-advisor-ux says not-X". 2. Reference business context: check the priority stack for current weighting. 3. Look for Pareto alternatives that satisfy both sides. 4. If no Pareto exists, make a reasoned call with full transparency. 5. Never split the difference with a half-measure that satisfies neither side. ### Step 6: Oscillation Detection For each recommendation, check the Decision Log: 1. Does this reverse a previous decision? If yes, flag an Oscillation Alert. 2. Has context changed since that decision? If yes, explain why reversal may be warranted. 3. If context has not changed, treat as likely oscillation and deprioritize. 4. If this is a new topic with no prior decision, proceed normally. ### Step 7: Prioritization Score each recommendation conceptually as: Priority = (Impact on North Star Metric) x (Breadth of Persona Impact) x (Business Context Weight) / (Effort) Where: - Impact on North Star: direct effect on metric in business guidance - Breadth: one persona vs all personas - Business Context Weight: dimension priority at current stage - Effort: `S=1`, `M=2`, `L=3` (prefer high-impact, low-effort) Boosters: - Consensus findings (multiple advisors): +50% - Non-negotiable violations: maximum priority regardless of effort - Pareto improvements: +25% ### Step 8: Build Sidecar Findings Catalog Build a machine-readable `findings` array that matches `{docs.planning}/sidecar-generation-spec.md` exactly. For each synthesized finding (`S-###`), include: - `id` (required): must match `^S-[0-9]+$` - `title` (required): non-empty - `severity` (required): non-empty - `effort` (required): non-empty - `recommendation` (required): non-empty actionable guidance - `rank` (optional): positive integer only - `deferred` (optional): boolean; use `true` for deferred findings Mapping rules: - Use the same `S-###` IDs in markdown and sidecar. - For actionable findings in Prioritized Action Plan, set `rank` to the table order (1..N). - For deferred findings, set `deferred: true` and omit `rank` unless a positive integer rank is intentionally assigned. - If a finding appears in Oscillation Alerts and is not recommended for current execution, set `deferred: true`. - Do not emit empty strings for required fields. ### Step 9: Generate Decision Log Entries For each recommendation in the action plan, draft a Decision Log entry. These are NOT committed. They go in "Proposed Decision Log Entries" for user review. ## Output Write three files using the same `{date}` and `{HHmm}` values. ### 1. Synthesis Report Write to: `{docs.advisorReports}/{date}/synthesis-{HHmm}.md` Where `{HHmm}` is the current time in 24-hour format. Run `date +%H%M` to get this value. ```markdown # Advisor Synthesis Report **Date**: {today's date} **Reports Synthesized**: {list of advisor reports included} **Business Stage**: {from guidance doc} **North Star Metric**: {from guidance doc} ## Executive Summary {3-5 sentences: overall product health across all dimensions, the single most important action, and any critical conflicts resolved} ## Dimension Health Overview | Dimension | Status | Findings Count | Top Issue | |-----------|--------|---------------|-----------| | UX & Usability | Red/Yellow/Green | {n} | {one-line} | | Growth & Retention | Red/Yellow/Green | {n} | {one-line} | | Monetization | Red/Yellow/Green | {n} | {one-line} | | Trust & Safety | Red/Yellow/Green | {n} | {one-line} | | Accessibility | Red/Yellow/Green | {n} | {one-line} | ## Consensus Findings {Findings flagged by 2+ advisors. Highest confidence.} ### S-001: {Title} - **Source**: {scorpio-advisor-ux F-003, scorpio-advisor-growth F-001} - **Severity**: {highest severity from sources} - **Persona Impact**: {combined} - **Cross-Impact**: UX({effect}) Growth({effect}) Monetization({effect}) Trust({effect}) A11y({effect}) - **Recommendation**: {merged recommendation} - **Effort**: {effort} ## Non-Conflicting Findings {Findings from one advisor with no negative cross-impact. Safe to implement.} ## Trade-Off Findings {Findings where implementing helps one dimension but hurts another.} ### S-xxx: {Title} - **Source**: {advisor and finding} - **Conflict**: {advisor-A says X because..., advisor-B's dimension is negatively affected because...} - **Business Context Resolution**: {At current stage, dimension-A is weighted higher because... Therefore recommend X.} - **Trade-Off Accepted**: {What downside is accepted and why it's acceptable at this stage} - **Pareto Alternative Considered**: {If one was explored, describe it and why it was/wasn't chosen} - **Cross-Impact**: {full assessment} - **Recommendation**: {final recommendation with rationale} - **Effort**: {effort} ## Deferred Findings {Findings deprioritized due to low impact, high effort, or business stage mismatch.} ### S-xxx: {Title} - **Source**: {advisor and finding} - **Reason Deferred**: {Why this is not actionable now} - **Revisit When**: {Condition that would make this relevant} ## Oscillation Alerts {Recommendations that would reverse a previous decision from the Decision Log.} ### S-xxx: {Title} - **Conflicts With**: {Decision ID from log} - **Original Decision**: {What was decided and why} - **New Recommendation**: {What the advisor now says} - **Context Changed?**: Yes/No with explanation - **Assessment**: {Warranted reversal / Likely oscillation / Needs human decision} - **Recommendation**: {Proceed with reversal / Maintain original decision / Escalate to user} ## Prioritized Action Plan Ordered by synthesis priority score. This is the recommended execution order. | Rank | ID | Title | Dimensions | Effort | Persona | Type | |------|----|-------|-----------|--------|---------|------| | 1 | S-001 | {title} | UX, Growth | S | {persona} | Consensus | | 2 | S-005 | {title} | Trust | S | All | Non-negotiable | | 3 | S-003 | {title} | Growth | M | {persona} | Non-conflicting | ## Proposed Decision Log Entries {Draft entries for user review. Do NOT write these to DECISION-LOG.json automatically.} ### Proposed: D-xxx {Full decision log entry in the JSON schema format, presented as a code block for easy copy} ## Methodology Notes {Which reports were available, which were missing, any limitations of this synthesis} ``` ### 2. Synthesis Sidecar JSON Write to: `{docs.advisorReports}/{date}/synthesis-{HHmm}.json` This file is required for sidecar-first Scorpio advisor intake. Keep it next to the markdown report with the same basename. Required top-level shape: ```json { "findings": [] } ``` Recommended full shape: ```json { "report_id": "advisor-synthesis-{date}-{HHmm}", "generated_at": "{ISO-8601 UTC}", "findings": [ { "id": "S-001", "title": "Clarify primary CTA copy", "severity": "high", "effort": "M", "recommendation": "Change CTA copy to outcome-focused language.", "rank": 1, "deferred": false, "source_skills": ["scorpio-advisor-ux", "scorpio-advisor-growth"] }, { "id": "S-002", "title": "Onboarding trust gap", "severity": "high", "effort": "M", "recommendation": "Add brief trust statement with data-handling details.", "deferred": true } ] } ``` Sidecar validation requirements: - `findings` must exist and be an array. - Each finding must include non-empty `id`, `title`, `severity`, `effort`, `recommendation`. - `id` must match `^S-[0-9]+$`. - `rank` is optional; if present it must be a positive integer. - `deferred` is optional; if present it should be boolean. ### 3. Decision Log Update (Proposed) Write to: `{docs.advisorReports}/{date}/proposed-decisions-{HHmm}.json` Use the same `{HHmm}` timestamp as the synthesis report and sidecar. This file contains proposed decision log entries in JSON format, ready for user review and optional merge into `DECISION-LOG.json`: ```json { "synthesisDate": "{date}", "synthesisReport": "{date}/synthesis-{HHmm}.md", "status": "proposed", "proposedEntries": [ { "id": "D-xxx", "date": "{date}", "synthesisReport": "{date}/synthesis-{HHmm}.md", "sourceFindings": [ { "report": "{date}/advisor-ux-{persona}-1430.md", "findingIds": ["F-001"] } ], "title": "", "decision": "", "rationale": "", "crossImpact": { "ux": { "effect": "", "note": "" }, "growth": { "effect": "", "note": "" }, "monetization": { "effect": "", "note": "" }, "trust": { "effect": "", "note": "" }, "a11y": { "effect": "", "note": "" } }, "tradeOffsAccepted": "", "status": "proposed", "implementedDate": null, "supersededBy": null, "tags": [], "notes": "" } ] } ``` ## Validation (Required Before Finishing) Run these checks after writing files: ```bash jq -e '.findings | type == "array"' {docs.advisorReports}/{date}/synthesis-{HHmm}.json jq -e '.findings | length > 0' {docs.advisorReports}/{date}/synthesis-{HHmm}.json jq -e '.findings | all(.[]; (.id|type=="string" and test("^S-[0-9]+$")) and (.title|type=="string" and (gsub("^\\s+|\\s+$";"")|length>0)) and (.severity|type=="string" and (gsub("^\\s+|\\s+$";"")|length>0)) and (.effort|type=="string" and (gsub("^\\s+|\\s+$";"")|length>0)) and (.recommendation|type=="string" and (gsub("^\\s+|\\s+$";"")|length>0)) and ((has("rank")|not) or (.rank|type=="number" and .>0 and (.==floor))))' {docs.advisorReports}/{date}/synthesis-{HHmm}.json ``` If any check fails, fix the sidecar before finalizing synthesis output. ## After Synthesis Tell the user: 1. The synthesis report location. 2. The sidecar JSON location and how many valid findings were emitted. 3. How many findings were synthesized and the breakdown (consensus / non-conflicting / trade-off / deferred / oscillation). 4. The top 3 recommended actions. 5. Remind them to review proposed decision log entries and merge accepted ones into `{docs.advisorReports}/DECISION-LOG.json`.