comment

Files (1)

• SKILL.md

SKILL.md (first lines)

# comment

Post structured comments to Linear issues. This skill owns the **how** of commenting — formatting, provenance, threading. Calling skills own the **what** — when to comment and what content to include.

> **Why this protocol exists.** An issue page shows every top-level comment expanded. One top-level comment per event (assessment, spike, plan, CI result) turns the page into a wall the reader has to scroll through to make sense of. Replies fold under their thread, and a resolved thread folds away entirely. So: few top-level comments, each a thread that can be closed, and everything else a reply.

> **Sync note:** Every skill that posts comments delegates here and must not contradict this protocol: `pair`, `issue`, `align`, `design`, `pr`. When the protocol changes, check those skills for wording that still describes the old shape.

## Protocol

```
Issue comments:
├── T1: redesign the auth flow          ← current thread: general work
│   ├── Assessment
│   ├── Plan
│   ├── Step 1 complete
│   └── ✅ Summary: what was tried, how it ended   → human resolves
├── T2 Spike: does the SDK support PKCE ← typed thread: its own question
│   └── ✅ Answer                                  → human resolves
└── T3: rework after review             ← next current thread
    └── …
```

### Vocabulary

- **Description** — the issue's own text. Not a comment.
- **Thread** — a top-level comment plus the replies under it.
- **Top-level comment** — the comment that starts a thread. Its first line is the thread's title.
- **Reply** — a comment posted under a top-level comment, via `parentId`.

### Thread titles

Every top-level comment is titled `T{n}[ {Type}]: {one-line summary}`:

- **`T{n}`** — one sequence per issue, shared by all threads. The next thread takes the highest existing number + 1, counting resolved threads too. `T`, not `#`, because a bare `#85` already reads as a PR number.
- **Type** — optional. General work has none. Anything else names what the thread is, e.g. `Spike`, `Fix`, `Refactor`. These are examples, not an enforced list.
- **Summary** — one line saying what the thread is about, not what happened in it.

Example titles: `T1: redesign the auth flow`, `T2 Spike: does the SDK support PKCE`, `T3 Fix: token refresh drops the session`. These are the title alone; the heading line wraps it in bold and appends `(skill: {caller-skill})` (see **Comment anatomy**).

**The current thread** is the highest-numbered unresolved thread with no type. It is where anything without a better home goes.

Issues that predate this protocol have top-level comments without a `T{n}` title. Treat unresolved ones as routing candidates, never as the current thread, and start numbering at `T1`.

### Comment anatomy

Every comment has three parts:

1. **Heading line:** for a top-level comment, `**T{n}[ {Type}]: {summary}** (skill: {caller-skill})`; for a reply, `**{Title}** (skill: {caller-skill})`. Spell out `skill:` — a bare `(pair)` means nothing to a reader who doesn't know the skill names
2. **Provenance line:** `*[ai:claude-code]*`
3. **Body:** the content, in markdown

Example top-level comment, with every part present — number, type, summary, caller skill, provenance and body:

```markdown
**T2 Spike: does the SDK support PKCE** (skill: pair)

*[ai:claude-code]*

**Verdict:** Feasible, with caveats.
```

Example reply:

```markdown
**Assessment** (skill: pair)

*[ai:claude-code]*

**Clear and ready:**
- Add Google OAuth callback endpoint
- Store refresh tokens in existing session table
```

### Reading the threads

Routing needs to know which threads exist and which are open. `list_comments` returns every comment with its `parentId` (`null` for a top-level comment) and `resolvedAt` (`null` while open). Read it in full:

- **At session start, read greedily.** One full `list_comments` read of the issue, before the first comment. Prefer spending the tokens over misreading the situation.
- **Within a session, trust the context.** Once the threads and their IDs are in view, reuse them. Read again only if the context was compacted and the IDs are gone. Parallel sessions on one issue are rare by design, so no re-read before each post.

**Where the tokens go.** `list_comments` cannot filter to top-level comments: it returns every reply with its full body, and long bodies make the read expensive on a busy issue. When that cost matters, hand the read to a subagent and have it return only an index: number, title, comment ID, resolved or not, date of the last reply. The default is still the greedy read.

### Routing a comment

Before posting, decide where the comment goes. This is one self-contained choice, so a fast judgment model (e.g. a System One model such as TypeSafe's Jev) could take it over later:

- **Input:** the draft comment, and the unresolved threads (title plus a line of their latest content).
- **Output:** one thread, or **none of the above**.

Then:

| Outcome | Action |
|---|---|
| A thread fits the topic | **Reply** in that thread |
| Nothing fits, and the content is routine progress | **Reply** in the current thread |
| Nothing fits, and the topic may deserve its own conversation | **Ask the user** whether to open `T{n+1} {Type}: …` or reply in the current thread. With no user present (walk-away, managed agent), reply in the current thread and say in the body that it may deserve its own thread |
| No current thread exists (new issue, or all resolved) | **Open** `T{n+1}: …` as the new current thread |

Open a typed thread only for a topic that can be resolved on its own: a spike that answers one question, a fix pulled out of the main work. Assessments, plans, step completions, PRs and CI results are routine progress and belong in the current thread.

### Closing a thread

A thread closes with a reply whose heading starts with ✅ and whose body is its summary: what was tried, how it concluded, and what (if anything) carries over. Then ask a human to resolve it. The Linear MCP can read `resolvedAt` but cannot set it, so resolving is a human action. Until it happens, the thread stays a routing candidate.

A resolved thread folds away, so the list of resolved threads becomes the issue's history: each one's ✅ reply is the tl;dr.

### Provenance

The provenance marker identifies the authoring surface:

- `*[ai:claude-code]*` — comment authored by Claude Code (interactive session)
- `*[ai:managed-agent]*` — comment authored by a managed agent (walk-away)

The marker always appears on line 3 (after heading + blank line), never inline or at the end.

### Mid-thread events

When something changes mid-thread (plan adjusted, step skipped, blocker found), use these emoji prefixes on the reply's heading:

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb