silver-research

/silver:research — Research Composition Spec

SB queue builder for tech decisions and spikes. Parent orchestrator spawns workers; research artifacts hand off to feature/devops queues.

Never writes research inline in the parent session — workers execute flows.

Mandatory SB workflow execution

Before any local research write-up or handoff, the execution trace must show the dependency chain for this workflow. At minimum:

1. Invoke silver:clarify
2. Run the selected research path in the current host session; invoke MultAI only when the user explicitly requested it in the current task
3. Invoke silver:clarify
4. Handoff to silver:feature or silver:devops only after the research artifact exists

If any required downstream SB skill cannot be invoked, stop immediately and notify the user. If the user explicitly requested MultAI and it is unavailable, stop and offer install-and-retry or permission to continue with the default direct-research path. Do not treat missing MultAI as a blocker for the default path. Do not replace missing SB workflow steps with shell reconnaissance, direct edits, or ad hoc local reasoning.

The workflow-chain-guard.sh hook enforces this at edit time: once the composed workflow is active, implementation edits stay blocked until the required SB workflow markers are actually present in the workflow state. If the guard blocks you, the research chain has not been completed yet.

Pre-flight: Load Preferences

Read the User Workflow Preferences section of silver-bullet.md to load user workflow preferences before any other step. Silently apply any stored routing, skip, tool, MultAI, or mode preferences throughout this workflow.

grep -A 50 "^## [0-9]\+\. User Workflow Preferences" silver-bullet.md | head -60

Display banner:

SILVER BULLET ► RESEARCH WORKFLOW

Question: {$ARGUMENTS or "(not specified)"}

Composition Proposal

Before beginning execution, read existing artifacts to determine context and propose which flows to include or skip.

1. Context Scan

Research is an exploration-focused workflow — it produces artifacts, not shipped code. No FLOW 8 (EXECUTE), FLOW 12 (VERIFY), or FLOW 14 (SHIP) are included.

Artifact	Signal	Action
.planning/research/ directory exists	Prior research artifacts present	Note for continuity — do not skip, always re-scope
External spec artifacts provided	Structured source material	Include FLOW 5 (SPECIFY) to ingest into SPEC.md

# Check for existing research artifacts
ls .planning/research/ 2>/dev/null | head -5

2. Build Flow Chain

Construct the proposed flow chain for research/exploration work. Short chain — research produces artifacts only:

FLOW 3 (CLARIFY) → FLOW 4 (DECIDE) → FLOW 5 (SPECIFY) [only when research should become a spec]

No per-phase loop — research is a single-pass engagement that hands off to the appropriate SB implementation workflow (silver:feature, silver:ui, silver:devops, or silver:plan when the next step is planning rather than implementation).

3. Autonomous composition (default)

Do not ask Approve composition?. Log: SB ► research composed {N} paths — orchestrator active. Workflow tracking is started by flow-advance.sh.

5. Legacy manual workflow start (fallback only)

Resolve the workflow helper only when the hook did not start tracking.

# Build a comma-separated flow list from the confirmed composition (use the
# user-facing FLOW / PATH names so they match what compliance-status surfaces).
SB_FLOWS="<flow1>,<flow2>,..."   # filled in from the confirmed chain

if [[ -x scripts/workflows.sh ]]; then
  SB_WORKFLOWS_BIN="scripts/workflows.sh"
