@enrichlayer/el-linear 1.38.1 → 1.39.0

package/claude-skills/linear-operations/SKILL.md

@@ -371,7 +371,7 @@ Complete ALL items before creating any issue:
 - [ ] **Assignee** — ask user if unclear (`el-linear users list --active`).
 - [ ] **Project** — always ask user, never guess (`el-linear projects list`).
 - [ ] **Labels** — exactly 1 type label + 1–2 domain labels (see Label Taxonomy below).
-- [ ] **Title** — action verb matching the type label (see Title Verb Convention), sentence case, specific scope.
+- [ ] **Title** — action verb matching the type label (see Title Verb Convention), sentence case, specific scope, **plain-language and jargon-free** (see Title Readability).
 - [ ] **Description** — 2–4 sentences with context and intent, formatted with **bold** and `inline code`.
 - [ ] **"Why we need this"** — genuine motivation, not a restatement of the title.
 
@@ -497,6 +497,27 @@ Title must start with a verb that matches the type label:
 - `spike` → Research, Investigate, Explore, Evaluate, Audit, Benchmark
 - `refactor` → Refactor, Restructure, Extract, Decouple, Simplify
 
+### Title Readability — plain language, jargon in the body
+
+**The title says what problem is being solved, in words a non-author can read.** The title is the shared surface — a teammate scanning the board, a manager triaging priority, a future picker deciding what to pick up. If it only parses for the person who wrote it that week, that whole audience is locked out. This applies to **MR/PR titles too** — they front the same board.
+
+**Keep the mechanism detail — function names, env-var constants, symbol soup — in the description, not the title.** Moving it into the body doesn't lose precision; it puts precision where the reader who opens the issue actually wants it. The title carries the *problem*; the body carries the *how*.
+
+- **Lead with the problem or outcome**, not the internal symbol at the center of it.
+- **Move code identifiers, env-var constants, and file/function names into the body**, under a `## …` heading where they read as helpful context.
+- **Proper nouns that ARE the clearest name stay.** The name of a tool, service, or protocol a teammate would recognize (a CLI name, `Vault`, `CI`, `OAuth`) is not jargon — don't paraphrase it into vagueness. The test is "would a teammate recognize this?", not "does it contain a lowercase token?".
+- **Don't overcorrect into mush.** "Fix the thing that was broken" is worse than a jargon title — specificity still matters, just express it in problem terms.
+
+Before → after:
+
+| ❌ Jargon title | ✅ Plain-language title |
+|---|---|
+| `parseTokenBucket drops refill when lastRefillTs is unset` | Fix rate limiter losing its refill allowance after an idle period |
+| `AUTH_SESSION_TTL mismatch logs out users early in refreshSession` | Fix users getting logged out before their session length expires |
+| `Extract validateEntry into shared pkg (3 hand-rolled copies)` | Extract the duplicated entry validator into a shared package |
+
+The mechanism (`parseTokenBucket`, `AUTH_SESSION_TTL`, `refreshSession`, the three copies) still gets stated — in the **description**, where it reads as context instead of a barrier.
+
 ### Rules
 
 - **Create missing labels liberally** — `el-linear labels create "my-label" --team ENG`.

package/dist/commands/documents.js

@@ -65,8 +65,9 @@ async function handleCreateDocument(options, command) {
     outputSuccess(document);
 }
 async function handleListDocuments(options, command) {
-    if (options.project && options.issue) {
-        throw new Error("Cannot use --project and --issue together. Choose one filter.");
+    const filters = [options.project, options.issue, options.attachedTo].filter(Boolean);
+    if (filters.length > 1) {
+        throw new Error("Cannot combine --project, --issue, and --attached-to. Choose one filter.");
     }
     const rootOpts = getRootOpts(command);
     const documentsService = await createGraphQLDocumentsService(rootOpts);
@@ -75,9 +76,9 @@ async function handleListDocuments(options, command) {
     if (Number.isNaN(limit) || limit < 1) {
         throw new Error(`Invalid limit "${options.limit}": must be a positive number`);
     }
-    if (options.issue) {
+    if (options.attachedTo) {
         const attachmentsService = await createGraphQLAttachmentsService(rootOpts);
-        const issueId = await linearService.resolveIssueId(options.issue);
+        const issueId = await linearService.resolveIssueId(options.attachedTo);
         const attachments = await attachmentsService.listAttachments(issueId);
         const documentSlugIds = [
             ...new Set(attachments
@@ -96,8 +97,13 @@ async function handleListDocuments(options, command) {
     if (options.project) {
         projectId = await linearService.resolveProjectId(options.project);
     }
+    let issueId;
+    if (options.issue) {
+        issueId = await linearService.resolveIssueId(options.issue);
+    }
     const docs = await documentsService.listDocuments({
         projectId,
+        issueId,
         first: limit,
     });
     outputSuccess({ data: docs, meta: { count: docs.length } });
@@ -119,8 +125,8 @@ export function setupDocumentsCommands(program) {
         .option("--team <team>", "team key or name")
         .option("--icon <icon>", "document icon")
         .option("--color <color>", "icon color")
-        .option("--issue <issue>", "link document to issue (e.g., ABC-123)")
-        .option("--attach-to <issue>", "also attach document to issue (e.g., ABC-123)")
+        .option("--issue <issue>", "link document directly to issue (e.g., ABC-123)")
+        .option("--attach-to <issue>", "also create a URL attachment on issue (e.g., ABC-123)")
         .action(handleAsyncCommand(handleCreateDocument));
     documents
         .command("update <documentId>")
@@ -164,7 +170,8 @@ export function setupDocumentsCommands(program) {
         .command("list")
         .description("List documents")
         .option("--project <project>", "filter by project name or ID")
-        .option("--issue <issue>", "filter by issue (shows documents attached to the issue)")
+        .option("--issue <issue>", "filter by direct issue link (set by documents create --issue)")
+        .option("--attached-to <issue>", "filter by URL attachments (set by documents create --attach-to)")
         .option("-l, --limit <limit>", "maximum number of documents", "50")
         .action(handleAsyncCommand(handleListDocuments));
     documents

package/dist/utils/graphql-documents-service.d.ts

@@ -9,6 +9,7 @@ declare class GraphQLDocumentsService {
     getDocument(id: string): Promise<LinearDocument>;
     listDocuments(options?: {
         projectId?: string;
+        issueId?: string;
         first?: number;
     }): Promise<LinearDocument[]>;
     deleteDocument(id: string): Promise<boolean>;

package/dist/utils/graphql-documents-service.js

@@ -55,9 +55,13 @@ class GraphQLDocumentsService {
         return transformDocument(result.document);
     }
     async listDocuments(options) {
-        const filter = options?.projectId
-            ? { project: { id: { eq: options.projectId } } }
-            : undefined;
+        let filter;
+        if (options?.projectId) {
+            filter = { project: { id: { eq: options.projectId } } };
+        }
+        else if (options?.issueId) {
+            filter = { issue: { id: { eq: options.issueId } } };
+        }
         const result = await this.graphqlService.rawRequest(LIST_DOCUMENTS_QUERY, {
             first: options?.first ?? 50,
             filter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",