completing-chunks

Completing chunks

Mechanical post-chunk pass. No judgment about quality of work — that's reviewing-execution. This skill measures what changed, writes it to the sidecar, and propagates.

When you're done

chunks.N.status: "completed". chunks.N.touched.actual populated from git diff. chunks.N.touched.drift computed (actual minus declared). completed_at set. If observations.md exists and was passed via --observations, the tracker records the path. If the plan rolls up to a roadmap row and this was the final chunk, the roadmap tracker's row is marked shipped.

Process

1. Confirm the chunk is committed. The verb measures drift from a commit range; uncommitted changes can't be measured. If the user hasn't committed, ask them to commit before invoking.

2. Invoke the verb:

   node greymatter/scripts/dev-pipeline.js complete-chunk --plan <plan-path> --chunk <N> [--observations observations.md]
   

   The verb resolves the commit range, runs git diff, queries graph.db for symbol-level changes, computes actual minus declared, writes the result to plan.tracker.json (status, touched.actual, touched.drift, completed_at), and ticks the roadmap row if this was the last chunk in a plan that rolls up to one.

3. Read the verb's stdout. It prints one line per drift record (<kind> <path>[::<symbol>]). Skim for surprises — anything outside the chunk body's intent is worth flagging to the user before the next dispatch.

   • Watch stderr for the degraded-graph warning. If you see complete-chunk: chunk N touched X file(s) but resolved 0 symbols — graph.db may not contain project '<name>', the symbol-level drift is silent and only file-level records were written. Tell the user, run node greymatter/scripts/scan.js --project <name>, and re-run complete-chunk against the same commit range.

4. Hand off.

   • More chunks pending → offer dispatching-chunks for chunk N+1; the next dispatch reads the new drift entries and injects them.
   • Last chunk just completed → offer reviewing-execution. Stop.

Boundaries

• Does not judge the work. That's reviewing-execution.
• Does not edit plan.md. The body is immutable post-dispatch; corrections go in a superseding plan.
• Does not invent drift. If git diff is empty, drift is empty. The tracker's drift array is computed; never typed.

Anti-patterns

• Marking complete without computing drift. Skipping the verb strands downstream chunks on stale info.
• Mutating prior chunks' drift entries. Past chunks are append-only.
• Skipping roadmap tick. If the plan has a parent roadmap row and the plan is fully done, the roadmap must reflect it in the same operation.