unfold git:20260926.7121c86A

Immutable. This exact content never changes and is served at /api/v1/blob/ec808ee0d9f573da.

---
name: unfold
description: |
  This skill should be used at the two moments in multi-PR / multi-project
  work where a hand belongs on the unit's chart in Linear: "이 길로 가는 이유
  기록" / "결정 남겨줘" / "log this decision" (decide), "열린 것들 축으로
  묶어줘" / "축 정리" / "collapse the open questions" (group). Also applies
  without being named: when the accumulated context and the utterance show an
  intent to write to a repository, the unit's chart is read before the first
  write — matched against the catalog of project root issues, that one chart
  and nothing beside it. Writes ONLY structure and decisions, never status.
  Invoked as /unfold [moment] [project].
---

# Unfold — Writing the unit's chart in Linear

A unit of work has a chart outside the codebase: its project's root issue in
Linear, whose five sections say what is wanted, why, under which constraints,
and what is still open, and whose decision comments say where the direction
stands now. This skill covers the two moments where a human hand belongs on
that chart: a decision and a regrouping of the open set.

Reading the chart on its own is outside this skill; the adopting host carries
that on its always-loaded surface. What is here is the convention for writing
— the shape of a decision line, what the cull drops, the state/structure
boundary — and the read each write needs first.

## Core rule — pace layering

- **Write only structure and decisions**: new workstream issues, `blockedBy`
  edges, runbook documents, one-line decision comments, a regrouped Open
  questions section and the relocation of an item that regrouping releases —
  into another section of the same root description, or into the issue or
  document that item belongs to.
- **Read at need, never cache-and-trust**: issue status and milestone progress
  % are system-maintained. Dependency edges are not — they are stored
  structure, written by hand under the bullet above. A write reads what it is
  about to change, immediately before changing it.
- **Never hand-write state**: do not set issue status, milestone completion,
  or live-system facts (deploy/image existence) in Linear. Status flows from
  PR events; live facts are read from their source (CI, registry, ArgoCD)
  at need. Hand-mirrored state drifts, and stale state read back as "the
  whole picture" pollutes downstream judgment. Sole exception: the initial
  state of a backfilled issue — one created for work finished before the
  issue existed — is set once at creation, because no PR event will ever
  fire for it; this is a one-time creation fact, not ongoing mirroring,
  and automation owns the state from then on.

## Invocation

`/unfold [moment] [project]` — both arguments optional.

| Moment | Aliases (EN / KO) | Kind |
|---|---|---|
| `decide` | decision, path, 결정, 왜 이 순서 | **write** (one comment) |
| `group` | axes, collapse, regroup, 축 정리, 정렬, 묶기 | **write** (open-set regroup) |

- No moment argument: infer from the utterance. A direction being chosen is
  `decide`; an accumulated open set being collapsed into axes is `group`.
  Genuinely ambiguous → name the candidates and ask once.
- Korean voice input is expected — match aliases semantically, not literally.
- **Write-intent trigger.** When the accumulated context and the utterance
  show an intent to write to a repository — an edit, a branch, a worktree, a
  spawn — and no chart is open for that unit yet, the unit's chart is read
  before the first write, resolved by catalog match (below). Recognizing that
  intent is the work, so the trigger belongs where the intent forms, not where
  a write executes: this skill states the trigger and delivers it nowhere, and
  a host that wants it to fire unasked binds it on an always-loaded surface of
  its own.
- **When a PR merges, the chart it names is tidied in the same pass.**

## Project resolution

Resolve the target Linear project in this order; never hardcode project IDs:

1. Explicit `[project]` argument (name, ID, or slug).
2. Infer from the working repo: take the git repo directory name (and, if
   present, the current worktree/branch's issue identifier like `FD-123`) and
   query Linear (`list_projects` with a name query, or `get_issue` on the
   identifier and read its project).
3. **Catalog match** (the write-intent path, and the fallback when 1–2 give
   nothing): the catalog is the root issues of the user's projects — the
   in-progress projects first, plus a root issue the accumulated context and
   utterance make plainly relevant even though its project is not in
   progress. Match the intent against that catalog; one match opens that
   chart. No match: propose a new root issue for the unit as a structure
   write, draft first — never open a neighbour's chart instead.
4. Still ambiguous: list the candidates and ask once. The resolved chart is
   reused while the write target and the intent stay the same unit; a switch
   to another repository or another unit re-runs the match, because a chart
   that is open is not thereby the chart this write belongs to.

## Tool loading

Linear MCP tools are deferred in most sessions. Before the first call, load
schemas via ToolSearch, e.g.
`select:mcp__claude_ai_Linear__list_projects,mcp__claude_ai_Linear__list_issues,mcp__claude_ai_Linear__get_issue,mcp__claude_ai_Linear__list_comments,mcp__claude_ai_Linear__list_documents,mcp__claude_ai_Linear__save_comment,mcp__claude_ai_Linear__save_issue,mcp__claude_ai_Linear__save_document`
(load only what the moment needs; exact server prefix may differ — discover
with a keyword search on "linear" first when unsure).

## Moment routing (summary)

Detailed per-moment procedures and write templates live in
`references/moments.md` — consult it when executing a moment. Summary:

| Moment | Reads | Writes | Emit |
|---|---|---|---|
| `decide` | the chart (root issue description + decision comments), then the anchor the decision belongs to | `save_comment` | one-line decision log, at the moment the direction changes (draft → cull → write) |
| `group` | the chart's open items and its decision comments, in order, plus the body of each relocation destination before changing it | `save_issue` (root description) / `save_issue` or `save_document` (a released item's destination) | axes each naming what it absorbed + every non-axis classified as projection or different-object, with its disposition → cull → rewritten Open questions |

## Output discipline

- Every write moment drafts first and culls the draft before anything is
  written. Where the adopting host's always-loaded surface grants standing
  authorization for that write — an approval given when the work was set up,
  or a class of writes the host lets proceed — the session applies the cull,
  writes, and reports what was written. Otherwise the draft is shown and
  written only on user confirmation (a decision comment and a regrouped open
  set are outward, team-visible acts), and the
  user culls it. In both branches three reasons drop a line: it is derivable by reasoning from what is already recorded, it
  is the product of a mechanical fix rather than a choice, or it does not
  match the unit's intent. Derivability drops an assertion, never a
  representation a moment is required to produce: a `group` axis and the list
  of what it absorbed are derivable from the originals by construction, and
  that is what they are for. Only the slow layer is written — structure and
  decisions — never a state the next read would refresh anyway.
- When the pre-write read reveals stale structure (an edge or runbook
  contradicting reality), surface it as a proposed structure fix — do not
  silently rewrite.

## Additional Resources

- **`references/moments.md`** — the pre-write chart read, the `decide` and
  `group` procedures, decision-comment and axis-collapse templates, and the
  field caveats that bound what may be written.