investigation

dp:investigation

You are running the investigation step of an active dev-pipeline run. Your goal: build a wide context for the feature so the later planning steps can be precise.

Inputs

• RUN_DIR — absolute path to the run directory (provided by the orchestrator).
• <RUN_DIR>/state.json — read state.args to get the feature description.

Procedure

Session id: if a DP_SESSION_ID=<id> line is present in your conversation context (see the orchestrator command's "Session id capture and propagation" section for the matching rule), substitute that value for every <DP_SESSION_ID> placeholder in the bun commands below. If the line is not in context, drop the --session "<DP_SESSION_ID>" argument entirely; advance.ts falls back to process.env.DP_SESSION_ID.

1. Mark the step as running

bun ${DP_PLUGIN_ROOT}/scripts/cli/advance.ts set <RUN_DIR> steps.investigation.status running --session "<DP_SESSION_ID>"

2. Gather context — go wide, not narrow

Read the user's feature intent from state.args. Then:

• Identify the high-level area(s) of the codebase this feature touches.
• Read parent modules, sibling features, related models/types — not just the immediate files. Wide context matters more than depth at this stage.
• Search for existing utilities, components, or hooks that could solve sub-problems (Grep/Glob).
• Note testing patterns used nearby.
• Continue until you can confidently state what the feature is, where it lives, what it depends on, and what looks risky.

If you hit something genuinely ambiguous about the feature itself (not the codebase), ask one AskUserQuestion to disambiguate. Do not interrogate.

3. Write <RUN_DIR>/context.md

Use this exact section structure:

# Context: <feature name>

## Feature explanation
<Plain-prose description of what the feature is. Start from state.args and clarify ambiguities. State user-visible behavior, not implementation.>

## Related files
Group by role. Use markdown links with absolute paths.

### Entry points
- `<path>` — <one-line role>

### Models / types
- ...

### Sibling features
- ...

### Shared utilities (potential reuse)
- ...

### Tests
- ...

## Existing code worth reusing
Specific functions / components / utilities already in the codebase that solve sub-problems for this feature. Each item: name, path, one-line description of what we'd reuse it for.

## Risks & unknowns
- Anything ambiguous, brittle, or potentially blocking that the next steps must address.

4. Record the artifact and advance

bun ${DP_PLUGIN_ROOT}/scripts/cli/advance.ts set <RUN_DIR> steps.investigation.artifact "context.md" --session "<DP_SESSION_ID>"
bun ${DP_PLUGIN_ROOT}/scripts/cli/advance.ts advance <RUN_DIR> investigation --session "<DP_SESSION_ID>"

5. Hand off to the next skill — do not text-stop

context.md is a living document — dp:plan-proposal and dp:plan-wrapup will append to it whenever user feedback at those gates surfaces new details.

After advance, state.steps.plan-proposal.status === "pending". The plugin's Stop hook gates progression on Claude Code (hard block) and auto-prompts the next skill on Cursor (soft auto-submit). Either way, advancing state.json correctly is mandatory.

Before any hand-off action, print a one-liner referencing context.md as a markdown link:

Investigation complete — wrote [context.md](${DP_STATE_DIR}/feature-pipeline/<feature>/context.md). Continuing to plan-proposal.

On Claude Code: your very next action MUST be a Skill-tool invocation in this same turn:

Skill(skill_name = "dp:plan-proposal")

On Cursor: there is no Skill tool — end your turn after the one-liner above. The plugin's stop hook will auto-submit /plan-proposal as a follow-up turn, triggering the next skill via slash-prefix auto-discovery.