deft-directive-refinement

name	deft-directive-refinement
description	Conversational refinement session. Ingests external work items into xBRIEF proposed/ scope, deduplicates via origin references, evaluates proposals with the user, reconciles stale origins, and promotes/demotes scopes through the lifecycle using deterministic task commands.
triggers	["refinement","reprioritize","refine","roadmap refresh","refresh roadmap","triage","action menu","work the cache","pre-ingest"]

Deft Directive Refinement

Conversational refinement session -- ingest, evaluate, reconcile, and prioritize scope xBRIEFs with the user.

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

Upstream pass: refinement begins with a triage pass -- see ../deft-directive-triage/SKILL.md (D6 / #1130) for the canonical cache-hygiene + "what's next?" queue playbook before continuing into the refinement flow below.

See also: ../../contracts/deterministic-questions.md (canonical numbered-menu rule used by every Phase 0 / Phase 2-5 gate below) | task cache:fetch-all / task cache:get (Tier 1 unified content cache, #883 Story 2) | task triage:bootstrap / task triage:accept / task triage:reject / task triage:defer / task triage:needs-ac / task triage:mark-duplicate / task triage:bulk-* / task triage:refresh-active (Phase 0 action surface, #845 + #883 Story 3 rebind).

Platform Requirements

! This skill requires GitHub as the SCM platform and the GitHub CLI (gh) to be installed and authenticated. Issue ingestion, origin freshness checks, and completion lifecycle all depend on gh.

Deterministic Questions Contract

! Every numbered-menu prompt rendered in this skill (Phase 0 Triage action menu, Phase 2 Evaluate per-item accept/reject, Phase 3 Reconcile flagged-item walk, Phase 4 Promote/Demote lifecycle gates, Phase 5 Prioritize reorder gates) MUST follow ../../contracts/deterministic-questions.md: render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options MUST be Discuss and Back, in that order. The Discuss-pause semantic is documented verbatim there -- on Discuss selection the agent MUST halt the in-progress sequence immediately, prompt What would you like to discuss?, and resume only on an explicit user signal. Implicit resumption is forbidden, and fallback chat replies MUST map only to the displayed number or exact displayed option text.

When to Use

• User says "refinement", "reprioritize", "refine", "roadmap refresh", or "refresh roadmap" (legacy v0.19 terms -- deft-directive-refinement is the current skill name)
• User says "triage", "action menu", "work the cache", or "pre-ingest" -- first-class Phase 0 direct triggers introduced under #845; they route to Phase 0 (Triage), not the general refinement entry
• New issues have accumulated since the last refinement session
• Periodic maintenance pass (e.g. weekly or after a batch of user feedback)
• User wants to review and organize the backlog

! Entry point (#1141, supersedes #845 / #883 action-menu). Phase 0 -- Triage-first consultation is the canonical entry point for any refinement session. Phase 0 consults task triage:summary (D2 / #1122) and task triage:queue --state=accept (D11 / #1128) and pulls the [RESUME]-tagged slice (D3 / #1123) FIRST. Refinement does NOT itself triage cached candidates -- that work belongs to ../deft-directive-triage/SKILL.md (D6 / #1130). Phase 0 ! MUST chain into Phase 1 -- Ingest on completion (or surface the empty-cache fallback prompt when the cache has not yet been bootstrapped -- see Phase 0a below). Phase 1+ semantics are unchanged.

Prerequisites

• ! xbrief/ directory exists with lifecycle folders (proposed/, pending/, active/, completed/, cancelled/)
• ! GitHub CLI (gh) is authenticated and can access the repo
• ~ PROJECT-DEFINITION.xbrief.json exists (run task project:render if missing)

Session Model

Refinement is a conversational loop, not a batch job. The user directs the flow:

• "Triage" / "action menu" / "work the cache" / "pre-ingest" -> Phase 0 (Triage-first consultation, #1141) -- refinement consults the cache; the canonical decision-making playbook is ../deft-directive-triage/SKILL.md (D6 / #1130)
• "Pull in issues" / "ingest" -> Phase 0 ALWAYS runs first to consult task triage:summary + task triage:queue --state=accept; Phase 1 follows on the cohort Phase 0b produces (#1141)
• "Show proposed" / "evaluate" -> Phase 2 (Evaluate)
• "Check origins" / "reconcile" -> Phase 3 (Reconcile)
• "Accept these" / "reject that" / "promote" / "demote" -> Phase 4 (Promote/Demote)
• "Reprioritize" / "reorder pending" -> Phase 5 (Prioritize)
• "Close out" / "scope is done" / "completion" -> Phase 6 (Completion Lifecycle)
• "Done" / "exit" -> Exit

The agent may suggest the next phase, but the user decides. Phases can be entered in any order and repeated.

Branch Setup (Preflight)

! Before making any changes, ensure you are working on a feature branch. This preflight runs before Phase 0 and again before Phase 1 if Phase 0 is auto-skipped.

1. ! Check if the working tree has uncommitted changes that would conflict -- stop and ask the user to resolve them first
2. ! Create or switch to a refinement branch (e.g. refinement/YYYY-MM-DD) if not already on one
3. ! Confirm the branch and working directory to the user before proceeding

Phase 0 -- Triage-first consultation (cache-first, #1141)

! Phase 0 is a thin consumer of the canonical triage cache: refinement consults task triage:summary (D2 / #1122) and task triage:queue (D11 / #1128) BEFORE walking any xbrief/ lifecycle folder. The dedicated triage playbook lives at ../deft-directive-triage/SKILL.md (D6 / #1130) -- refinement does NOT itself triage cached candidates; it consumes the queue's accept and [RESUME] slices and turns them into scope xBRIEFs.

! Phase 0 runs three sub-phases in canonical order: Phase 0a -- Triage gate -> Phase 0b -- Cache-first ingestion -> Phase 0c -- Resume conditions. Each sub-phase MUST run before the next, and Phase 0 MUST chain into Phase 1 -- Ingest on completion. Numbered prompts in Phase 0 ! MUST follow ../../contracts/deterministic-questions.md (Discuss / Back as the final two numbered options; Discuss-pause semantic applies verbatim).

See also (#883 Story 2): the unified cache (task cache:fetch-all --source=github-issue --repo OWNER/NAME) is the sole content-mirroring surface in v0.26.0+. Tier 1 reads MUST go through task cache:get -- github-issue OWNER/NAME/<N>. The legacy "Three-Tier Inventory Model" + action-menu walk that lived here pre-#1141 has moved out of refinement and into ../deft-directive-triage/SKILL.md (D6 / #1130); refinement now consumes the post-decision queue rather than producing decisions.

Phase 0a -- Triage gate (task triage:summary)

1. ! Invoke task triage:summary (D2 / #1122) and capture the one-liner.

2. ! Empty-cache backward-compat fallback. If the one-liner is the documented empty-cache prompt ([triage] cache empty -- run task triage:bootstrap), the agent ! MUST emit the verbatim recovery message to stderr BEFORE any folder scan:

   triage cache empty -- run `task triage:welcome` (N3 / #1143) to onboard, or `task triage:bootstrap` to seed the cache directly; refinement Phase 0 cannot consult the queue against an empty cache. Falling back to a legacy `xbrief/proposed/` folder scan only if you opt in.
   

   Then prompt the user Fall back to legacy folder-scan against xbrief/proposed/ for this session? [y/N] (default N). On N, exit refinement with the canonical deft-directive-refinement complete -- exiting skill. confirmation and the chaining instruction Run task triage:welcome (N3 / #1143) to onboard, then re-enter refinement.. On y, chain into Phase 1 against xbrief/proposed/ as the legacy fallback. ! MUST NOT silently proceed without surfacing the breadcrumb to task triage:welcome -- a fresh post-upgrade install needs that pointer to find the canonical onboarding ritual.

3. ! Outstanding-work gate. If the cache is populated AND any of untriaged, stale-defer (resume condition met), or in-flight is non-zero, surface the one-liner verbatim to the user with the canonical recommendation:

   triage cache has outstanding work -- recommend running `skills/deft-directive-triage/SKILL.md` (D6 / #1130) first. Proceed to refinement anyway? [y/N]
   

   ~ Default is N: deferring to the triage skill is the documented happy path because refinement consumes accept-decisioned candidates and an untriaged backlog means there are fewer accept rows than there could be. On N, exit with the canonical confirmation phrasing and the chaining instruction Run skills/deft-directive-triage/SKILL.md to clear the backlog, then re-enter refinement.. On y, proceed to Phase 0b.

4. ? When all counts are zero (cache populated, no outstanding work), proceed to Phase 0b without prompting.

⊗ Skip Phase 0a -- refinement on top of an untriaged cache wastes the operator's time on items the triage skill would have rejected, deferred, or marked needs-AC. ⊗ Bypass the empty-cache fallback prompt -- a silent proceed against an empty cache surfaces a misleading "no candidates" state and hides the upgrade-onboarding path from the operator.

Phase 0b -- Cache-first ingestion (task triage:queue --state=accept)

1. ! Pull the ingestion candidate list via task triage:queue --state=accept (D11 / #1128). Each row is a cached issue whose latest audit-log decision is accept -- the canonical "ready to become a scope xBRIEF" cohort. ! MUST NOT enumerate xbrief/proposed/ independently of the queue; the folder participates only via the join described in step 2.

2. ! Join the queue against xbrief/proposed/ (and the rest of the lifecycle folders) by references[].uri: queue rows whose issue is already represented by an existing xBRIEF surface as "already tracked"; queue rows with no matching xBRIEF are "new accept candidates". Items already in xbrief/proposed/ continue to participate -- they are joined against the cache rather than enumerated separately.

3. ~ When the join surfaces zero new candidates (every accept row already has a xBRIEF), Phase 0b is a clean no-op; chain straight into Phase 0c.

4. ! For each new candidate, fall through to Phase 1 -- Ingest, which delegates the actual scope-xBRIEF write to task issue:ingest. The intended single-verb form is task scope:promote --from-issue=<N> (#1136 / D18); until D18 lands, refinement chains the existing task issue:ingest + task scope:promote pair.

⊗ Walk xbrief/proposed/ directly as the primary ingestion surface -- the cache is the authoritative "what is ready to refine?" surface; the folder is the destination, not the source of truth. ⊗ Drop items that exist in xbrief/proposed/ but lack a matching cache row -- those are reconciled later (Phase 3 / origin reconciliation), not silently discarded.

Phase 0c -- Resume conditions ([RESUME]-tagged items first)

1. ! Before walking new untriaged candidates from Phase 0b, process every [RESUME]-tagged row in the queue. [RESUME] rows surface from D3 (#1123) when a prior defer audit entry's resume-on condition fires (atomics: ref:closed:#N, ref:merged:#N, date:>=YYYY-MM-DD, pending-count:>=N|<=N, composed by a single top-level AND or OR).
2. ! Stale-defer (resume-eligible) items take priority over fresh untriaged when both are present in the same Phase 0 pass -- the operator made a forward-dated decision on the deferred item and the framework is honouring it. Treat the [RESUME] slice as the FIRST class of candidates surfaced to the user.
3. ~ The exact precedence in task triage:queue is [ORPHAN] -> [RESUME] -> [URGENT] -> untriaged -> other (per D11 + D13 / #1132 grouping). Refinement consumes this order verbatim and surfaces [RESUME] candidates first; [ORPHAN] rows are out-of-scope for refinement (they are handled by the triage skill's audit phase).

⊗ Treat [RESUME] rows as "leftover" -- they are the highest-priority class refinement is meant to process, because the operator already decided to revisit them when the condition fired.

Pre-Phase-1 handoff

1. ! Surface a one-line session summary: {resume_eligible} resume-eligible, {new_accept} new accept candidate(s), {already_tracked} already tracked in xbrief/.
2. ! Chain into Phase 1 -- Ingest, which now operates on the cohort produced by Phase 0b's join ([RESUME] rows first, then new accept candidates).
3. ? If the user opts out of Phase 1 (e.g. "that's it for today"), exit via the Phase 0 mid-session exit surface below -- ! MUST NOT route to the ### EXIT block under ## PR & Review Cycle because that block is the post-PR-creation exit path and references a PR #{N} that does not yet exist at this point in the flow.

Phase 0 mid-session exit surface

! When the user opts out of Phase 1 after completing (or partially completing) Phase 0, perform exactly these steps -- ! MUST NOT mention any PR number, since none has been created yet:

1. ! Surface the outstanding-work tally: {resume_eligible} resume-eligible candidate(s) still pending, {new_accept} accept candidate(s) not yet ingested -- these will resurface on the next Phase 0 entry.
2. ! Note the audit-log location verbatim using double-backtick fencing so the inner path renders correctly: Audit log preserved at `xbrief/.eval/candidates.jsonl`; queue state is reproducible via `task triage:queue --state=accept`.
3. ! Confirm skill exit with the canonical phrasing: deft-directive-refinement complete -- exiting skill.
4. ! Provide the Phase-0-appropriate chaining instruction: Resume with `task triage:queue --state=accept` to inspect the queue, or re-enter the refinement skill when ready to continue. Do NOT reference a PR, a review cycle, or a monitor agent.

⊗ Skip Phase 1 silently after Phase 0 -- always render the chaining decision so the user knows the entry point shifted. ⊗ Mutate xbrief/proposed/ directly during Phase 0 -- only task issue:ingest (called from Phase 1) is allowed to write there; Phase 0 is read-only against the cache. ⊗ Route Phase 0 mid-session opt-out to the post-PR ### EXIT block under ## PR & Review Cycle -- that block surfaces a non-existent PR #{N} and confuses the user.

Phase 1 -- Ingest

! Scan external sources for new work items and create proposed scope xBRIEFs.

! Pre-filing master-diff check (#1102). When a refinement pass FILES a new GitHub issue that proposes ADDING a file or directory (rather than ingesting an existing issue), first run the pre-filing existence check from ../deft-directive-gh-slice/SKILL.md Step 5 -- git ls-tree origin/master -- <path> (or gh api repos/{owner}/{repo}/contents/{path}) -- so a stale "add file X" issue is never opened against state that already exists on master (the #1099 -> #1100 close-and-refile recurrence).

Step 1: Gather Sources

1. ? Scan non-GitHub sources (Jira, direct user requests, etc.) manually if applicable — those ingest paths are not yet task-wrapped
2. ! GitHub issues are ingested via the task wrapper documented in Step 3 — the task fetches open issues itself, so no separate gh issue list call is needed

Step 2: Deduplicate via References (Dry-Run Preview)

1. ? Run task issue:ingest -- --all --dry-run to preview which issues the ingest task would create scope xBRIEFs for. The task deduplicates candidates against references entries in existing xBRIEFs (across all lifecycle folders) so already-tracked issues are skipped automatically.
2. ! Present the user with the list of new-vs-already-tracked items the dry-run reports: "{N} new items found, {M} already tracked"
3. ! Wait for user approval before proceeding to ingest

Step 3: Ingest Approved Items

! Delegate ingest to task issue:ingest — the task is the canonical implementation of scope-xBRIEF creation. Skills MUST NOT reinvent the slug rules, reference shape, or deduplication logic inline (see #537 for background).

• Single issue: task issue:ingest -- <N> — creates xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json with origin references, canonical slug from scripts/slug_normalize.py (see ../../conventions/vbrief-filenames.md), and schema-conformant shape.
• Batch: task issue:ingest -- --all [--label <L>] [--status <S>] — ingests every open issue matching the filters, skipping duplicates by references.uri match.
• Preview: add --dry-run to either form to preview without writing files.

The task emits xBRIEFs conforming to the canonical v0.6 schema (xbrief/schemas/xbrief-core.schema.json) with origin references in the form documented in ../../conventions/references.md:

"references": [
  {
    "uri": "https://github.com/{owner}/{repo}/issues/{N}",
    "type": "x-xbrief/github-issue",
    "title": "Issue #{N}: {issue title}"
  }
]

• ! New scope xBRIEFs MUST target "xBRIEFInfo": { "version": "0.6" } (the task handles this automatically)
• ! plan.status starts at "proposed"; the task sets this
• ! Conform to xbrief/schemas/xbrief-core.schema.json (v0.6) -- the task validates before writing
• ~ After ingest, review the generated xBRIEFs with the user before promoting any of them to pending/

⊗ Hand-author scope xBRIEFs inside the skill when the ingest task exists — duplicating the narrative logic is how #534 (non-conformant references) and #537 (drift between skill and task) arise ⊗ Write references with url/id/bare github-issue types — use the schema-conformant {uri, type, title} shape above ⊗ Ingest an item that already has a matching xBRIEF reference -- task issue:ingest handles deduplication; skills MUST NOT duplicate that logic inline

Phase 2 -- Evaluate

! List proposed items for interactive user review.

Step 1: List Proposed Items

1. ! Read all xBRIEFs in xbrief/proposed/
2. ! Present each item with:
   • Title and filename
   • Origin link(s) from references
   • Summary from narratives (if populated)
   • Labels/category (if available from origin)
3. ! Sort by creation date (oldest first) or as user prefers

Step 2: Interactive Review

! For each proposed item (or batch, as user directs):

• ! Present the item and wait for user decision
• ~ The user may: accept (promote to pending), reject (cancel), defer (keep in proposed), or request more detail
• ! Do not proceed to the next item until the user responds
• ? The user may batch-accept or batch-reject multiple items at once

⊗ Auto-accept or auto-reject proposed items without user review

Phase 3 -- Reconcile (RFC D12)

! Check if linked origins have changed since the xBRIEF was last touched. Delegate the scan to task reconcile:issues and walk the user through flagged items for approval (see #537 for why the skill is a thin wrapper over the task).

Step 1: Run the Reconciler

task reconcile:issues

The task scans every xBRIEF with a GitHub-backed reference (whether the reference uses the legacy github-issue bare type or the canonical x-xbrief/github-issue shape), fetches each linked issue, compares timestamps and state, and reports items in four buckets:

• Linked & current — origin has not changed since the xBRIEF was last updated (no action)
• Stale — origin updatedAt is newer than the xBRIEF (propose an update)
• Externally closed — origin issue is CLOSED (propose cancellation or reconcile if intentional divergence)
• Unlinked — xBRIEF has no GitHub reference (flag for review)

Step 2: Walk Flagged Items with the User

1. ! For each stale item the task surfaces, show the user the diff between the current xBRIEF and the refreshed origin. Propose edits; ! wait for explicit user approval before writing anything.
2. ! For each externally closed item, ask the user whether to task scope:cancel <file> it or preserve intentional divergence.
3. ! For each unlinked item, ask whether to attach an origin reference or leave the xBRIEF as-is.

Step 3: Apply User-Approved Updates

• ! Agent proposes edits; ! user approves each change
• ! Never auto-update xBRIEFs — intentional divergence (xBRIEF refined beyond original issue scope) must be preserved
• ! For approved updates, update the xBRIEF content and xBRIEFInfo.updated timestamp; prefer the task commands (task scope:cancel, task scope:block, etc.) over hand-editing where they apply

⊗ Replace the task invocation with a hand-written gh issue view loop — the task is the canonical implementation; skills MUST NOT duplicate it (#537) ⊗ Auto-update xBRIEFs based on origin changes without user approval ⊗ Overwrite intentional divergence -- if a xBRIEF has been refined beyond the original issue, preserve the refinement

Origin sync after material xBRIEF edits (#2540)

! When this refinement pass materially updates an origin-linked scope xBRIEF (AC, plan.status, or plan.items statuses/titles), run task issue:sync-from-xbrief -- <path> to post a sync comment on the linked GitHub issue so the human-facing tracker stays current. Use --dry-run to preview the comment without posting.

! If sync is intentionally skipped (offline, issue frozen, divergence is deliberate), document the skip reason in the session notes or PR body — do not silently leave the origin stale.

⊗ Materially edit an origin-linked xBRIEF without running issue:sync-from-xbrief or documenting why it was skipped

Phase 4 -- Promote/Demote

! Move xBRIEFs between lifecycle folders using deterministic task commands. The status values below align with the canonical v0.6 Status enum (draft | proposed | approved | pending | running | completed | blocked | failed | cancelled) — note that failed is also a valid terminal transition for active work that could not complete.

Available Commands

• task scope:promote <file> -- proposed/ -> pending/ (status: pending)
• task scope:activate <file> -- pending/ -> active/ (status: running)
• task scope:complete <file> -- active/ -> completed/ (status: completed)
• task scope:cancel <file> -- any -> cancelled/ (status: cancelled)
• task scope:restore <file> -- cancelled/ -> proposed/ (status: proposed)
• task scope:block <file> -- stays in active/ (status: blocked)
• task scope:unblock <file> -- stays in active/ (status: running)
• task scope:fail <file> (v0.6+) -- active/ -> completed/ (status: failed) — record a failure terminal state when a scope cannot complete but should not be cancelled
• task scope:undo <decision_id> (D15 / #1134) -- reverse a single scope-lifecycle audit entry (demote -> re-promote, cancel -> restore-from-cancelled-to-prior-folder, restore -> re-cancel); terminal actions (complete / fail) are REFUSED -- use git revert or hand-edit
• task scope:undo --batch-id=<uuid> (D15 / #1134) -- reverse every audit entry tagged with the batch_id (e.g. the cohort produced by task scope:demote --batch); idempotent on already-undone entries; the undo cohort is itself reversible via the undo_batch_id minted on the new entries. Optional --dry-run previews without writing.
• task scope:undo --latest (D15 / #1134) -- reverse the most-recent reversible audit entry (demote / cancel / restore / undo) not already undone; convenience form used by the N6 / #1146 smoketest contract.

Workflow

1. ! Execute transitions using the task commands above -- they handle plan.status updates, plan.updated timestamps, and file moves atomically
2. ! Derived-artifact renders (task roadmap:render, task project:render) happen after a batch of promotions/demotions, not after each individual item. During high-volume triage (e.g. dozens of accept/reject decisions in one session), defer both renders until the end of the batch -- the source of truth is the lifecycle folder contents under xbrief/, so ROADMAP.md and PROJECT-DEFINITION.xbrief.json can be refreshed once per batch without losing correctness.
3. ! task roadmap:render regenerates ROADMAP.md from the updated lifecycle folder contents. Call it once per batch (typically at the end of Phase 4, before handing back to the user or transitioning to Phase 5), not after every single promote/demote.
4. ! task project:render refreshes the PROJECT-DEFINITION items registry. Call it once per refinement pass -- usually at the end of the session alongside the final roadmap render -- unless the user explicitly needs an intermediate registry refresh. It is not a per-edit tax.
5. ! Before the user is shown the final backlog state (end of Phase 4, end of Phase 5, or session exit), both task roadmap:render AND task project:render MUST have been run at least once so ROADMAP.md and PROJECT-DEFINITION.xbrief.json reflect the current lifecycle folder truth. This preserves correctness while allowing N promotions/demotions to share one render checkpoint.
6. ! Mark rejected items as cancelled via task scope:cancel (never delete xBRIEFs)

~ Operationally: a large refinement session can ingest/evaluate/promote multiple issues and close out with one final render checkpoint, rather than N repetitive renders after every individual item.

⊗ Rerender derived artifacts (task roadmap:render, task project:render) after every single accept/reject/promote/demote during high-volume triage -- batch the lifecycle edits and render once at the end of the batch ⊗ Move xBRIEFs between folders manually (cp/mv) -- always use task scope:* commands ⊗ Delete xBRIEFs -- use task scope:cancel to preserve history

Phase 5 -- Prioritize

! Reorder and organize the pending backlog.

1. ! List all xBRIEFs in xbrief/pending/ with titles, origins, and any phase/dependency metadata
2. ~ Help the user set phases and dependencies:
   • Group related items into phases (via xBRIEF items hierarchy or tags)
   • Identify dependencies between items (via edges in xBRIEF schema)
3. ! task roadmap:render is the checkpoint before showing the reordered backlog to the user -- not a per-edit tax. Run it ONCE at the end of the reorder pass to regenerate ROADMAP.md from the updated pending/ contents. Do not invoke it after each individual reorder action.
4. ~ Present the regenerated roadmap summary to the user for confirmation

Phase 6 -- Completion Lifecycle

! On scope completion, update origins to close the loop.

When a Scope Completes

1. ! Read the completed xBRIEF's references array
2. ! For each GitHub-issue reference (either the legacy bare github-issue type or the canonical x-xbrief/github-issue shape):
   • Close the issue with a comment linking to the implementing PR:

     gh issue close {N} --comment "Completed via PR #{PR} -- scope xBRIEF: {filename}"
     

   • The issue number is extracted from the reference uri (e.g. https://github.com/o/r/issues/{N})
3. ? For other reference types (x-xbrief/jira-ticket, x-xbrief/user-request, x-xbrief/github-pr, etc.), follow the appropriate update mechanism
4. ! Update PROJECT-DEFINITION via task project:render

⊗ Complete a scope without updating its origins ~ Completion lifecycle can be triggered during refinement or as a standalone action after a PR merge

! When the refinement session files a new umbrella issue (or surfaces one whose current-shape comment is missing), file the umbrella then file its ## Current shape (as of pass-N) comment per ## Umbrella current-shape convention in AGENTS.md (#1152) -- the edit-in-place comment is the canonical surface every subsequent design pass updates.

! Before reporting an umbrella or epic's current status to the operator (what is done, what blocks, wave order), fetch repos/<owner>/<repo>/issues/<N>/comments via REST, read the ## Current shape (as of pass-N) comment and any linked context/LockedDecisions xBRIEF — never conclude status from the issue body alone (claim-cites-state-surface, #2066).

~ Issue-label hygiene for any umbrella or child issue this skill files: before creating issues, inspect the target repo's existing labels with gh label list or the labels API; choose one or more suitable existing labels when practical, or explicitly note that no label was applied. This is a recommendation, not a gate -- do not block issue creation solely because no label fits, and do not invent ad hoc labels outside the repo's existing label set.

! When a refinement pass produces a slicing event (rare but possible -- e.g. a design pass on an existing umbrella files N additional Wave-N child issues), record the cohort in xbrief/.eval/slices.jsonl via scripts/slice_record.py::write_slice(...) with actor="skill:refinement" immediately after the children are filed (#1132 / D13). Same call shape as skills/deft-directive-gh-slice/SKILL.md Step 6. The cohort record is what makes task triage:audit --orphans able to detect Wave-2+ children whose umbrella closes prematurely; without it the production-side drift this surface guards against re-fires. Skip when the pass produced no new child cohort (e.g. a pure re-prioritization).

! When the umbrella + children were filed by hand (legacy gh issue create / issue_write MCP / prior pass-N runs that pre-date this skill's slicing phase), use the canonical retro verb task slice:record-existing (#1147 / N7) -- it wraps the same slice_record.write_slice helper with actor="manual:operator", takes --umbrella=N --children=A,B,C [--wave-N=...] flags, validates each issue via the N5 / #1145 scm.call shim, and is idempotent on a matching umbrella + child set (re-run is a no-op; --force writes a second record for legitimate multi-session slicing). Companion task slice:list enumerates persisted slices for verification. The backfill verb is the canonical retro path for cohorts D13's writer never saw.

CHANGELOG Convention

• ! Write ONE batch CHANGELOG.md entry at the END of the full refinement session -- not one entry per xBRIEF created or promoted. The batch entry summarizes all changes made during the session.
• ⊗ Add a CHANGELOG entry after each individual action during refinement -- wait until the full session is complete and write a single summary entry.

PR & Review Cycle

After all refinement work is complete:

1. ! Ask the user: "Ready to commit and create a PR?"
2. ! Wait for explicit user confirmation before proceeding.

Pre-Flight (before pushing)

! Run all pre-flight checks BEFORE committing and pushing:

1. ! Verify CHANGELOG.md has an [Unreleased] entry covering the refinement changes
2. ! Run task check -- all checks must pass
3. ! Verify .github/PULL_REQUEST_TEMPLATE.md checklist is satisfiable for this PR. If the file is missing, do NOT block — copy the canonical template from templates/PULL_REQUEST_TEMPLATE.md (ship-with-deft) to .github/PULL_REQUEST_TEMPLATE.md in the consumer project, then proceed with pre-flight (#531). If the file exists but contains unsatisfiable checklist items for this PR, call them out to the user before pushing.
4. ! Mandatory file review: Re-read ALL modified files before committing. Explicitly check for:
   • Encoding errors (em-dashes corrupted to replacement characters, BOM artifacts)
   • Unintended duplication (accidental double xBRIEFs or duplicate entries)
   • Structural issues (malformed xBRIEF JSON, broken references)
   • Semantic accuracy (verify that counts and claims in CHANGELOG entries match the actual data)

Commit, Push, and Create PR

1. ! Commit with a descriptive message: docs(xbrief): refinement session -- {summary}
2. ! Push the branch to origin
3. ! Create a PR targeting the appropriate base branch

Review Cycle Handoff

! After the PR is created, automatically sequence into skills/deft-directive-review-cycle/SKILL.md.

• ! Inform the user: "PR #{N} created -- starting review cycle."
• ! Follow the full review cycle skill from Phase 1 (Deft Process Audit) onward.

EXIT

! When the review cycle completes (exit condition met) or the PR is ready for human review:

1. ! Explicitly confirm skill exit: "deft-directive-refinement complete -- exiting skill."
2. ! Provide chaining instructions to the user/agent:
   • If review cycle is complete and PR is approved: "PR #{N} is ready for human merge review."
   • If review cycle is still in progress: "Review cycle handed off to deft-review-cycle. Monitor PR #{N} for Greptile findings."
   • If returning to a monitor agent: "Returning control to monitor agent -- refinement PR #{N} created and review cycle initiated."
3. ! Do NOT continue into adjacent work after this point -- the skill boundary is an exit condition.

Anti-Patterns

• ⊗ Bypass Phase 0 by walking xbrief/proposed/ or gh issue list directly -- task triage:queue --state=accept (D11 / #1128) is the canonical ingestion-candidate surface (#1141)
• ⊗ Skip Phase 0a's task triage:summary invocation -- the triage-gate decision (run the triage skill first vs proceed) depends on its output (#1141 / D2 / #1122)
• ⊗ Silently proceed against an empty cache -- emit the canonical task triage:welcome (N3 / #1143) breadcrumb to stderr first (#1141)
• ⊗ Treat [RESUME]-tagged items as leftover -- they are the highest-priority class refinement processes (#1141 / D3 / #1123)
• ⊗ Skip Phase 1 silently after Phase 0 -- always render the chaining decision so the user knows the entry point shifted (#1141, supersedes #845)
• ⊗ Auto-accept or auto-reject proposed items without user review
• ⊗ Create xBRIEFs without origin provenance (references linking to the source)
• ⊗ Ingest items without deduplicating against existing xBRIEF references first
• ⊗ Auto-update xBRIEFs based on origin changes -- user approves all updates
• ⊗ Overwrite intentional divergence when reconciling stale origins
• ⊗ Move xBRIEFs between folders manually -- always use task scope:* commands
• ⊗ Delete xBRIEFs -- use task scope:cancel to preserve history
• ⊗ Complete a scope without updating its origins (closing issues, posting comments)
• ⊗ Skip deduplication during ingest -- always diff against existing references
• ⊗ Add a CHANGELOG entry per individual action during refinement -- write one batch entry at the end of the full session
• ⊗ Proceed to the next proposed item without waiting for user decision during evaluate
• ⊗ Auto-push without explicit user instruction
• ⊗ Rerender ROADMAP.md or PROJECT-DEFINITION.xbrief.json after every single accept/reject/promote/demote during high-volume triage -- task roadmap:render and task project:render are batch checkpoints, not per-edit taxes, and calling them N times for N lifecycle edits turns O(1) render work into O(N) without changing correctness (see #638)
• ⊗ Return a final backlog view to the user without having run task roadmap:render and task project:render at least once since the last lifecycle edit -- batch the renders, but do not skip them

See also

• Upstream skill: ../deft-directive-triage/SKILL.md (D6 / #1130) -- the canonical triage hygiene + queue selection playbook. Refinement Phase 0a consults task triage:summary (D2 / #1122) and Phase 0b consumes task triage:queue --state=accept (D11 / #1128), both of which are produced by the triage skill's decision flow. [RESUME]-tagged items (Phase 0c) originate from D3 (#1123) --resume-on conditions documented in the triage skill's Phase 3.
• Reversibility verb in Phase 4: task scope:undo <file> (D15 / #1134).
• Onboarding (empty-cache fallback target): task triage:welcome (N3 / #1143) -- the single chained command a fresh post-upgrade install runs before re-entering refinement.
• Refs: #1141 (this rewrite), #1119 (umbrella), #1122 (D2), #1128 (D11), #1123 (D3), #1130 (D6), #1134 (D15), #1143 (N3), #1149 (N9 routing).