Vc Generate Closeout

vc-generate-closeout

Output style: closeout packet leads with the verdict/recommendation, tables for drift/readiness, one-line TL;DR — process/development-protocols/communication-standards.md.

Generate the post-EXECUTE closeout packet for a completed plan or phase. Produces a structured summary with archive-readiness classification, drift signal scoring, commit checkpoint recommendation, and the single best next valid state.

When To Invoke

Invoke this skill at the end of:

• Any non-trivial EXECUTE completion (the execute-agent's own closeout block)
• ENTER UPDATE PROCESS MODE flows before archiving a plan
• fast-mode-agent session end, after implementation and verification are complete
• Phase program closeout between phases (after validate + regression checkpoint, before inter-phase UPDATE PROCESS)

Do not invoke for trivial single-file fixes where the plan file is not involved.

Mode Selection

Choose one mode before generating the closeout packet.

Simple Mode (default)

Use when:

• The execute session just ended and all context is fresh in the conversation.
• The plan was a single-phase, straightforward implementation.
• No context compaction occurred during the session.

Behavior: write the 8-item closeout packet directly from the plan file and conversation context. No additional git or file scanning is required.

Deep Mode

Trigger conditions — use Deep Mode if any one of the following applies:

• The session was resumed after a context compaction (conversation context may be incomplete).
• The execute session was long — many sub-steps, multiple checklist sections, or multiple commits.
• The caller explicitly requests deep mode.
• The phase is part of a multi-phase program and accurate phase-completion status is required for the umbrella plan.

Behavior: gather evidence before writing the closeout packet. Run these steps in order:

1. git diff HEAD~1 --name-only — confirm which files were actually changed. Cross-reference against the plan's blast radius.
2. git log --oneline -5 — confirm commit messages match what was planned. Flag any commits that touch files outside the plan's scope.
3. Read the phase report if one was already written — confirm its claims match actual execution output.
4. Read the validate-contract test gates — confirm each gate's final status: green, known-gap, or skipped. Do not rely on memory for gate outcomes.
5. Read the plan Implementation Checklist — for every checked item, confirm a matching file appears in the git diff. Flag any checked item with no corresponding change.

After gathering evidence, write the closeout packet with explicit source citations for every material claim.

Quality difference between modes:

• Simple: "Section 2 completed — billing router updated" (from memory)
• Deep: "Section 2 completed — git diff HEAD~1 confirms packages/api/src/router/billing.ts modified (+47/-12 lines); test gate pnpm test:billing confirmed green in execute log"

When in doubt, prefer Deep Mode. A false-confident Simple closeout is worse than a slightly slower Deep one.

Closeout Packet Schema

Every closeout packet must include these 9 items. Present them in order.

1. Selected plan path

   • The exact file path of the plan being closed out (e.g. process/features/foo/active/foo-phase-01_PLAN_03-06-26.md). Never leave this implicit.

2. Closeout classification (one of three states — see §Closeout Classification States)

3. What was finished

   • A concrete list of what was actually implemented or changed. Not a restatement of the plan checklist — what was done in practice.

4. What was verified vs still unverified

   • What tests or evidence exist that confirm the work.
   • What still requires manual verification, user confirmation, or future test coverage.

4b. Validate-contract compliance

• Was VALIDATE run for this plan?
• Is a ## Validate Contract section present in the plan file?
• If VALIDATE was skipped, state the documented skip reason.
• A plan cannot be classified Ready for UPDATE PROCESS archival without a present validate-contract or a documented skip reason.

5. Cleanup done vs still needed

   • What context docs, reports, or process artifacts were already updated.
   • What remains: open TODOs, uncommitted changes, missing reports, stale references, or plan debt.

6. Single best next valid state (one of the allowed states from §Move-On Semantics)

   • Name the exact next action or plan path. Never end with a generic "move to next task."

7. Commit-checkpoint recommendation (see §Commit Checkpoint Classification)

   • Whether to invoke vc-git-manager before UPDATE PROCESS, or whether the remaining changes are process-only and the commit belongs after UPDATE PROCESS.

8. Regression status (phase programs only)

   • Which previously verified surfaces were checked for regression against this phase's blast radius.
   • Whether all passed, or whether fixes were applied before re-verification.
   • If regression checking was skipped (e.g., first phase with no prior verified surfaces), state why explicitly.

9. SPEC achievement

   • For each acceptance criterion in the locked *_SPEC_*.md, score met or unmet.
   • Each unmet criterion → a backlog NOTE (the SPEC is frozen; gaps go to backlog only).
   • If there is no SPEC for this plan (e.g. trivial or phase-program inner loop governed by the umbrella SPEC), state that explicitly.

Closeout Classification States

Exactly three states are allowed. Choose one and state it verbatim.

• Ready for UPDATE PROCESS archival

  • The selected plan path still matches the implemented work.
  • Required verification evidence exists.
  • No material deviations remain unresolved.
  • The user has confirmed or approved cleanup.
  • validate-contract is present in the plan file, or VALIDATE was explicitly skipped with a documented reason.

• Keep in active/testing

  • Implementation is substantially complete.
  • But testing, manual verification, or explicit user confirmation is still pending.
  • Do not archive until those are resolved.

• Needs PLAN/UPDATE PROCESS reconciliation

  • Material deviations from the selected plan were required during execution.
  • Context or process updates are needed before the plan can be archived.
  • The work should route through UPDATE PROCESS or back to PLAN first.

Drift Signal Scoring

After building the closeout packet, score the UPDATE PROCESS urgency by counting signals.

Signal sources (5 sources, max score 6):

• (a) Files touched during the EXECUTE phase: +1 if ≥1 file, +1 more if ≥10 files (max 2 from this source)
• (b1) Any .claude/, .codex/, or agent harness file (agent .md/.toml, SKILL.md, settings, hooks) changed: +1
• (b2) Any README.md, AGENTS.md, CLAUDE.md, or process/development-protocols/ file changed: +1
• (c) Session involved 3 or more memory-worthy observations (new patterns discovered, deviations documented, architectural decisions made): +1
• (d) Feature-folder structural change (new {slug}_{date}/ task folder created, backlog NOTE written, or task folder archived/moved): +1
• (e) Validate-contract deviation (execution diverged from the validate-contract or the plan's declared blast radius): +1

Thresholds and required wording:

The exact phrase for each band must appear word-for-word in the closeout output (do not rephrase — these are machine-matched strings):

• LOW (0–1 signals): (few files changed, nothing critical) include "UPDATE PROCESS available if you want."
• MEDIUM (2–3 signals): (notable scope — worth capturing learnings) include "Recommend UPDATE PROCESS -- significant changes detected."
• HIGH (4+ signals): (harness, agents, or protocol docs were edited — durable capture is urgent) include "Strongly recommend UPDATE PROCESS -- harness/protocol files touched."

Always include the exact threshold phrase verbatim in the closeout output. Do not summarize or rephrase the wording.