Chunks from narratives

A narrative is a multi-chunk initiative with the decomposition done up front. It's a vehicle for generating chunks; the chunks are what stake out the architecture. Use it when you can sketch the whole shape of the work and each piece carries enough intent to deserve its own chunk.

When to reach for one

  • The work has three or more chunks worth of intent-bearing scope.
  • You can describe the end state and the major steps from where you sit today.
  • Splitting up front would help with scheduling, parallelism, or review.

If you can't sketch the steps yet, you don't want a narrative. You want an investigation. If the work decomposes into a long list of mechanical edits with no architectural decisions to record, you don't want a narrative or chunks for it at all. Vibe it.

Creating

Narratives are created with the /narrative-create skill. The natural workflow is to brain-dump the initiative to the agent (what you're trying to build, why it matters, the rough shape of the arc) and ask the agent to use the skill to capture what you just said. The skill scaffolds OVERVIEW.md from a template, calling ve narrative create underneath. You and the agent then iterate on OVERVIEW.md until it captures the arc you're trying to paint.

OVERVIEW.md has two key sections:

  • Advances Trunk Goal: how this initiative connects to the project's goal in docs/trunk/GOAL.md.
  • Proposed Chunks: the prompts that will become real chunks.

Proposing chunks

The narrative's frontmatter holds the proposed-chunk list:

proposed_chunks:
  - prompt: "Add the new card-on-file model and migration"
    chunk_directory: null
  - prompt: "Wire the v2 payment endpoint to the new model"
    chunk_directory: null
  - prompt: "Migrate existing customers in the background"
    chunk_directory: null

chunk_directory is null until the chunk has been created. To see what's outstanding, two CLI commands help: 

$ ve chunk list-proposed     # all proposals (across narratives,
                             # investigations, and the friction log)
                             # that haven't been turned into chunks yet
$ ve chunk list --future     # all chunks that exist but aren't being
                             # implemented yet

Realizing the chunks

Before turning a proposed chunk into a real one, run the intent test on it: does the code that results need to remember why it exists? A proposal that fails the test isn't a chunk waiting to happen. It's work to vibe when the time comes. Strike those proposals from the narrative or mark them as out-of-chunk-system work.

For the proposals that pass: ask the agent to materialize them. You don't run ve chunk create by hand. The natural prompt is something like "turn the proposed chunks in the payment_methods_v2 narrative into FUTURE chunks." The agent iterates through the list, runs /chunk-create for each (with --future under the hood), and refines each GOAL.md against the narrative's framing and the existing code.

Once the chunks exist, you walk the goals one by one and decide whether each one fits your vision. Goals that miss get refined or rewritten; chunks that no longer fit the narrative get pulled. Each chunk's GOAL.md references the parent narrative in its frontmatter: 

narrative: payment_methods_v2

When an agent reads a chunk later, the narrative reference tells it where to look for shared context: the framing decisions, the order of operations, the why.

Workflow

  1. Brain-dump the initiative to the agent: what you're building, why, the rough shape.
  2. Ask the agent to use /narrative-create to capture it. Iterate on OVERVIEW.md with the agent until it captures the arc.
  3. Ask the agent to materialize the proposed chunks as FUTURE chunks.
  4. Walk each chunk's GOAL.md and decide whether it fits your vision; refine in turn or in parallel.
  5. Activate one chunk with ve chunk activate <name> and drive it through the usual workflow. Or, if the architecture is already well-defined and you're confident enough in how your goals will be interpreted to skip reading each plan file, inject the whole narrative into the orchestrator and have it solve the chunks in dependency order in the background while you sleep.

Narratives are scaffolding

Once a narrative has spawned its chunks, the narrative has done its work. The chunks now own the architectural intent and get maintained as the code evolves. The narrative itself drifts: proposed chunks that didn't pan out, descriptions that no longer match what shipped, an arc that turned out to bend differently in practice. That's expected.

Don't try to keep OVERVIEW.md in sync with the code. The narrative was the vehicle for generating the chunks; the chunks are what stake out the architecture from here.