openspec-unblock-research

name

openspec-unblock-research

description

Supervisor-only, verification-first unblock research engine. Use when a task/attempt is marked BLOCKED and you need to normalize facts vs unknowns, gather evidence via configurable research providers (e.g., mcp__web-search-prime__*, mcp__context7__*, mcp__web-reader__*), and output a portable, auditable unblock report plus executable guidance written to caller-defined sinks (no assumed repo structure).

OpenSpec Unblock Research (Supervisor-Only, Verification-First)

Produce a repeatable unblock package when work is BLOCKED. Do not solve by guessing: separate facts from unknowns, then research to produce evidence-backed guidance.

This skill is intentionally workflow-agnostic: it does not know about run counters, retries, or task systems. The caller provides blocked_context and sinks (where/how to write outputs).

Inputs (from caller)

Ask for missing required inputs once, then proceed with what you have.

Required

• blocked_context (structured or semi-structured):
  • blocker_summary: 1-2 sentences.
  • error_excerpt: exact error text (or null if none).
  • symptoms: what happens, where, how often.
  • already_tried: commands/edits attempted + outcomes.
  • needs: what information/artifact is missing (logs, versions, access, files).
  • environment: OS, shell, language/runtime versions, tool versions, container/CI context.
• sinks: where to persist the report and/or guidance. Do not assume filenames.

Optional

• toolchain_config: research provider routing config (see below). If omitted, use the default provider ordering in this file.
• budget_config: limits for research cost and stopping conditions (see below).
• repo_context (if relevant): paths, modules involved, prior diffs, related issues/PRs.

Outputs

1. Portable Unblock Report (JSON, v1): canonical, structured, auditable.
2. Unblock Guidance (markdown): directly executable steps plus verification plus fallbacks.
3. Sink write-back: persist (1) and/or (2) exactly as configured by caller.

Canonical schema plus examples:

• references/portable-unblock-report.v1.md
• references/examples.md
• references/templates.md

Non-negotiables

• Verification before speculation: never elevate an unverified claim into a Key conclusion.
• Quote exact error_excerpt and command outputs as evidence artifacts when available.
• Every Key conclusion MUST have at least one evidence pointer.
• Every guidance step MUST include an explicit verification method.
• If you cannot run tools (no network, tool missing), output a "data to collect" plan instead of guessing.

Core workflow

Phase A - Normalize the blocker (facts vs unknowns)

1. Parse inputs into the report fields:
   • Facts: error text, stack trace lines, exit codes, file paths, versions, commands run.
   • Unknowns: missing versions, missing reproduction steps, missing logs, unclear scope.
2. Produce a minimal reproduction checklist:
   • exact command
   • expected vs actual
   • smallest input triggering it (file, snippet, env)
3. Produce a NEEDS list (what to ask for next) if reproduction is impossible.

Phase B - Plan research (provider routing plus queries)

Build query terms from facts only (error codes, function names, package and version, platform).

Plan providers by role (abstract, not tool-specific):

• Clue source (search): fast, broad, up-to-date pointers.
• Authority source (docs/API): official docs, API references, migration notes.
• Evidence fetcher (reader): pull primary text from candidate links.
• Internal authority (repo/CI logs): local files, lockfiles, tool output.

Phase C - Execute research within budget

Stop early when you have enough evidence to produce:

• 1-3 key conclusions
• runnable unblock steps plus verification
• at least one fallback path

If evidence conflicts, record the conflict explicitly and list the discriminating experiment.

Phase D - Synthesize into guidance (actionable plus verifiable)

Produce unblock guidance as ordered steps:

• Step: command/config/code location
• Why: tie back to key conclusion
• Verify: command/assertion/log line to confirm

Add fallbacks:

• If A fails -> B
• If B is blocked -> specify exact missing input required to proceed

Phase E - Write to sinks (caller-controlled)

Render (JSON report and/or markdown guidance) and write to each configured sink. If a sink cannot be written, record it as an error in the report and still return the outputs in-chat.

Toolchain config (declarative, extendable)

Treat each research tool (including future MCP servers) as a provider entry. Routing is driven by provider entries, not hard-coded logic.

Example shape:

{
  "providers": [
    {
      "provider_id": "mcp__context7__*",
      "tool_glob": "mcp__context7__*",
      "role": "authority|clue|evidence_fetcher|internal_authority",
      "priority": 10,
      "when": {
        "requires_error_excerpt": false,
        "keywords_any": ["function_name", "package_name"],
        "blocked_types_any": ["api-uncertainty", "version-mismatch"]
      },
      "stop_signals": {
        "confirmed_by_primary_source": true,
        "enough_candidates_to_verify": true
      },
      "budget_overrides": { "max_calls": 3 }
    }
  ]
}

To add a new MCP server later:

• Add it to the runtime allowlist (outside this skill).
• Add one provider entry (tool_glob, role, priority, triggers, stop signals) to toolchain_config. Do not change the core workflow.

Default provider ordering (if caller omits toolchain_config)

1. mcp__context7__* (authority source)

   • Use for: API signatures, official examples, breaking changes, migration guides.
   • Trigger when: blocker involves uncertain API usage, version mismatch, or doc uncertainty.
   • Stop when: primary-source excerpt confirms the needed behavior and version.

2. mcp__web-search-prime__* (clue source)

   • Use for: recent regressions, platform-specific behavior, new tool usage, common pitfalls.
   • Trigger when: error_excerpt includes searchable strings (error codes, exact messages).
   • Stop when: you have candidate links and hypotheses to verify.

3. mcp__web-reader__* (evidence fetcher)

   • Use for: converting links into quotable evidence (primary text).
   • Trigger when: you have candidate URLs worth verifying.
   • Stop when: you have enough primary-text evidence pointers for conclusions.

If these tools are unavailable, fall back to local verification: reproduce, inspect versions/lockfiles, locate failing codepaths, and produce a NEEDS list.

Budget config (overrideable)

If caller did not supply budget_config, use:

• max_tool_calls_total: 8
• max_evidence_items: 6
• min_independent_sources_high_confidence: 2
• timebox_seconds: 300
• early_stop_on_confidence: true

If budget is exhausted:

• Stop research.
• Output best-effort guidance labeled with confidence levels.
• Add open questions plus discriminating next experiments.

Sink model (declarative, caller-owned)

The caller provides sinks[]. Each sink declares:

• what to write: report_json and/or guidance_md
• where to write: file path (optional; can be "return only")
• how to insert: append or anchor-based insertion

Supported sink types are described in references/portable-unblock-report.v1.md (keep the canonical report JSON regardless of sink).

Supervisor/Worker contract

• Worker: captures a structured blocker record (facts only) and hands it off.
• Supervisor (you): runs this workflow, produces research-backed unblock guidance, and writes the auditable report via sinks.