Imported from VoDmAl/ai-dev-plugins (plugins/vdm/skills/crystal-cut/SKILL.md). Install upstream with npx skills add VoDmAl/ai-dev-plugins --skill crystal-cut. Copyright stays with the author (MIT).

crystal-cut - Close a Crystal

Purpose

Transitions a crystal from status: in-progress to status: done. The crystal-completion-guard PreToolUse hook (${CLAUDE_PLUGIN_ROOT}/scripts/crystal-completion-guard.sh) enforces the gate at the tool layer: any - [ ] checkbox in the workitem blocks the transition (Decision Log #4 generalizes "completion discipline" — every unchecked checkbox is an open obligation, not only sidetracks).

This skill is the orchestration layer above the gate: it sweeps the workitem, surfaces the open items with the five resolution paths, then performs the flip once the user has addressed each.

Gate behavior (defense in depth)

Three layers enforce the same invariant (Decision Log #7):

1. Primary — PreToolUse hook on Write/Edit/MultiEdit for workitem files. Works in any project regardless of git. It evaluates the post-edit content, so it also fires on the creating Write: a brand-new file written straight at status: done must contain zero - [ ], or the gate blocks it. (Relevant when importing an already-complete legacy doc — see crystal-grow → Migrating legacy docs.)
2. Stop reminder — ${CLAUDE_PLUGIN_ROOT}/scripts/crystal-stop-reminder.sh surfaces open items at end-of-turn so the assistant doesn't drift.
3. Backup (git only) — pre-commit hook ships with vdm-git for downstream projects with git. See /vdm-git:guard for activation.

The gate is intentionally cheap to circumvent only via the five resolution paths — there is no --force flag and no --no-verify shortcut in this skill. If the gate seems wrong for a specific case, the right move is to use one of the five paths (most likely cancelled (reason: ...)), not to bypass.

Terminal-tier gates (DL #10 in crystal-multi-root)

The done transition triggers the unchecked-items gate above. Two other terminal statuses behave differently:

The superseded-by requirement is enforced by the same PreToolUse hook (crystal-completion-guard.sh → crystal-completion-guard.py) — see DL #10 for the gate design.

Orphan-sidetracks gate (DL #14 in crystal-multi-root)

A sidetrack card can have **Status:** open without a corresponding inline - [ ] см. Sidetrack #N marker in the workitem body. Without the marker, the obligation is invisible to the checkbox-counting unchecked-items gate — crystal-cut would silently pass over it. DL #14 declares the inline-marker requirement; this gate enforces it deterministically.

Logic: scan every sidetrack card heading ### #N. <title> followed at some point by **Status:** open[ ...]. For each, look for a matching marker line - [ ] ... Sidetrack #N anywhere in the body. Cards lacking a marker are reported as orphans and block the done-transition with the combined diagnostic (orphans listed alongside unchecked items if both exist).

Decision-Log entries use a different heading shape (### #N / date / title, slash separator, no period after N) and never carry **Status:**, so the parser does not collide with them.

Fix path for orphans: add the marker line (typically inside a ## Pending sidetracks block under ## Next actions, or at the spot of origin if the побег surfaced in body text), then resolve it via one of the five paths above. The marker turns the invisible obligation into a visible checkbox the other gate already understands.

Implementation:

• bash audit_sidetracks_without_markers <workitem-path> in lib/crystal-path.sh
• python _audit_sidetracks_without_markers(content) in crystal-completion-guard.py Both must stay in sync — they implement the same parser.

Five resolution paths (DL #9)

Each unchecked item must be addressed by one of:

For migrated / cancelled / deferred / promoted-to-stem: the sidetrack card's **Status:** line is updated AND the inline - [ ] marker is checked ([x]) since the obligation has been addressed in a defined way. The gate counts checkboxes, not statuses — keeping the two in sync is required.

Behavioral protocol

When /vdm:crystal-cut [slug] is invoked:

Step 1: Locate the target

If slug is supplied:

• Single-root mode: target <root>/<slug>/workitem.md (canonical) or <root>/<slug>.md (legacy flat).
• Multi-root mode: slug is expected as <root-qualifier>/<slug> (per DL #6 in crystal-multi-root, e.g. auth/refactor-jwt). If only the short form is supplied and it's unambiguous (matches in exactly one root), use it; if it matches in ≥2 roots, ask which root.

If omitted, target the singleton active workitem (the one with status: in-progress). Multiple actives → consult derive_singleton_mode:

• global violation → warn and ask which one.
• per-root mode → one active is allowed per root; if pwd is under a resolved root, target that root's active; otherwise ask.
• off mode → ask explicitly which slug.

Step 1.5: Harvest check — the docs-distill handoff

Must run before the sweep, not after. docs-distill writes new - [ ] obligations into the workitem; sweeping first would clear a list that is about to grow.

A crystal in the work phase produced artifacts that went outward. Its findings about the subject — not about the conversation — are the whole reason it existed, and they die with it unless they are harvested. The forcing function here is normally a human who happens to notice; that is exactly what this step replaces.

Applies when the crystal shows evidence of the work phase:

• session-type: prd-work (or any non-capture type), or
• the workitem's ## Текущая модель / ## Decision Log holds claims about how the subject now works — as opposed to which option the conversation picked.

A pure capture-phase crystal (session-type: prd-prep, may well stay dormant forever) owes no harvest — the obligation is born with the work, not with the crystal. Skip this step for those.

Nudge, do not gate:

🧪 Crystal `<slug>` is in the work phase — was the harvest given?

Findings about the subject outlive this crystal; findings about the
conversation do not. Run /vdm:docs-distill to pull the survivors out and give
each an address, or say "nothing to harvest" and proceed.

If the user runs it, docs-distill appends - [ ] <finding> → <address> items to ## Next actions. From there the existing gate does the enforcing — the crystal cannot be cut while an unchecked box remains. Soft until named; binding the moment it is named. That is the whole mechanism; no new gate is added here.

Step 2: Sweep unchecked items

Read the workitem. Collect every - [ ] line with its line number and the section it appears under (## Next actions, ## Sidetracks → ### #N, inline Decision-Log discussion, etc.). Group by section for readability.

Step 3: Present the sweep

🔪 crystal-cut sweep: <slug>

  ## Next actions (3 open):
    L478:  - [ ] Скаффолд hook scripts
    L479:  - [ ] Регистрация в hooks.json
    L482:  - [ ] PROJECT_CHANGELOG.md entry

  ## Sidetracks (1 open):
    #6. Reflexive case — этa сессия как канонический пример (L431)

Resolve each via one of: [x] resolved | migrated → <slug> |
cancelled (...) | deferred (date) | promoted-to-stem (→ <sibling>).

For each open item, propose the most likely resolution path based on context (e.g. obviously-completed items → suggest [x]; long-deferred items the user mentioned punting → deferred). Do not auto-flip without confirmation — the user owns each path decision.

Step 4: Apply resolutions

For each addressed item:

• [x] resolved → Edit the checkbox in place
• migrated → create card in target crystal (cross-link both ways), flip this checkbox [x], update sidetrack **Status:**
• cancelled → flip checkbox [x], update sidetrack **Status:** with the reason
• deferred → flip checkbox [x], update sidetrack **Status:** with the deadline
• promoted-to-stem → run crystal-grow for the sibling, transfer the обязательство there, flip checkbox [x], update sidetrack **Status:**

Step 5: Flip status

Edit the frontmatter: status: in-progress → status: done. The PreToolUse hook will let this through because the unchecked count is now zero. If the hook still blocks, you missed an item — re-sweep.

Also bump last-updated: to today.

Step 6: Soft hints (DL #22)

After a successful close, emit two soft hints — text-only, no auto-trigger:

✓ Crystal `<slug>` closed (status:done).

Consider:
  - /vdm:changelog — record this workitem's outcome in PROJECT_CHANGELOG.md

If the close addressed N resolved (not migrated/cancelled/deferred) sidetracks where N > 0, additionally:

  - /vdm:learn — N resolved sidetracks may be candidates for knowledge capture

These are suggestions the user runs explicitly. Never auto-invoke.

Examples

Example 1: Clean close

User: /vdm:crystal-cut auth-refactor

Sweep finds zero unchecked items. Assistant flips frontmatter, emits the two soft hints. Done in one round.

Example 2: Resolve via mixed paths

Sweep finds 4 open items. Assistant proposes:

• "Update README" → [x] (already done in the last commit)
• "Add tracing" → migrated → observability-pass
• "Fix typo in deprecated API" → cancelled (API will be removed in v3)
• "Mobile UI variant" → deferred (deadline: 2026-06-01)

User confirms each. Assistant applies edits + flips status + emits hints.

Example 3: Gate fires on premature cut

User flipped status: done manually in IDE without using crystal-cut. The PreToolUse hook intercepts and emits the blocked-diagnostic. The assistant explains the five paths and runs the sweep above to bring the user back on rails.

Example 4: Done with one loose end — split it into a new sibling

The work is feature-complete except a single trailing obligation that has no existing home — e.g. zero-inbox shipped, but a commented-out cron line needs a real scheduling pass later. The sweep finds one - [ ]. There is no "done but for one thing" state — and there shouldn't be; the obligation has to land somewhere. Decide among three paths:

• date-bound ("revisit after the next release") → deferred (deadline: ...)
• genuinely dropped → cancelled (reason: ...)
• a real follow-up with no home → migrated → <new-sibling>

The third is the case worth spelling out, because the target doesn't exist yet:

1. crystal-grow cron-scheduling-pass — create the sibling first (it starts status: in-progress; this is fine, the singleton you're closing is about to go done).
2. Move the obligation into the new crystal's ## Next actions (or a sidetrack card), and cross-link: the source card's **Status:** becomes migrated → cron-scheduling-pass, the new crystal notes migrated from: zero-inbox.
3. Flip the source - [ ] → [x] (the obligation is addressed — it now lives elsewhere).
4. Re-sweep: zero unchecked → flip status: done. Cut succeeds.

Don't grow a whole sibling for something that's really a deferred or cancelled — a one-line follow-up rarely earns its own crystal. Reach for migrate-to-new only when the loose end is itself a unit of work.

Quality gates

• Harvest check offered for a work-phase crystal (Step 1.5), before the sweep
• All - [ ] checkboxes addressed (gate would block otherwise)
• Sidetrack **Status:** lines match their checkbox resolutions
• migrated items have cross-links in both source and target
• Frontmatter status: done AND last-updated: <today>
• Two soft hints emitted (always changelog; learn if N>0 resolved sidetracks)

Configuration

Shares the crystal config section with the other three crystal-* skills. See /vdm:crystal-grow for sub-commands. Disabling (crystal off) silences the reminder hooks but does not disable the PreToolUse gate — the gate is unconditional. To fully disable, uninstall the plugin.

Reflexive case

The suite's own design crystal — upstream at cc-vdm-plugins → docs/tasks/crystal-design/workitem.md, not in your project — was closed via this exact protocol when the crystal-* suite reached v1. The act of closing it validated the gate, the sweep, and the hint emission end-to-end. Read its final state for a worked example of a clean cut.