investigation

ai-dp:investigation

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

This pipeline runs without user interaction. Never ask the user anything — resolve ambiguity yourself and record the call (and any alternatives you rejected) so the next step, ai-dp:decisions, can formalize it.

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 AIDP_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 <AIDP_SESSION_ID> placeholder in the bun commands below. If the line is not in context, drop the --session "<AIDP_SESSION_ID>" argument entirely; advance.ts falls back to process.env.AIDP_SESSION_ID.

1. Mark the step as running

bun ${AIDP_PLUGIN_ROOT}/scripts/cli/advance.ts set <RUN_DIR> steps.investigation.status running --session "<AIDP_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 something about the feature itself is genuinely ambiguous, do not ask the user — pick the most reasonable interpretation, proceed, and capture the ambiguity (and the interpretation you chose) under Risks & unknowns so ai-dp:decisions can record it as an explicit decision.

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 ${AIDP_PLUGIN_ROOT}/scripts/cli/advance.ts set <RUN_DIR> steps.investigation.artifact "context.md" --session "<AIDP_SESSION_ID>"
bun ${AIDP_PLUGIN_ROOT}/scripts/cli/advance.ts advance <RUN_DIR> investigation --session "<AIDP_SESSION_ID>"

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

context.md is a living document — ai-dp:decisions and ai-dp:plan-wrapup may append to it when later steps surface new details.

After advance, state.steps.decisions.status === "pending". The plugin's Stop hook hard-blocks the turn from ending until this step advances, so 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](${AIDP_STATE_DIR}/ai-feature-pipeline/<feature>/context.md). Continuing to decisions.

Your very next action MUST be a Skill-tool invocation in this same turn:

Skill(skill_name = "ai-dp:decisions")