Chunks from investigations

An investigation is the right shape when you don't yet know what work to do. The question can be diagnostic ("why does this regress?", "is this safe to remove?") or it can be a wild architectural idea you can't yet draw a line to ("I wish I could run chunks in parallel in the background, but I have no idea how"). Either way, you can't yet sketch the chunks; you need to think before you can plan.

The work of an investigation is conversation, experiment, and active thinking in partnership with an agent. The output is usually a realization that lets you spell out the chunks that get you there ("a system like the orchestrator could do this, and here's how I'd decompose it"). Sometimes the realization is that no work is needed, or that the work doesn't carry enough intent to earn a chunk and should just be vibed.

When to reach for one

• You have a wild architectural idea and no idea how to make it real.
• You're diagnosing an issue with no clear fix.
• You're considering a change but want to validate it first.
• You have hypotheses to test, not steps to execute.

Creating

Investigations are created with the /investigation-create skill. The natural workflow is to brain-dump the question or wild idea to the agent and ask it to use the skill. The skill scaffolds OVERVIEW.md from a template (calling ve investigation create underneath); you and the agent then iterate on it as the investigation progresses.

OVERVIEW.md has four sections:

• Trigger: what prompted the investigation.
• Success Criteria: what "answered" looks like.
• Testable Hypotheses: what you believe and how you'd disprove it.
• Proposed Chunks: work that emerges from findings.

Status flow

NOTED is underused. A lot of investigation work is figuring out that the right answer is "leave it alone for now," and recording that is more useful than deleting the directory.

From findings to chunks

As the investigation surfaces specific work, append it to proposed_chunks:

proposed_chunks:
  - prompt: "Cache product lookups in the checkout path"
    chunk_directory: null
  - prompt: "Add a regression test for the bundle pricing path"
    chunk_directory: null

When the investigation reaches SOLVED (or NOTED with action), apply the intent test to each proposed chunk before realizing it. A proposal earns a chunk when the resulting code needs to remember why it exists: a constraint, a decision, or a tradeoff worth recording. Proposals that don't pass get vibed instead.

For the ones that do, ask the agent to materialize them as FUTURE chunks. The agent walks the proposed-chunk list, runs /chunk-create for each, and refines each goal against what the investigation found. Each chunk's GOAL.md should reference the investigation in its frontmatter:

investigation: slow_checkout_january

This keeps the lineage intact. The chunk knows where the work came from; a future agent reading the chunk can read the investigation to understand the evidence behind the goal.

Finding the intent

Chunks need intent. If you don't yet know what the architectural intent is (what constraint, decision, or tradeoff the code should remember), you're not ready to write a chunk. Investigations exist to find that intent.

Agents turn out to be very good at this. Hand one an ambitious-but-confused engineer with a wild idea or a murky question, and it can interview its way to the heart of the matter: targeted follow-ups, small experiments, hypotheses tested aloud, until an articulable intent surfaces. That intent is what becomes the chunk.

Investigations are cheap. Reach for one whenever the intent isn't clear yet.