workflow-end

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

Quick Summary

Goal: [Process] Close the active workflow cleanly — clear workflow tracking so the next prompt gets fresh detection, and before clearing state print a one-way developer-comprehension recap (what / purpose / how / why) of what the workflow changed so the developer understands the work without re-reading the diff.

Summary:

• Purpose: penultimate state-closure step (runs before /watzup) — close the active workflow cleanly so the next prompt gets fresh detection, AND leave the developer understanding what changed without re-reading the diff.
• Main steps (ordered): (1) integration-test coverage check on changed business-logic files; (2) spec ↔ TDD-test sync gate (spec-tdd-test-sync-gate) BEFORE task-completion verification; (3) sync knowledge graph if .code-graph/ exists; (4) mark this task completed; (5) print the diff-gated one-way comprehension recap (what / purpose / how / why); (6) announce Workflow [name] completed; (7) confirm state cleared.
• Blocking gates: coverage gap (changed handler/command/service/controller with no matching test) OR unadjudicated spec-vs-code drift → MUST surface via AskUserQuestion, NEVER silent-skip; workflow MUST NOT report completed while drift is unadjudicated.
• Model-driven close: completes once ALL TaskList items done AND the sync gate recorded synced-or-accepted-as-is; NO hook clears state (residual .ck-workflow-state.json cleared only by session-init on explicit /clear).
• Recap depth throttled by codingLevel (CK_CODING_LEVEL → .claude/.ck.json → default 3); skip recap ONLY when there is no diff. The recap never quizzes and never blocks — deeper explanation is the standalone /understand skill.

Workflow:

1. Detect — classify request scope and target artifacts.
2. Execute — apply required steps with evidence-backed actions.
3. Explain — print the diff-gated comprehension recap (skip only when no changes).
4. Verify — confirm constraints, output quality, and completion evidence.

Key Rules:

• MUST ATTENTION when the workflow produced a diff, print the comprehension recap (what changed / purpose / how it works / why) — depth throttled by codingLevel, but NEVER fully skip when changes exist.
• MUST ATTENTION the recap is one-way — NO quiz, NO teach-back, NEVER blocks. Deeper comprehension is handled by the standalone /understand skill, which /watzup invokes as its final handoff and which the developer can also invoke directly for any target.
• MUST ATTENTION run the spec ↔ TDD-test sync gate (spec-tdd-test-sync-gate) BEFORE task-completion verification when behavior-changing files are in the diff — the workflow MUST NOT report completed while a behavior-vs-spec divergence is unadjudicated; surface unsynced drift via AskUserQuestion, never silent-close.
• MUST ATTENTION keep claims evidence-based (file:line) with confidence >80% to act.
• MUST ATTENTION keep task tracking updated as each step starts/completes.
• MUST ATTENTION define success criteria before execution and loop until observable verification passes.
• MUST ATTENTION when creating/reviewing specs or tests, name Business Intent / Invariant Guarded or the protected business intent/invariant and ensure the test would fail if that intent breaks.
• NEVER skip mandatory workflow or skill gates.

When This Runs

This skill is the workflow state-closure step. In workflows including /watzup, runs after final verification/docs work and before /watzup, so active workflow closes before post-workflow summary and /understand handoff. As penultimate action — after all workflow work done, before clearing state — prints one-way developer-comprehension recap of what workflow changed. Use /understand for deep standalone explainer of any target.

NOT for: Manual invocation mid-workflow (use workflow switching via /start-workflow instead).

---

What To Do

1. Integration test coverage check (skip if workflow is docs/design/investigation/e2e-only, or project has no test suite):

   git diff --name-only HEAD && git ls-files --others --exclude-standard
   

(The second command lists untracked files not yet staged — catches brand-new handler files before first git add) - Scan changed files for those likely requiring integration test coverage: business logic files such as handlers, commands, queries, services, controllers, resolvers, event processors. Naming varies by stack — infer from the project's existing file patterns (e.g., *Service.*, *Handler.*, *Controller.*, *Command.*, *Query.*). - For each identified file → search for a corresponding test file. Infer the project's test naming convention from existing tests (e.g., *.test.ts, *Tests.java, *_test.py, *.spec.js, *Tests.cs). Check standard test directories (tests/, spec/, __tests__/, or adjacent test projects). - If ANY identified file lacks a corresponding test → MANDATORY: use AskUserQuestion: - Option A: "Run /integration-test now" (Recommended) - Option B: "Tests already written/updated — proceed" - No silent skip. Business logic changes without test coverage MUST be surfaced to the user. - If no business logic files changed, or all have matching tests → skip silently

