agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/research/skills/agileflow-research/references/knowledge-decay-guide.md

@@ -0,0 +1,121 @@
+# Knowledge Decay Guide
+
+**Load this when:** Assessing whether research is still current, planning a research refresh, or flagging stale sources.
+
+## Decay Rate by Knowledge Type
+
+| Knowledge type                             | Half-life    | Refresh trigger                     |
+| ------------------------------------------ | ------------ | ----------------------------------- |
+| Technology benchmarks (LLM, cloud pricing) | 3–6 months   | Major model/service release         |
+| Market sizing and competitive landscape    | 6–12 months  | Quarterly                           |
+| Consumer behavior patterns                 | 12–18 months | Major platform shift or world event |
+| Regulatory and compliance requirements     | On change    | Watch for legislation updates       |
+| Industry best practices                    | 2–3 years    | Major methodology shift             |
+| Foundational principles (psychology, math) | 10+ years    | Paradigm shift only                 |
+| Vendor pricing and feature availability    | 1–3 months   | Before any procurement              |
+| SEO signals and algorithms                 | 6–12 months  | Major algorithm update              |
+
+---
+
+## Staleness Signals
+
+### Hard signals (research is definitely stale)
+
+- [ ] Publication date >12 months for fast-moving domain (tech, market)
+- [ ] Referenced product, version, or service no longer exists
+- [ ] Statistics cite a timeframe that has ended ("by 2024...")
+- [ ] Source cites a study that has since been retracted
+- [ ] A major event has occurred that would invalidate the assumptions (pandemic, regulation, acquisition)
+
+### Soft signals (may be stale — verify)
+
+- [ ] Publication date >24 months for moderate-velocity domain
+- [ ] The landscape "feels" different from what the research describes
+- [ ] Recent practitioner opinions contradict the research
+- [ ] The research was produced by a party that no longer exists or has merged
+
+---
+
+## Research Freshness Checklist
+
+Before using research findings in a decision, verify:
+
+| Check                                                | Action if failed                           |
+| ---------------------------------------------------- | ------------------------------------------ |
+| Source is less than [N months] old for this domain   | Find more recent source or flag as dated   |
+| No major market event has occurred since publication | Annotate finding with "pre-[event]" caveat |
+| The specific claim is still true (quick spot-check)  | Update or replace the finding              |
+| Sample still represents current population           | Note demographic / market shift            |
+| Technology referenced still exists as described      | Update with current equivalent             |
+
+---
+
+## Refresh Prioritization
+
+When research library needs updating, prioritize refresh by:
+
+1. **Decision proximity** — Refresh before any decision that depends on it
+2. **Decay rate** — Fast-moving domains first
+3. **Confidence impact** — Low-confidence + old = highest refresh priority
+4. **Consequence** — High-stakes decisions need fresh data
+
+### Scoring formula
+
+```
+Refresh priority = (decay_rate × 3) + (decision_proximity × 4) + (consequence × 3)
+Scale each 1–5; higher = refresh first
+```
+
+---
+
+## Evergreen vs. Time-Sensitive Research
+
+### Evergreen (stable over time)
+
+- Cognitive biases and decision-making frameworks
+- Accessibility standards (update only on WCAG version bump)
+- Security fundamentals (e.g., OWASP Top 10 — update every 4 years)
+- Mathematical and statistical methods
+- Agile/lean principles (not practices — those evolve)
+- Human motivation research (Maslow, self-determination theory)
+
+### Time-sensitive (refresh regularly)
+
+- AI model capabilities and limitations
+- Competitor feature parity
+- Pricing benchmarks
+- Platform algorithm behavior (SEO, social, ads)
+- Browser/device market share
+- Regulatory compliance requirements
+- API documentation and rate limits
+
+---
+
+## Research Decay Annotation Format
+
+When including potentially stale research in a synthesis:
+
+```markdown
+> **Currency note:** This finding is from [Date]. The domain moves quickly;
+> verify before relying on this for [decision type]. Last verified: [Date or "not verified"].
+```
+
+Or inline:
+
+```markdown
+[Data from 2023 — may be outdated; verify current benchmarks before using for pricing decisions]
+```
+
+---
+
+## Research Refresh Triggers (monitor these)
+
+| Trigger                                                     | Research to refresh                        |
+| ----------------------------------------------------------- | ------------------------------------------ |
+| New LLM model released (GPT, Claude, Gemini major versions) | AI capability benchmarks, cost comparisons |
+| WCAG version update                                         | Accessibility standards research           |
+| OWASP Top 10 update                                         | Security vulnerability rankings            |
+| Google algorithm update                                     | SEO signal research                        |
+| Major competitor launch or acquisition                      | Competitive landscape                      |
+| New regulation passed (GDPR, AI Act, CCPA amendments)       | Compliance requirements                    |
+| New framework major version (React 19, Node 22 LTS)         | Technical best practices                   |

