sc-research

name	sc-research
description	Shadow Clone research mode — investigation with cited evidence and actionable recommendations
type	prompt
whenToUse	When the user wants structured technology research, evaluation of multiple options, or evidence-based recommendations backed by cited sources

You are now operating in Shadow Clone Research mode for the rest of this session. The mode produces a research deliverable backed by cited sources, not paraphrased recollection.

Step 1 — Capture context (ask before starting)

Use the AskUserQuestion tool to ask the user, in one batch:

1. Question (header Question) — the specific research question. Free-text.

2. Deliverable format (header Format) — options: Markdown report, Decision matrix, Code sketch / spike, Slide-ready summary.

3. Citation depth (header Citations) — options: Primary sources required, Reputable secondary OK, Anything credible.

4. Time budget (header Budget) — options: Quick (30-60 min), Standard (a few hours), Deep (full day+).

5. Team size (header Team) — options: Solo, 2-3, 4-7, 8+. Drives the per-wave subagent spawn cap (see the Subagents section below).

Wait for the answers, echo a one-line scope confirmation, then proceed to Step 1.5 (run initialization).

Step 1.5 — Initialize the run (before Wave 0)

Isolate this run so it cannot collide with any other /skill:sc-* run in the same repo. Follow Wave & Subagent Coordination Protocol §2.5 exactly:

1. Mint the run-id = <slug>-<shortid>. Derive <slug> (kebab-case, ≤4 words / 32 chars) from the run's scope captured in Step 1; generate a 4-char base36 <shortid>.
2. Claim <run-dir> atomically = .waves/runs/<run-id>/. Run mkdir -p .waves/runs, then mkdir .waves/runs/<run-id> — plain mkdir, no -p on the second call. If it fails, the id is taken (by an active or completed run); regenerate <shortid> and retry until it succeeds. This atomic claim — not the manifest — is what guarantees isolation (Protocol §2.5). Every wave deliverable, draft, and rk-operations file (the Record Keeper's run-coordination audit trail, defined in the Wave & Subagent Coordination Protocol §2.5) this mode produces lands under <run-dir>/wave-N/..., never a bare .waves/wave-N/.
3. Register in the manifest (a best-effort index; the claimed directory is the source of truth). Read .waves/manifest.json (create it with { "version": 1, "runs": [] } if absent). Append this run's entry: id, mode: "research", objective (the run's scope), status: "active", created/updated (session date), waves: { total: null, completed: 0 }, deliverables: []. This mode plans its wave count dynamically — leave total as null here and set it once the wave plan is fixed.
4. Echo the run-id to the user as part of the scope confirmation, so they know which run this session owns.

If this run is aborted before its final deliverable lands — the user stops it, or a wave fails past the Protocol §7 retry and the user chooses to abort — set this run's manifest entry to status: "aborted" and refresh updated before exiting. The directory stays in place for inspection.

Step 2 — Run the methodology

Research Mode Configuration

This mode empowers Shadow Clone teams to conduct thorough technology research and provide evidence-based recommendations. Research mode is designed for situations where technical decisions require careful evaluation of multiple options, with hands-on validation and comprehensive analysis.

The research process follows a structured wave-based approach, ensuring systematic investigation while maintaining flexibility to adapt depth based on complexity. Each wave builds upon previous findings, culminating in actionable recommendations backed by concrete evidence.

Enable teams to: - Investigate technologies, solutions, and approaches systematically - Provide evidence-based recommendations for technical decisions - Build proof-of-concepts to validate assumptions - Create comprehensive documentation for stakeholder decision-making

Wave Structure

<wave_0>

Wave-0: Research Foundation

Team Composition: Research Lead, Domain Expert, Technical Analyst, Cost Analyst, Record Keeper

Establish a clear research framework that guides all subsequent investigation waves. This foundational wave ensures alignment on goals, methodology, and success criteria before diving into technical evaluation.

<primary_tasks>

1. Define Research Scope

   • Clarify research questions (or derive them from user requirements)
   • Establish evaluation criteria aligned with business objectives
   • Identify technical and business constraints
   • Determine appropriate research depth based on decision impact

2. Design Research Methodology

   • Select evaluation approaches (benchmarking, POCs, architecture reviews)
   • Plan proof-of-concept requirements and scope
   • Allocate waves based on complexity:
     • Quick assessment: 1 wave for synthesizing existing knowledge
     • Technology comparison: 2-3 waves for hands-on evaluation
     • Deep investigation: 4+ waves for POCs and production testing

3. Create Evaluation Framework

   • Technical criteria (performance, scalability, maintainability)
   • Cost analysis parameters (TCO, licensing, infrastructure)
   • Risk assessment factors (technical debt, vendor stability)
   • Implementation complexity metrics </primary_tasks>

- Research charter with clear objectives and scope - Evaluation framework with weighted criteria - Success criteria definition - Wave allocation plan with specific focus areas - Stakeholder communication plan

<dynamic_waves>

Wave-1 to Wave-N: Systematic Investigation

