The research-workflow Skill — Structured Investigation Before Planning

Acting on assumptions is expensive. The research-workflow skill is Datarim's answer to the recurring cost of discovering mid-implementation that a library version is wrong, an API endpoint behaves differently than the docs say, or a component the plan assumed would exist already does not. The skill structures external investigation so those discoveries happen before code is written.

The skill runs in two primary modes. Full Mode is for features, new systems, or tasks involving unfamiliar technology — it covers all 10 research checkpoints. Lite Mode is for enhancements where most context is already known — it runs 5 of the 10 items. Quick fixes skip research entirely.

The 10 checkpoints

The checkpoints cover: current stable versions and recent major releases; breaking changes and deprecated APIs between current and target versions; recommended approaches from official guides; relevant documentation sections from the task's stack; examples of similar implementations and reference architectures; component compatibility; known CVEs and security advisories for dependencies; past experience from the project's long-term memory store; reusable components in the existing codebase; and infrastructure constraints — server resources, port allocation, network topology.

Tool selection is adaptive. If context7 MCP is available, it handles library documentation most efficiently. If web search is available, it handles version checks, CVE lookups, and architectural patterns. If neither is reachable, the skill falls back to codebase analysis using grep, file reads, and git history, marking those checkpoints as [OFFLINE — based on local context only].

The gap protocol

Research before planning does not eliminate every unknown. The skill has a second function: a gap discovery protocol for use when implementation hits a wall. The triggers are specific — an import fails unexpectedly, an API returns an unexpected response shape, a required feature is missing, components turn out to be incompatible. When any trigger fires, the developer agent pauses, spawns a focused researcher subagent, and waits for findings before continuing.

If the gap is fundamental — wrong technology choice, impossible requirement, architectural incompatibility — implementation stops entirely. The gap is recorded, and the operator is asked to run /dr-prd to revise requirements. The skill is explicit: do not attempt workarounds for fundamental gaps.

Pre-flight artifact discovery

Plans drift. Between /dr-plan and /dr-do, earlier tasks may have shipped, schemas may have changed, infrastructure resources may have been renamed. The skill includes a pre-flight procedure for the start of /dr-do: enumerate named artifacts in the plan, verify each against its current live state, and compare against the plan's assumptions. Three outcomes follow — match (proceed), already done (skip the step), or drift (document and pivot).

A real incident from the skill's history: a plan called for one integration approach; pre-flight discovery showed an earlier task had already shipped the alternative approach. Following the original plan would have discarded working code. The pivot was documented in the insights file; Phase 1 effort dropped from a planned 1–2 days to roughly 2 hours.

Empirical provider verification

When a task introduces or replaces a third-party endpoint, the contract must be confirmed by a real request before any code depends on it. The skill requires sending the smallest valid request that exercises the actual input format — including content type, auth header, and any vendor-specific flags — and capturing both a success response and an error response as fixtures. Documentation drifts; a three-minute curl probe replaces an unknown number of mid-implementation rewrites.

Research findings land in datarim/insights/INSIGHTS-{task-id}.md. Read what Datarim is for the full pipeline, or see the reflecting skill for how completed-task insights feed back into framework evolution.