else
  SB_WORKFLOWS_BIN="$(
    for root in \
      "$HOME/.codex/plugins/cache/alo-labs-codex/silver-bullet/current" \
      "${SB_RUNTIME_HOME_ROOT}/plugins/cache/alo-labs/silver-bullet/current" \
      "$HOME/.codex/plugins/cache/alo-labs-codex/silver-bullet"/* \
      "${SB_RUNTIME_HOME_ROOT}/plugins/cache/alo-labs/silver-bullet"/*; do
      if [[ -x "$root/scripts/workflows.sh" ]]; then
        printf "%s\n" "$root/scripts/workflows.sh"
        break
      fi
    done
  )"
fi
if [[ -z "${SB_WORKFLOWS_BIN:-}" ]]; then
  echo "Silver Bullet workflow tracker not found. Run /silver:update or reinstall Silver Bullet, then retry." >&2
  exit 1
fi

SB_WORKFLOW_ID=$("$SB_WORKFLOWS_BIN" start /silver:research "the research question" "$SB_FLOWS")
export SB_WORKFLOW_ID
echo "Workflow tracker started: $SB_WORKFLOW_ID"

After each flow / path completes, mark it done:

"$SB_WORKFLOWS_BIN" complete-flow "$SB_WORKFLOW_ID" "<flow-name>"

When the entire composition finishes (after the final SHIP / RELEASE flow lands), close the workflow:

"$SB_WORKFLOWS_BIN" complete "$SB_WORKFLOW_ID"

complete archives the file under .planning/workflows/.archive/<id>.md and removes it from the active set, so the strict final-delivery gate will not match a stale id.

Legacy: the v0.22 single-file .planning/WORKFLOW.md mechanism is retired. The per-instance .planning/workflows/<id>.md files are the only workflow tracker as of v0.29.1.

After each path completes, the helper updates the Flow Log row in-place — the helper does not edit the file directly.

Step-Skip Protocol

When the user requests skipping any step:

1. Explain why the step exists (one sentence)
2. Offer: A. Accept skip B. Lightweight alternative C. Show me what you have
3. If user chooses A permanently: record in silver-bullet.md §10b and templates/silver-bullet.md.base §9b, then commit both files.

Step 1: Clarify Research Question

Invoke silver:clarify through the active runtime's SB-recognized skill invocation channel. Purpose: Socratic clarification — precisely define the research question before choosing the research mode. This prevents running the wrong research path or optional MultAI augmentation on an ambiguous question.

After silver:clarify completes, the research question should be specific enough to select a path.

Step 1.5: Research Mode Policy

Default mode is direct research in the current host session. Use repository context, local artifacts, and primary sources available through the current host/runtime.

Only opt into MultAI when the user explicitly asks for multi-AI, second-opinion, or cross-model perspectives in the current task.

If MultAI is requested but unavailable, stop and ask the user whether to install it now or continue with direct research only.

Step 2: Choose Research Path

Ask:

What type of research question is this?

A. Market/landscape — "What tools/solutions exist for X?", "What's the state of the art?", "What does the ecosystem look like?" B. Tech selection — "Should we use X or Y?", "Which library/framework/approach is best for our case?", "Compare X vs Y" C. Competitive/product intelligence — "How do competitors solve X?", "What does product Y do that we should learn from?"

Wait for selection. Note: if the answer is obvious from $ARGUMENTS or silver:clarify output, skip this question and proceed directly.

Path 2a: Market/Landscape Research

Invoked when: selection is A.

2a.1 — Direct landscape scan Research the landscape directly in the current host session. Prefer official docs, vendor materials, primary sources, repo constraints, and concrete examples over generic summaries.

2a.2 — Synthesize findings Summarize the market map, key options, trade-offs, and recommendations in a concise artifact.

2a.3 — Optional MultAI augmentation Only when the user explicitly requested multi-AI perspectives in the current task, invoke multai:landscape-researcher and then multai:consolidator through the active runtime's SB-recognized skill invocation channel to broaden and cross-check the direct research artifact. If MultAI is unavailable, stop and ask whether to install it now or continue without it.

Output: Write consolidated findings to .planning/research/<YYYY-MM-DD>-<topic-slug>/landscape-report.md

Proceed to Step 3.

Path 2b: Tech Selection Research

Invoked when: selection is B.

2b.1 — Build the evaluation criteria directly Define the decision criteria from the clarified question, repo constraints, and operational requirements.

2b.2 — Compare the options directly Use primary sources and concrete constraints to compare options and draft the recommendation rationale.

2b.3 — Optional MultAI augmentation Only when the user explicitly requested multi-AI perspectives in the current task, invoke multai:orchestrator, multai:comparator, and multai:consolidator through the active runtime's SB-recognized skill invocation channel to add cross-model perspectives and a comparison matrix. If MultAI is unavailable, stop and ask whether to install it now or continue without it.

Output: Write consolidated report to .planning/research/<YYYY-MM-DD>-<topic-slug>/comparison-report.md

Proceed to Step 3.

Path 2c: Competitive/Product Intelligence

Invoked when: selection is C.

2c.1 — Direct competitive/product research Inspect public product evidence, docs, changelogs, demos, reviews, and local problem context directly in the current host session.

2c.2 — Optional MultAI augmentation Only when the user explicitly requested multi-AI perspectives in the current task, invoke multai:solution-researcher through the active runtime's SB-recognized skill invocation channel to broaden the competitive scan. If MultAI is unavailable, stop and ask whether to install it now or continue without it.

Output: Write CIR to .planning/research/<YYYY-MM-DD>-<topic-slug>/competitive-intelligence-report.md

Proceed to Step 3.

Artifact Output Protocol

After any research path completes, ensure the artifact directory exists before writing:

mkdir -p ".planning/research/$(date +%Y-%m-%d)-{topic-slug}/"

The artifact file path will be referenced in the handoff to the receiving workflow (Step 4). Research lineage is fully traceable via the .planning/research/ directory — the path is passed explicitly to the receiving workflow so provenance is never lost.

Step 3: Apply Research to Engineering Design

Invoke silver:clarify through the active runtime's SB-recognized skill invocation channel. Purpose: apply research findings to engineering design — turn the research artifact into a decision-ready handoff that the implementation workflow can absorb. Use the research artifact as primary input context for the clarification pass.

Step 4: Hand Off to Implementation Workflow

Ask:

Research complete. Which workflow should receive these findings?

A. silver:feature — build a new feature based on research findings B. silver:devops — infrastructure/deployment change based on research findings C. Done — research-only engagement, no implementation needed

If A: invoke silver:feature through the active runtime's SB-recognized skill invocation channel. Pass the artifact path (.planning/research/<date>-<topic>/) as context argument so silver:context and silver:plan can reference it.

If B: invoke silver:devops through the active runtime's SB-recognized skill invocation channel. Pass the artifact path as context argument.

If C: summarize research artifacts created and their paths. Done.