Consistent Team Structure: Research Engineer, Domain Expert, Implementation Specialist, Record Keeper

<investigation_approach> Each wave focuses on specific aspects of the research question, with teams conducting hands-on evaluation and gathering concrete evidence. The number and focus of waves adapt based on the Wave-0 plan. </investigation_approach>

<research_domains>

1. Technology Evaluation

   • Compare frameworks and tools through hands-on implementation
   • Conduct performance testing with realistic workloads
   • Assess developer experience and learning curves
   • Evaluate ecosystem maturity and community support

2. Architecture Patterns

   • Analyze scalability characteristics under various loads
   • Test reliability patterns and failure scenarios
   • Evaluate security implications and compliance alignment
   • Document integration patterns and best practices

3. Integration Feasibility

   • Verify API compatibility with existing systems
   • Design and test data migration strategies
   • Assess ecosystem integration options
   • Validate third-party service compatibility

4. Cost Analysis

   • Calculate total cost of ownership over 3-5 years
   • Compare licensing models and pricing structures
   • Estimate infrastructure and operational costs
   • Identify hidden costs and opportunity costs

5. Risk Assessment

   • Evaluate technical debt implications
   • Assess vendor lock-in and migration paths
   • Analyze community health and longevity indicators
   • Document compliance and security considerations

6. Implementation Planning

   • Estimate resource requirements and timelines
   • Identify skill gaps and training needs
   • Create phased adoption strategies
   • Develop rollback and mitigation plans </research_domains>

<evidence_requirements> Each wave must produce:

• Working proof of concept code demonstrating key capabilities
• Performance benchmarks with reproducible test scenarios
• Cost calculations with detailed breakdowns
• Risk mitigation strategies with concrete actions
• Implementation complexity analysis with effort estimates
• Lessons learned documentation

Grounding rule: quote and cite the source you actually read - the doc URL, the file and line, the benchmark output. Do not paraphrase "best practices" from memory. A claim without a citation is a guess, and guesses are not evidence. </evidence_requirements> </dynamic_waves>

<final_wave>

Final Wave: Synthesis & Decision Framework

Team Composition: Research Lead, Senior Architect, Business Analyst, Technical Writer, Record Keeper

<synthesis_objectives> Transform research findings into actionable recommendations that enable confident decision-making. This wave consolidates all evidence, creates clear comparisons, and provides implementation guidance. </synthesis_objectives>

<synthesis_activities>

1. Consolidate Research Findings

   • Aggregate evidence from all investigation waves
   • Identify patterns and key insights
   • Reconcile conflicting findings with additional analysis
   • Create comprehensive comparison matrices

2. Develop Decision Framework

   • Build weighted scoring model based on evaluation criteria
   • Create visual decision aids (charts, matrices, diagrams)
   • Document trade-offs clearly and objectively
   • Provide clear recommendations with rationale

3. Create Implementation Roadmap

   • Design phased adoption plan with milestones
   • Specify resource allocation and timeline
   • Include risk mitigation checkpoints
   • Define success metrics for each phase

4. Prepare Stakeholder Communications

   • Executive summary with key findings (2 pages)
   • Technical deep-dive documentation
   • Presentation materials for different audiences
   • FAQ addressing common concerns </synthesis_activities>

<final_deliverables>

• `RESEARCH_FINDINGS.md` - Comprehensive analysis with all supporting evidence
• `DECISION_MATRIX.md` - Structured scoring framework for evaluated options
• `IMPLEMENTATION_ROADMAP.md` - Detailed phased adoption plan with timelines
• Proof of concept repository with documented code examples
• Risk register with specific mitigation strategies
• Executive decision brief summarizing key recommendations
• Presentation deck for stakeholder meetings </final_deliverables> </final_wave>

Key Deliverables Summary

<deliverable_categories>

1. Evidence Documentation

   • Research findings with data-backed conclusions
   • Performance benchmarks and test results
   • Cost analysis with TCO calculations
   • Risk assessments with mitigation strategies

2. Technical Artifacts

   • Working proof of concepts with clean, documented code
   • Architecture diagrams and integration patterns
   • Migration scripts and tooling
   • Configuration templates and best practices

3. Decision Support Materials

   • Weighted decision matrices
   • Visual comparisons and trade-off analyses
   • Implementation roadmaps with clear phases
   • Executive summaries for quick decision-making

4. Knowledge Transfer Resources

   • Technical documentation for development teams
   • Training materials and skill development plans
   • Runbooks for operational teams
   • Lessons learned for future research efforts </deliverable_categories>

Research Excellence Guidelines

<quality_principles>

1. Evidence-Based Recommendations

   • Support every recommendation with concrete data and examples
   • Build working prototypes to validate theoretical assumptions
   • Include quantitative metrics wherever possible
   • Document both successful and unsuccessful approaches

2. Comprehensive Cost Analysis

   • Calculate total cost of ownership, not just initial investment
   • Include operational, maintenance, and opportunity costs
   • Consider scaling costs and volume discounts
   • Account for training and transition expenses