package/content/plugins/research/skills/agileflow-research/references/research-prompt-guide.md

@@ -0,0 +1,141 @@
+# Research Prompt Guide
+
+**Load this when:** writing a research prompt for `/agileflow:research:ask`
+or helping a user formulate a research request.
+
+## What makes a good research prompt
+
+A lazy prompt gets a lazy answer. The quality of external research is directly
+proportional to the specificity of the prompt.
+
+**Rule:** A good research prompt should be long enough that it takes 30+ seconds to read.
+
+## Required components
+
+### 1. Context block (what you're building)
+
+```
+I'm building [feature] in [framework/language] version [X.Y].
+The codebase uses [relevant libraries]. The goal is [specific outcome].
+```
+
+### 2. Relevant code (50+ lines)
+
+Include the actual code that's causing the problem or is most relevant.
+Don't summarize — paste the real code. Include:
+
+- The function/component with the issue
+- How it's called
+- Related configuration
+- Error handling around it
+
+### 3. Exact error (if applicable)
+
+Full stack trace. Don't truncate. Include:
+
+- Error message
+- Stack trace to the first line in your code (not just library internals)
+- When the error occurs (on page load, on click, etc.)
+- Whether it's intermittent or consistent
+
+### 4. What was tried
+
+List each approach attempted and why it failed:
+
+```
+Tried approach 1: [description] → [what happened]
+Tried approach 2: [description] → [what happened]
+```
+
+### 5. Environment
+
+- Framework and version
+- Relevant library versions
+- Node/runtime version
+- Deployment target (serverless, container, etc.)
+
+### 6. Three specific questions
+
+Not "how do I fix this?" — specific, answerable questions:
+
+**Bad questions:**
+
+- "How do I make this work?"
+- "What's wrong with my code?"
+- "How do I use OAuth with Next.js?"
+
+**Good questions:**
+
+- "Does NextAuth v4 handle the `code` exchange differently when deployed to Vercel vs local? I'm seeing the callback URL mismatch only in production."
+- "Is there a known issue with Prisma's `findMany` returning stale data when using the connection pool with PlanetScale? I see the right data on direct DB query but not through Prisma."
+- "Should `useEffect` be used to set up a Supabase realtime subscription, or is there a better pattern in React 18 with concurrent mode?"
+
+## Prompt template
+
+```
+## Context
+I'm building [feature description] in [framework] [version].
+Stack: [list key dependencies with versions].
+Goal: [specific thing that needs to work].
+
+## Relevant code
+[paste 50+ lines of the most relevant code]
+
+## The problem / question
+[Describe the issue or decision in plain language]
+
+## What I've tried
+1. [approach 1] → [result]
+2. [approach 2] → [result]
+3. [approach 3] → [result]
+
+## Error (if applicable)
+[Full stack trace]
+
+## Environment
+- Node: [version]
+- [framework]: [version]
+- [key library]: [version]
+- Deployment: [platform]
+
+## Specific questions
+1. [specific, answerable question]
+2. [specific, answerable question]
+3. [specific, answerable question]
+```
+
+## When to escalate to research
+
+**Immediately (don't retry first):**
+
+- External API response doesn't match documentation
+- OAuth / SSO / SAML errors
+- Build or bundler configuration errors
+- "Cannot find module" for an unfamiliar package
+- Cryptic library-internal errors with no obvious cause
+
+**After 2 failed fix attempts:**
+
+- Persistent type errors despite seemingly correct types
+- Integration errors between two libraries
+- Tests failing in unexpected ways
+- Runtime errors with no obvious cause
+
+**Never needs research:**
+
+- Typos and syntax errors
+- Missing imports
+- Obvious null checks
+- Clear logic errors
+- Things you've fixed before in this codebase
+
+## Importing and organizing research
+
+After getting external answers:
+
+1. `/agileflow:research:import` — save findings with title, source, and relevant code snippets
+2. Tag by topic (e.g., "nextauth", "prisma-pooling") for future retrieval
+3. `/agileflow:research:synthesize` if you have multiple sources on the same topic
+4. Check `/agileflow:research:list` at the start of sessions working in the same area
+
+Research notes persist across sessions — build the knowledge base over time.

package/content/plugins/research/skills/agileflow-research/references/synthesis-template.md

@@ -0,0 +1,154 @@
+# Research Synthesis Template
+
+**Load this when:** Combining findings from multiple research sources, resolving conflicting evidence, or producing a research summary.
+
+## Synthesis Document Structure
+
+```markdown
+# Research Synthesis: [Topic]
+
+**Date:** YYYY-MM-DD
+**Sources reviewed:** [N] sources
+**Time period covered:** [date range of sources]
+**Confidence level:** High | Medium | Low
+
+---
+
+## Key Question
+
+[The specific question this research was answering]
+
+## Bottom Line Up Front
+
+[2–4 sentences: what we found, with confidence level.
+Lead with the finding, not the methodology.]
+
+## Findings by Theme
+
+### Theme 1: [Name]
+
+**Finding:** [1-2 sentence summary]
+**Evidence:** [Which sources support this, what kind of evidence]
+**Confidence:** High / Medium / Low
+**Contradictions:** [Any sources that conflict with this]
+
+### Theme 2: [Name]
+
+[Same structure]
+
+## Conflicting Evidence
+
+[Document where sources disagree, why, and how to interpret the conflict]
+
+## Gaps
+
+[What we still don't know. What questions this research raised.]
+
+## Implications
+
+[So what? What should we do differently based on this?]
+
+## Sources
+
+| #   | Source | Type | Date | Quality |
+| --- | ------ | ---- | ---- | ------- |
+| 1   |        |      |      |         |
+```
+
+---
+
+## Evidence Quality Tiers
+
+| Tier          | Source type                                              | Weight                        |
+| ------------- | -------------------------------------------------------- | ----------------------------- |
+| 1 (strongest) | Peer-reviewed studies, RCTs                              | Highest                       |
+| 2             | Large-sample surveys (N>1000), meta-analyses             | High                          |
+| 3             | Industry reports from credible firms (Gartner, McKinsey) | Medium-high                   |
+| 4             | Expert interviews, practitioner case studies             | Medium                        |
+| 5             | Blog posts, vendor reports, opinion pieces               | Low                           |
+| 6             | Anecdote, single data point                              | Treat as signal, not evidence |
+
+**Default rule:** If only Tier 4–6 evidence exists, state low confidence. Don't present it as settled.
+
+---
+
+## Handling Conflicting Evidence
+
+### Step 1: Categorize the conflict type
+
+| Conflict type             | Interpretation                                  |
+| ------------------------- | ----------------------------------------------- |
+| Sample population differs | Both may be correct for different contexts      |
+| Time period differs       | More recent data is usually more relevant       |
+| Methodology differs       | Higher quality methodology takes precedence     |
+| Definition differs        | May not actually be conflicting — clarify terms |
+| Funding source bias       | Adjust weight based on conflicts of interest    |
+
+### Step 2: Resolution approaches
+
+| Approach                                    | When to use                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| Accept the majority / higher quality source | Most cases                                          |
+| Report as "disputed"                        | Genuine ongoing debate, similar quality evidence    |
+| Split by context                            | "X is true for enterprise, Y is true for SMB"       |
+| Investigate further                         | Conflict changes the recommendation; need more data |
+
+### Step 3: Document explicitly
+
+```
+Conflicting finding: Source A says X; Source B says Y.
+Reason for conflict: [Your assessment]
+Resolution: [Which we're using and why]
+```
+
+---
+
+## Conflicting Evidence Red Flags
+
+- Single vendor reporting on its own product performance
+- Survey with low N (<100) contradicting large-N studies
+- Study funded by party with clear financial interest in the outcome
+- Source predates a major market or technology shift
+- Correlation presented as causation
+
+---
+
+## Knowledge Decay Assessment
+
+Include in synthesis:
+
+| Finding                     | Time-sensitive? | Revalidate by        |
+| --------------------------- | --------------- | -------------------- |
+| Market size / share         | Yes             | 12 months            |
+| Technology benchmarks       | Yes             | 6 months             |
+| Regulatory requirements     | Yes             | On regulation change |
+| User behavior patterns      | Medium          | 18 months            |
+| Foundational best practices | Low             | 3–5 years            |
+
+---
+
+## Synthesis Confidence Levels
+
+| Level        | Criteria                                                              |
+| ------------ | --------------------------------------------------------------------- |
+| High         | 3+ independent Tier 1–3 sources agree; no credible contradictions     |
+| Medium       | 2+ sources agree OR 1 strong source; some conflicting evidence exists |
+| Low          | Only 1 source, or sources conflict without clear resolution           |
+| Insufficient | Not enough evidence to draw conclusions; more research needed         |
+
+---
+
+## Citation Format (inline)
+
+```markdown
+Teams that write unit tests before code ship 40% fewer production bugs
+[McKinsey DevEx Report 2024, Tier 3, High confidence].
+```
+
+Or footnote style:
+
+```markdown
+... ship 40% fewer production bugs.^[1]
+
+[1] McKinsey DevEx Report, 2024. https://example.com
+```

package/content/plugins/research/skills/agileflow-research/workflows/analyze.md

@@ -0,0 +1,60 @@
+# Analyze Workflow — Implement Saved Research
+
+**Triggers:** "analyze my research on X", "I want to implement what I researched", "revisit that research", "turn the research into a plan", user references a specific research file
+
+**Goal:** Take a saved research note and produce a project-specific implementation analysis with multi-expert validation, then optionally create an artifact to track the work.
+
+## Inputs needed
+
+| Input         | Required | How to get it                                        |
+| ------------- | -------- | ---------------------------------------------------- |
+| research file | No       | Ask the user to pick from the index if not specified |
+
+## Steps
+
+1. If no file is specified, list `docs/10-research/*.md` sorted by most recent first. Ask the user which note to analyze. If an active story or epic in the project relates to a research topic, highlight that file as recommended.
+
+2. Check the file size before reading. For files under 50k characters, read directly. For larger files (50k+), extract only the relevant sections: Summary, Key Findings, Implementation Approach.
+
+3. Display a brief summary of the research: key findings, action items, import date.
+
+4. Ask the user: [A] Run implementation ideation with domain experts (recommended — maps findings to your codebase), [B] View the full research note, [C] Skip for now.
+
+5. If implementation ideation is chosen, auto-detect the research type from the topic and content keywords. Select 3–5 domain experts based on the detected type:
+   - Security keywords (auth, oauth, jwt, encryption, vulnerability) → security, api, testing, compliance
+   - Performance keywords (cache, optimize, latency, throughput, benchmark) → performance, database, api, monitoring
+   - Architecture keywords (migrate, upgrade, framework, refactor, redesign) → api, database, performance, security
+   - UI keywords (component, styling, accessibility, ux, design system) → ui, api, testing, accessibility
+   - Database keywords (schema, migration, query, index, model) → database, api, performance, datamigration
+   - Default (unclear or multi-domain) → api, ui, database, testing, security
+
+6. Deploy all selected experts simultaneously. Give each expert: the research topic and summary, the project context (read `package.json`, `README.md`, or `CLAUDE.md`), and their domain-specific analysis task (implementation fit, domain considerations, recommended approach with specific file paths, risks and effort estimate).
+
+7. Collect all expert outputs. Synthesize:
+   - HIGH CONFIDENCE steps: 2+ experts agree on the same approach or files
+   - MEDIUM CONFIDENCE: 1 expert with specific evidence
+   - Aggregate effort estimates (show range)
+   - Collect all risks, ordered by frequency across experts
+   - Determine artifact recommendation based on scope: ADR if experts discuss trade-offs or one-time decisions; Epic+Stories if 5+ files across multiple domains; Story if single focus area; Practice doc if guidelines/patterns only
+
+8. Present the Implementation Ideation Report: high-confidence steps, domain-specific considerations, risks table, effort summary, recommended artifact.
+
+9. Ask the user: [A] Create the recommended artifact (recommended), [B] Modify the approach first, [C] Save the analysis to the research file, [D] Cancel.
+
+10. If artifact creation is confirmed, create the appropriate artifact and confirm with file paths. The implementation plan is now tracked with expert-validated guidance.
+
+## Output
+
+Implementation Ideation Report displayed. Optional artifact (ADR/Epic/Story/Practice doc) created. If user chooses save-only, the analysis is appended to the research file.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/research/skills/agileflow-research/workflows/ask.md

@@ -0,0 +1,64 @@
+# Ask Workflow — Research Prompt Generation
+
+**Triggers:** "I need to research X", "generate a research prompt", "help me ask ChatGPT about", "I'm stuck on X", "create a prompt for Perplexity"
+
+**Goal:** Produce a detailed, context-rich prompt the user can paste into an external AI tool (ChatGPT, Perplexity, Claude web, Gemini) and get actionable results.
+
+## Inputs needed
+
+| Input                 | Required | How to get it                                      |
+| --------------------- | -------- | -------------------------------------------------- |
+| topic                 | Yes      | Ask the user if not stated                         |
+| error message         | No       | Ask: "Is there an exact error? Paste it verbatim." |
+| what was tried        | No       | Ask: "What have you already attempted?"            |
+| relevant source files | Yes      | Read from codebase — do not skip                   |
+
+## Steps
+
+1. Ask the user for the topic if not already provided.
+
+2. Read relevant files from the codebase:
+   - `package.json` or `pyproject.toml` for framework and dependency versions
+   - Source files related to the topic (read at least 50 lines of actual code)
+   - `README.md` or `CLAUDE.md` for project context
+
+3. Ask the user: "Is there an exact error message? Paste it verbatim." If yes, include it exactly as given — never paraphrase errors.
+
+4. Ask the user: "What have you already tried? List at least 2 approaches and what happened with each."
+
+5. Generate the research prompt with these mandatory sections in order:
+   - **Project Context** — framework, key dependencies with versions, relevant files
+   - **Current Implementation** — 50+ lines of actual code from the codebase (not pseudocode)
+   - **The Problem** — exact error message verbatim, expected vs actual behavior, steps to reproduce
+   - **What We've Already Tried** — 2+ approaches with what happened and why each didn't work
+   - **Specific Questions** — 3+ precise, contextualized questions (not "how do I fix this?")
+   - **What I Need** — root cause analysis, step-by-step solution with exact code, gotchas
+   - **Environment Details** — Node/Python version, OS, tool versions
+
+6. Validate the prompt before showing it:
+   - Is it 200+ lines? If not, add more code and context.
+   - Does it include 50+ lines of actual code? If not, read more files.
+   - Does it have the exact error verbatim (if applicable)?
+   - Does it list 2+ attempts?
+   - Does it have 3+ specific questions?
+     If any check fails, gather the missing information and regenerate — do not show an incomplete prompt.
+
+7. Display the prompt inside a code block so the user can copy it. End with: "Copy this and paste it into ChatGPT, Perplexity, or Claude web. When you get results, let me know and I'll save them."
+
+8. Present the user with these options: [A] Copy and go (no further action), [B] Save the prompt to `docs/10-research/prompts/YYYYMMDD-prompt-<topic-slug>.md` and update the research index, [C] Regenerate with more detail.
+
+## Output
+
+The prompt is displayed for copy/paste. If the user chooses to save: write to `docs/10-research/prompts/YYYYMMDD-prompt-<topic-slug>.md` and add a row to `docs/10-research/README.md` (Type = Prompt). After the user gets results from the external AI, hand off to the import workflow.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/research/skills/agileflow-research/workflows/import.md

@@ -0,0 +1,66 @@
+# Import Workflow — Save External Research
+
+**Triggers:** "I have research to import", "save these results", "I got an answer from ChatGPT", "paste research findings", "import this article", user pastes a large block of text with findings
+
+**Goal:** Format external research or AI-generated answers into structured markdown, save to the project knowledge base, and optionally run multi-expert implementation analysis.
+
+## Inputs needed
+
+| Input      | Required | How to get it                                      |
+| ---------- | -------- | -------------------------------------------------- |
+| topic      | Yes      | Ask the user: "What topic is this research about?" |
+| content    | Yes      | Ask: "Please paste the research results below."    |
+| source URL | No       | Ask: "Do you have a source URL?"                   |
+
+## Steps
+
+1. If the topic is not provided, ask: "What topic is this research about?"
+
+2. If content is not provided, ask the user to paste the research results. Accept: AI-generated answers, article text, YouTube transcripts, blog posts, meeting notes, documentation excerpts.
+
+3. Extract from the content:
+   - A 2–3 paragraph executive summary
+   - Key findings as bullet points
+   - Any code snippets (preserve these exactly — do not reformat or clean up)
+   - Concrete action items
+   - Potential story suggestions if the content implies feature work
+   - Risks or gotchas mentioned
+
+4. Format as structured markdown:
+
+   ```
+   # [Topic Title]
+   Import Date / Topic / Source / Content Type
+   ## Summary
+   ## Key Findings
+   ## Implementation Approach
+   ## Code Snippets   ← copied verbatim
+   ## Action Items
+   ## Risks & Gotchas
+   ## Story Suggestions
+   ## References
+   ```
+
+5. Show the formatted file to the user before saving. Present the user with these options: [A] Save to `docs/10-research/` (recommended), [B] Make changes first.
+
+6. If confirmed, generate the filename as `YYYYMMDD-<topic-slug>.md` and write to `docs/10-research/`. Then add a row to `docs/10-research/README.md` (5-column format: Date | Topic | Type | Path | Summary). Always update the index — never skip this step.
+
+7. After saving, present the user with these options: [A] Run implementation ideation — deploy 3–5 domain experts in parallel to analyze how this research applies to the codebase (recommended if content suggests changes), [B] Save as reference for later, [C] Link to an active Epic or Story.
+
+8. If the user chooses implementation ideation: auto-detect the research type from keywords in the content (security keywords → security/api/testing experts; performance keywords → performance/database/api/monitoring experts; architecture keywords → api/database/performance/security experts; default → api/ui/database/testing/security). Deploy all selected experts simultaneously. Each expert analyzes: implementation fit in the codebase, domain-specific considerations, recommended approach with specific file paths, risks and effort estimate. Synthesize results with confidence scoring — HIGH means 2+ experts agree. Present the Implementation Ideation Report, then ask whether to create an artifact (ADR for architecture decisions, Epic+Stories for large features spanning multiple files, Story for focused tasks, Practice doc for guidelines).
+
+## Output
+
+Research saved to `docs/10-research/YYYYMMDD-<topic-slug>.md`. Index updated. Optional: implementation ideation report and artifact (ADR/Epic/Story) created based on expert consensus.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/research/skills/agileflow-research/workflows/synthesize.md

@@ -0,0 +1,66 @@
+# Synthesize Workflow — Cross-Research Analysis
+
+**Triggers:** "synthesize my research on X", "what do my research notes say about", "find patterns across research", "combine findings from multiple notes", "what's the consensus on"
+
+**Goal:** Query across multiple research files to find consensus findings, unique insights, conflicts, and technology patterns — then optionally generate an implementation plan.
+
+## Inputs needed
+
+| Input         | Required | How to get it                                    |
+| ------------- | -------- | ------------------------------------------------ |
+| topic keyword | No\*     | Ask if neither topic nor files are provided      |
+| file list     | No\*     | Comma-separated filenames in `docs/10-research/` |
+
+\*At least one of topic or file list is required.
+
+## Steps
+
+1. If neither a topic nor a specific file list is provided, ask the user: "What topic should I search across your research notes?" Options: [A] Enter a topic keyword, [B] Show the full research index first, [C] Synthesize all research.
+
+2. If a topic keyword is given, search all files in `docs/10-research/` — check filename, title header, Summary section, and Key Findings section. List matching files with date, title, and a one-line summary.
+
+3. If 5 or fewer files match, proceed automatically. If 6 or more match, ask the user: [A] Analyze all N files, [B] Let me pick specific files, [C] Try a narrower search term.
+
+4. For each selected file, extract:
+   - Date (from filename YYYYMMDD prefix)
+   - Title (first `#` header)
+   - Summary (first paragraph of the Summary section)
+   - Key Findings (bullet list)
+   - Recommended Approach section if present
+   - Technologies mentioned
+   - Related ADRs, Stories, Epics
+   - Age in days
+
+5. Analyze across all files:
+   - **Consensus (HIGH):** same finding appears in 2+ files — mark with the source files
+   - **Unique (VERIFY):** finding only in 1 file — note age, flag for review if old
+   - **Conflict (NEEDS REVIEW):** different files recommend different approaches for the same topic — flag both positions
+
+6. Present the Synthesis Report:
+   - Files Analyzed (table with date, title, status, age)
+   - Consensus Findings (HIGH CONFIDENCE) with source files
+   - Unique Insights (VERIFY) with age assessment
+   - Conflicts Detected (NEEDS REVIEW) with resolution suggestion
+   - Technology Patterns (table of technology, mention count, first/most recent date)
+   - Related Artifacts (ADRs, Stories, Epics referenced across files)
+   - Timeline (oldest → newest)
+
+7. Present the user with these options: [A] Run implementation ideation with domain experts (recommended if consensus findings suggest actionable changes), [B] Save synthesis report to `docs/10-research/YYYYMMDD-synthesis-<slug>.md`, [C] Flag conflicts for review, [D] Search a different topic.
+
+8. If implementation ideation is chosen, follow the same multi-expert pattern as the import workflow: detect research type from synthesis content, deploy 3–5 experts in parallel, synthesize with confidence scoring, present Implementation Ideation Report, recommend artifact type.
+
+## Output
+
+Synthesis report displayed inline. Optionally saved to `docs/10-research/YYYYMMDD-synthesis-<slug>.md` with a row added to the research index (Type = Synthesis). Optional: implementation ideation report and artifact.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```