pm-organize

What this skill does

# PM Organize

Placement is the **second half of intake**: pm-triage makes an issue *workable* (type + exec-mode label); pm-organize makes it *placed* (status + location). An issue that has been triaged but not placed is typed, labeled, and structurally sound — but it has no workflow status, no project home, no parent, and no assigned owner. pm-organize closes that gap.

## Usage

```
/pm-organize [<issue-id>]
```

- `<issue-id>` *(issue key e.g. `FUNC-12`, optional)* — the issue to place; omit to work the set of triaged-but-unplaced issues.

Writes are tiered: auto-safe changes (status, existing-workstream label) are applied on one confirmation; reversible changes (project/milestone/parent) are shown and applied on confirm; always-confirm changes (assignee reassignment, new-workstream creation, new-project creation) are surfaced as proposals and require an explicit separate OK.

## When to use this

- An issue has been triaged (typed + labeled by pm-triage) but is still unplaced — no status, no project home, no assigned owner.
- The operator says "where does this issue belong", "assign FUNC-12", "place this in the right project", "/pm-organize".

**When not to use it.** If the issue is already placed (has a status + project + assignee that reflect current intent), running pm-organize produces noise. If the issue lacks a type tag or exec-mode label (is still raw / untriaged), run pm-triage first — pm-organize assumes the issue is workable. If you want *only* to change a type tag or execution mode, that is pm-triage, not this skill.

## The five dimensions and write-safety tiers

| Dimension | Tier | What it means |
|---|---|---|
| **Status** | auto-safe | Set or advance the workflow status. Applied in default mode. (Linear only — GitHub returns `TRACKER_UNSUPPORTED` for `--status`; surface as a manual step on GitHub.) |
| **Existing-workstream label** | auto-safe | Add a workstream label that already exists in the tracker. Applied in default mode. |
| **Project** | reversible | Move the issue into a project. Shown always; applied on confirm or in autonomous mode. |
| **Milestone** | reversible | Set or change the milestone. Shown always; applied on confirm or in autonomous mode. |
| **Parent** | reversible | Link to a parent issue. Shown always; applied on confirm or in autonomous mode. |
| **Assignee reassignment** | always-confirm | Change who owns the issue. Never auto-applied — always a separate explicit confirmation. |
| **New-workstream creation** | always-confirm | Apply a workstream label that does not yet exist. Never auto — requires the operator to confirm the new label should be created. |
| **New-project creation** | always-confirm | Assign to a project that does not yet exist. Never auto — route to `pm-projects` to create it first. |

These tiers map directly to `placement-resolver.tierFor`:
- `tierFor('status')` → `'auto-safe'`
- `tierFor('workstream-existing')` → `'auto-safe'`
- `tierFor('project')` → `'reversible'`
- `tierFor('milestone')` → `'reversible'`
- `tierFor('parent')` → `'reversible'`
- `tierFor('assignee')` → `'always-confirm'`
- `tierFor('workstream-new')` → `'always-confirm'`
- `tierFor('project-new')` → `'always-confirm'`

## Workflow

Steps 1-4 are read-only and run without confirmation. Step 5 is the only write, and it is always confirmation-gated.

### Step 1 — Fetch the issue fresh

Read from the tracker — not the cache. Cache state can lag (stale labels, outdated status) and placement decisions hinge on current state.

- Linear: `node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-cache.js" verify-issue --slug <slug> --id <ID>` — reads the single issue fresh from Linear and returns it under the `fresh` key (alongside `cached` and a `divergence` array). Read placement state from `fresh`, not `cached`.
- GitHub: `gh issue view <NUM> --repo <org/repo> --json assignees,labels,milestone,projectCards,state,title,body,parentIssue`.

If the tracker is unreachable, stop with a transport error.

### Step 2 — Load conventions and parse the workstream scheme

Read `<repo>/.claude/pm/conventions.md`. Extract the `## Workstreams` section body and parse it:

```javascript
const { extractSections } = require(process.env.CLAUDE_PLUGIN_ROOT + '/hooks/lib/markdown-utils');
const { parseWorkstreamScheme } = require(process.env.CLAUDE_PLUGIN_ROOT + '/hooks/lib/placement-resolver');
const sections = extractSections(conventionsMarkdown);
const scheme = parseWorkstreamScheme(sections['Workstreams'] || '');
// scheme is { mode: 'prefix'|'enumerated'|'none', prefix, names }
```

If the conventions file is absent or has no `## Workstreams` section, `scheme.mode` is `'none'` — the workstream dimension is disabled; omit it from the proposal.

### Step 3 — Compute placement candidates deterministically

Use the resolver and roster libraries — do not invent heuristics inline:

**Workstream:**

```javascript
const { currentWorkstream, availableWorkstreams } = require('.../placement-resolver');
const ws = currentWorkstream(issue.labels, scheme);          // string | null
const candidates = availableWorkstreams(corpusLabels, scheme); // string[]
// corpusLabels = all labels seen across the project's issues (from the cache)
```

**Project candidates:**

```javascript
const { candidateProjects } = require('.../placement-resolver');
const projects = /* slug-keyed map from portfolio cache / portfolio-discovery */;
const cands = candidateProjects(issue, projects);
// [{ slug, name }] — team-matching projects, current project excluded
```

If no portfolio data is available, the project dimension degrades gracefully — note "recommend `/pm-setup --portfolio`" in the proposal.

**Parent candidates:** candidate parents are other open issues in the same project or team. Select the most plausible (e.g., epics or initiatives that share the workstream or title keywords). No resolver function is needed — use judgment.

**Assignee candidates:**

```javascript
const r = require('.../team-roster');
const cs = require('.../cache-store');
const curated = r.parseTeamMd(fs.existsSync(teamMdPath) ? fs.readFileSync(teamMdPath, 'utf8') : '');
const cache = cs.readTeam(slug) || { members: [] };
const { roster } = r.mergeRoster(curated, cache.members);
const ranked = r.rankAssignees({ title: issue.title, labels: issue.labels, workstream: ws }, roster);
// ranked[0] is the top recommendation — { handle, score, reasons }
```

### Step 4 — Build the placement proposal

Combine all dimensions into the proposal format shown below. Mark each dimension with its tier from `tierFor`. See **Placement proposal — output format**.

### Step 5 — Apply

Show the proposal. On the operator's confirmation:

- Apply the **auto-safe tier** via `pm-issue.js update` (status + existing-workstream label).
- In autonomous mode, also apply the **reversible tier** (project/milestone/parent) in the same or a follow-up update call.
- **Never auto-apply** assignee reassignment, new-workstream creation, or new-project creation — surface those as proposals and require an explicit separate confirmation.

For a single issue, one confirmation covers the auto-safe tier; the reversible tier is a second confirm; always-confirm dims are each their own explicit OK. For a batch, assemble all proposals into one summary and confirm once per tier class.

## Applying placement

The exact commands to apply each dimension:

```bash
# status (Linear only — GitHub returns TRACKER_UNSUPPORTED; surface as a manual step on GitHub)
node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-issue.js" update --id <ID> --status "<state name>"

# existing-workstream label
node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-issue.js" update --id <ID> --add-label "<ws-label>"

# reversible tier (confirm / autonomous mode — combine flags in one call)
node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-issue.js" update --id <ID> --project "<name>" --milestone "<name>" --parent "<parent-id>"

# assignee (ALWAYS confirm — never autonomous)
node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-issue.js" upda