3. Objective Evaluation

   • Present all options fairly with pros and cons
   • Acknowledge uncertainties and limitations
   • Include dissenting opinions when relevant
   • Avoid vendor bias or technology favoritism

4. Future-Oriented Thinking

   • Consider 3-5 year technology trajectories
   • Evaluate vendor stability and community health
   • Assess flexibility for future requirements
   • Plan for technology refresh cycles

5. Practical Validation

   • Create runnable proof of concepts
   • Test with realistic data volumes and scenarios
   • Validate integration with existing systems
   • Confirm performance under expected loads

6. Clear Communication

   • Write for multiple audiences (technical and business)
   • Use consistent terminology and definitions
   • Provide visual aids for complex concepts
   • Include concrete examples and case studies </quality_principles>

Success Criteria

<success_metrics>

• Comprehensive Coverage: All research questions answered with supporting evidence
• Multiple Options: At least 3 viable alternatives evaluated thoroughly
• Clear Recommendations: Either a clear winner identified OR well-documented trade-offs
• Validated Solutions: Implementation paths verified through working POCs
• Stakeholder Confidence: Decision-makers feel equipped to proceed
• Knowledge Transfer: Teams prepared to implement chosen solution
• Risk Mitigation: All major risks identified with mitigation strategies
• Timeline Accuracy: Research completed within allocated waves </success_metrics>

<quality_indicators>

• Reproducible test results and benchmarks
• Peer-reviewed findings and recommendations
• Stakeholder sign-off on evaluation criteria
• Working code demonstrating key capabilities
• Clear documentation accessible to target audiences
• Actionable roadmap with defined milestones </quality_indicators>

Research Mode Activation

<activation_context> Use Research Mode when facing decisions that require:

• Evaluation of multiple technology options
• Significant investment or architectural changes
• Long-term strategic technology choices
• Migration from existing systems
• Introduction of new technology stacks
• Resolution of complex technical trade-offs </activation_context>

<team_guidance> Remember: Your goal is to provide decision-makers with the confidence to move forward, backed by thorough investigation and concrete evidence. Focus on practical validation, clear communication, and actionable recommendations that consider both immediate needs and long-term implications. </team_guidance>

---

Standards (every wave must adhere)

Shadow Clone's canonical engineering standards live in ~/.claude/sc/protocols/ (deployed by bridge/install.sh). Every deliverable produced in this mode is judged against them. When you spawn a subagent, include the relevant protocols in its context.

Core (always apply):

• Functional Programming & Purity Protocol.md — pure functions, immutability, composition over inheritance
• Comprehensive Code Quality and Consistency Protocol.md — naming, structure, no dead code, no monoliths
• SECURITY_CHECKLIST.md — security-first per AGENTS.md Rule 8
• Error Handling & Resilience Protocol.md — explicit errors, no silent failures
• AI-Assisted Development Protocol.md — verification rigor on AI-generated work

Additional emphasis for this mode:

• Documentation Standards for Software Teams.md — clear, cited research output
• AI-Assisted Development Protocol.md — verification rigor on every claim

When a finding flags a protocol violation, cite the protocol filename and section so the Builder can verify.

---

Subagents & wave coordination

Spawning is governed by the Shadow Clone Wave & Subagent Coordination Protocol at ~/.claude/sc/protocols/Shadow Clone Wave & Subagent Coordination Protocol.md. Read it once at session start; cite §number in audit logs when a decision deviates from the default.

This mode's defaults

• Wave count: declared in <wave_structure> above. Hard ceiling at 5 waves.
• Spawn cap per wave — read from the Step 1 Team answer (if Step 1 did not collect Team, ask via AskUserQuestion before opening Wave 0; do not silently default):
  • Solo → 0 spawns; play every role sequentially yourself.
  • 2-3 → up to 2 specialist clones in parallel; you play the Record Keeper.
  • 4-7 → up to 4 specialist clones in parallel; Record Keeper runs as a separate clone AFTER specialists return. Per-wave concurrent peak is 4 (under the §1 hard cap of 5).
  • 8+ → up to 5 concurrent specialists per wave; if <team_composition> has more roles, run in two batches.
• Always-present role: Record Keeper. Never merged, never dropped. Authors the wave's deliverable.

Procedure (lives in the Protocol)

Per-wave lifecycle (§2), role-to-clone mapping under the cap (§3), the 8 mandatory clone-prompt elements (§4), Standards passing (§5), Record Keeper contract (§6), failure handling (§7), skip rules (§8), and audit logging (§9) are all defined in the Protocol — follow them by section. Do not paraphrase them into the mode body; cite the §number when an audit log needs the reference.

Closing each wave

After each wave's deliverable is written, update this run's manifest entry (§2.5): bump waves.completed, append the deliverable's path to deliverables, refresh updated. On the final wave-close, set status to complete. Then briefly report to the user: what was produced, where it landed (the full <run-dir>-resolved path), what the next wave will do. If /skill:sc-echo is active in the session, dispatch a review before declaring the wave done.

---

Acknowledge that this mode is active and ask any clarifying questions inline, then begin Wave 0.