2. Spec ↔ TDD-test sync gate (spec-tdd-test-sync-gate — runs BEFORE task-completion verification; skip with reason only if the workflow is docs/design/investigation/e2e-only OR the diff has no behavior-changing files):

   The feedback half of the loop closes HERE — a workflow MUST NOT report completed while the spec still diverges from the code that just changed. Green tests do NOT normalize that drift.

   • Scope to the behavior-changing files in the diff (same surface the coverage check above scanned — handlers/commands/queries/services/controllers/entities/event processors and behavior-bearing frontend logic).
   • Run /spec [mode=sync] over the §8 TCs ↔ executing tests for those files: reconcile every §8 TC against its covering test, and surface any §8 TC with no covering test or any business TestSpec guarding behavior with no §8 TC.
   • Re-check for unadjudicated spec-vs-code drift: any behavior-changing file whose divergence from the canonical Feature Spec was never classified CODE-WRONG / SPEC-STALE / AMBIGUOUS / in-sync (per SYNC:spec-drift-adjudication).
   • If /spec [mode=sync] finds an unsynced §8 TC, OR any behavior-vs-spec divergence is unadjudicated → MANDATORY: surface via AskUserQuestion:
     • Option A: "Reconcile now — run /spec [mode=sync] / /spec [update] to close the drift" (Recommended)
     • Option B: "Accept as-is — I will record the reason" (the user's accept-as-is reason is captured in the recap)
   • No silent skip, no silent close. Workflow MUST NOT report completed while a behavior-vs-spec divergence is unadjudicated — record the gate outcome (synced / accepted-as-is-with-reason) before proceeding.

3. Sync knowledge graph (skip if .code-graph/ dir doesn't exist):

   if [ -d ".code-graph" ]; then python .claude/scripts/code_graph sync --json && python .claude/scripts/code_graph update --json; fi
   

   Report results briefly.

4. Mark this task as completed via TaskUpdate

5. Explain the changes — developer comprehension recap (the final teaching step; runs after everything else is done):

   Scope what this workflow changed:

   git diff --name-only HEAD && git ls-files --others --exclude-standard
   

   • No diff (pure investigation/research/docs-only workflow with nothing built) → skip with reason "no changes to explain".
   • Diff present → ALWAYS print a one-way teaching recap so the developer understands the work without re-reading the diff. This is one-way — NO quiz, NO teach-back, NEVER blocks. For a deeper explanation of any target (a plan, subsystem, decision, concept, or bug), use /understand; /watzup invokes it as the final handoff.

   Throttle depth by coding level (resolve first found: env CK_CODING_LEVEL → .claude/.ck.json codingLevel → default 3):

   Level	Recap depth
   4–5	2–4 tight sentences on the highest-blast-radius change only
   2–3	The four-part recap below, concise
   0–1	The four-part recap, fuller, plainest language, define non-obvious terms

   Always print at least the short recap when a diff exists — NEVER fully skip.

   Structure (optimize for easiest learning — lead with high-level motivation, then drill into low-level logic; surface what a reader would NOT guess from the diff):

   1. What changed — concrete edits grouped by behaviour (not by file); cite file:line.
   2. Purpose / kind — feature / bug fix / enhancement / refactor / perf / security — and the problem it solves.
   3. How it works — mechanism, key logic, invariants relied on, edge cases preserved; focus the non-obvious.
   4. Why this way — rationale and trade-offs; why over the obvious alternative.

6. Announce to the user: "Workflow [name] completed. Next prompt will trigger fresh workflow detection."

7. Workflow end is model-driven — it completes once this skill's TaskList items are all marked done, AND the spec ↔ TDD-test sync gate (step 2) recorded synced-or-

---

Content truncated.