Skip to content

Document that Linear archives issues automatically - #289

Merged
schpetbot merged 1 commit into
mainfrom
archive-caveat-docs
Sep 15, 2026
Merged

schpetbot merged 1 commit into
mainfrom
archive-caveat-docs

Conversation

@schpetbot

Copy link
Copy Markdown
Collaborator

Follow-up to #285 / #284.

issue archive exposes an action Linear's own product hides. Linear's delete and archive issues docs say "archiving happens automatically with no option to manually archive items", and the 2021 changelog explains why the manual option was removed: most people used the archive as a trash can, and "the archive is something that Linear should manage for you while deleting issues is your own choice". The official Linear MCP server has no archive tool either. Nothing in our help or skill said any of this, so an agent reading the command list would treat archive as a normal way to retire an issue.

Changes

  • issue archive --help now explains the caveat and links the Linear docs. The generated skill reference and help snapshot follow from it.
  • docs/usage.md quotes and links the docs and changelog, and notes the practical hazards of calling issueArchive directly: it skips auto-archive's checks for open parents, sub-issues, cycles, and projects, and archived issues drop out of list, query, and search unless --include-archived is passed.
  • The skill template gains a "Close, delete, or archive an issue" recipe that tells agents to prefer closing or deleting, and to archive only when explicitly asked.
  • README comment and changelog entry.

Verification

  • deno check, deno lint, deno fmt --check on changed files
  • deno task test test/commands/issue/issue-archive.test.ts: 11 passed
  • deno task generate-skill-docs and deno task snapshot for the regenerated reference and help snapshot

issue archive (#285) exposes an action Linear's own product hides.
Linear's docs state that archiving happens automatically with no
option to manually archive items, and the 2021 changelog explains
the manual option was removed because most people used the archive
as a trash can: the archive is Linear's to manage, deleting is the
user's choice. The official Linear MCP server exposes no archive
tool either. Nothing in our help or skill said any of this, so an
agent reading the command list would treat archive as a normal way
to retire an issue.

The command's help, docs/usage.md, the README line, and the skill
template now say to prefer closing or deleting, quote and link the
Linear docs, and note the two practical hazards of calling
issueArchive directly: it skips auto-archive's checks for open
parents, sub-issues, cycles, and projects, and archived issues
drop out of list, query, and search unless --include-archived is
passed. The generated skill reference and help snapshot follow
from the new description.
@schpetbot
schpetbot merged commit e4f0837 into main Sep 15, 2026
15 checks passed
@schpetbot
schpetbot deleted the archive-caveat-docs branch September 15, 2026 19:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants