mdcontext 0.0.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (337) hide show
  1. package/.changeset/README.md +28 -0
  2. package/.changeset/config.json +11 -0
  3. package/.claude/settings.local.json +25 -0
  4. package/.github/workflows/ci.yml +83 -0
  5. package/.github/workflows/claude-code-review.yml +44 -0
  6. package/.github/workflows/claude.yml +85 -0
  7. package/.github/workflows/release.yml +113 -0
  8. package/.tldrignore +112 -0
  9. package/BACKLOG.md +338 -0
  10. package/CONTRIBUTING.md +186 -0
  11. package/NOTES/NOTES +44 -0
  12. package/README.md +434 -11
  13. package/biome.json +36 -0
  14. package/cspell.config.yaml +14 -0
  15. package/dist/chunk-23UPXDNL.js +3044 -0
  16. package/dist/chunk-2W7MO2DL.js +1366 -0
  17. package/dist/chunk-3NUAZGMA.js +1689 -0
  18. package/dist/chunk-7TOWB2XB.js +366 -0
  19. package/dist/chunk-7XOTOADQ.js +3065 -0
  20. package/dist/chunk-AH2PDM2K.js +3042 -0
  21. package/dist/chunk-BNXWSZ63.js +3742 -0
  22. package/dist/chunk-BTL5DJVU.js +3222 -0
  23. package/dist/chunk-HDHYG7E4.js +104 -0
  24. package/dist/chunk-HLR4KZBP.js +3234 -0
  25. package/dist/chunk-IP3FRFEB.js +1045 -0
  26. package/dist/chunk-KHU56VDO.js +3042 -0
  27. package/dist/chunk-KRYIFLQR.js +88 -0
  28. package/dist/chunk-LBSDNLEM.js +287 -0
  29. package/dist/chunk-MNTQ7HCP.js +2643 -0
  30. package/dist/chunk-MUJELQQ6.js +1387 -0
  31. package/dist/chunk-MXJGMSLV.js +2199 -0
  32. package/dist/chunk-N6QJGC3Z.js +2636 -0
  33. package/dist/chunk-OBELGBPM.js +1713 -0
  34. package/dist/chunk-OT7R5XTA.js +3192 -0
  35. package/dist/chunk-P7X4RA2T.js +106 -0
  36. package/dist/chunk-PIDUQNC2.js +3185 -0
  37. package/dist/chunk-POGCDIH4.js +3187 -0
  38. package/dist/chunk-PSIEOQGZ.js +3043 -0
  39. package/dist/chunk-PVRT3IHA.js +3238 -0
  40. package/dist/chunk-QNN4TT23.js +1430 -0
  41. package/dist/chunk-RE3R45RJ.js +3042 -0
  42. package/dist/chunk-S7E6TFX6.js +803 -0
  43. package/dist/chunk-SG6GLU4U.js +1378 -0
  44. package/dist/chunk-SJCDV2ST.js +274 -0
  45. package/dist/chunk-SYE5XLF3.js +104 -0
  46. package/dist/chunk-T5VLYBZD.js +103 -0
  47. package/dist/chunk-TOQB7VWU.js +3238 -0
  48. package/dist/chunk-VFNMZ4ZQ.js +3228 -0
  49. package/dist/chunk-VVTGZNBT.js +1629 -0
  50. package/dist/chunk-W7Q4RFEV.js +104 -0
  51. package/dist/chunk-XTYYVRLO.js +3190 -0
  52. package/dist/chunk-Y6MDYVJD.js +3063 -0
  53. package/dist/cli/main.d.ts +1 -0
  54. package/dist/cli/main.js +5458 -0
  55. package/dist/index.d.ts +653 -0
  56. package/dist/index.js +79 -0
  57. package/dist/mcp/server.d.ts +1 -0
  58. package/dist/mcp/server.js +472 -0
  59. package/dist/schema-BAWSG7KY.js +22 -0
  60. package/dist/schema-E3QUPL26.js +20 -0
  61. package/dist/schema-EHL7WUT6.js +20 -0
  62. package/docs/019-USAGE.md +625 -0
  63. package/docs/020-current-implementation.md +364 -0
  64. package/docs/021-DOGFOODING-FINDINGS.md +175 -0
  65. package/docs/BACKLOG.md +80 -0
  66. package/docs/CONFIG.md +1123 -0
  67. package/docs/DESIGN.md +439 -0
  68. package/docs/ERRORS.md +383 -0
  69. package/docs/PROJECT.md +88 -0
  70. package/docs/ROADMAP.md +407 -0
  71. package/docs/summarization.md +320 -0
  72. package/docs/test-links.md +9 -0
  73. package/justfile +40 -0
  74. package/package.json +74 -9
  75. package/pnpm-workspace.yaml +5 -0
  76. package/research/INDEX.md +315 -0
  77. package/research/code-review/README.md +90 -0
  78. package/research/code-review/cli-error-handling-review.md +979 -0
  79. package/research/code-review/code-review-validation-report.md +464 -0
  80. package/research/code-review/main-ts-review.md +1128 -0
  81. package/research/config-analysis/01-current-implementation.md +470 -0
  82. package/research/config-analysis/02-strategy-recommendation.md +428 -0
  83. package/research/config-analysis/03-task-candidates.md +715 -0
  84. package/research/config-analysis/033-research-configuration-management.md +828 -0
  85. package/research/config-analysis/034-research-effect-cli-config.md +1504 -0
  86. package/research/config-analysis/04-consolidated-task-candidates.md +277 -0
  87. package/research/config-docs/SUMMARY.md +357 -0
  88. package/research/config-docs/TEST-RESULTS.md +776 -0
  89. package/research/config-docs/TODO.md +542 -0
  90. package/research/config-docs/analysis.md +744 -0
  91. package/research/config-docs/fix-validation.md +502 -0
  92. package/research/config-docs/help-audit.md +264 -0
  93. package/research/config-docs/help-system-analysis.md +890 -0
  94. package/research/dogfood/consolidated-tool-evaluation.md +373 -0
  95. package/research/dogfood/strategy-a/a-synthesis.md +184 -0
  96. package/research/dogfood/strategy-a/a1-docs.md +226 -0
  97. package/research/dogfood/strategy-a/a2-amorphic.md +156 -0
  98. package/research/dogfood/strategy-a/a3-llm.md +164 -0
  99. package/research/dogfood/strategy-b/b-synthesis.md +228 -0
  100. package/research/dogfood/strategy-b/b1-architecture.md +207 -0
  101. package/research/dogfood/strategy-b/b2-gaps.md +258 -0
  102. package/research/dogfood/strategy-b/b3-workflows.md +250 -0
  103. package/research/dogfood/strategy-c/c-synthesis.md +451 -0
  104. package/research/dogfood/strategy-c/c1-explorer.md +192 -0
  105. package/research/dogfood/strategy-c/c2-diver-memory.md +145 -0
  106. package/research/dogfood/strategy-c/c3-diver-control.md +148 -0
  107. package/research/dogfood/strategy-c/c4-diver-failure.md +151 -0
  108. package/research/dogfood/strategy-c/c5-diver-execution.md +221 -0
  109. package/research/dogfood/strategy-c/c6-diver-org.md +221 -0
  110. package/research/effect-cli-error-handling.md +845 -0
  111. package/research/effect-errors-as-values.md +943 -0
  112. package/research/errors-task-analysis/00-consolidated-tasks.md +207 -0
  113. package/research/errors-task-analysis/cli-commands-analysis.md +909 -0
  114. package/research/errors-task-analysis/embeddings-analysis.md +709 -0
  115. package/research/errors-task-analysis/index-search-analysis.md +812 -0
  116. package/research/frontmatter/COMMENTS-ARE-SKIPPED.md +149 -0
  117. package/research/frontmatter/LLM-CODE-NAVIGATION.md +276 -0
  118. package/research/issue-review.md +603 -0
  119. package/research/llm-summarization/agent-cli-tools-2026.md +1082 -0
  120. package/research/llm-summarization/alternative-providers-2026.md +1428 -0
  121. package/research/llm-summarization/anthropic-2026.md +367 -0
  122. package/research/llm-summarization/claude-cli-integration.md +1706 -0
  123. package/research/llm-summarization/cli-integration-patterns.md +3155 -0
  124. package/research/llm-summarization/openai-2026.md +473 -0
  125. package/research/llm-summarization/openai-compatible-providers-2026.md +1022 -0
  126. package/research/llm-summarization/opencode-cli-integration.md +1552 -0
  127. package/research/llm-summarization/prompt-engineering-2026.md +1426 -0
  128. package/research/llm-summarization/prototype-results.md +56 -0
  129. package/research/llm-summarization/provider-switching-patterns-2026.md +2153 -0
  130. package/research/llm-summarization/typescript-llm-libraries-2026.md +2436 -0
  131. package/research/mdcontext-error-analysis.md +521 -0
  132. package/research/mdcontext-pudding/00-EXECUTIVE-SUMMARY.md +282 -0
  133. package/research/mdcontext-pudding/01-index-embed.md +956 -0
  134. package/research/mdcontext-pudding/02-search-COMMANDS.md +142 -0
  135. package/research/mdcontext-pudding/02-search-SUMMARY.md +146 -0
  136. package/research/mdcontext-pudding/02-search.md +970 -0
  137. package/research/mdcontext-pudding/03-context.md +779 -0
  138. package/research/mdcontext-pudding/04-navigation-and-analytics.md +803 -0
  139. package/research/mdcontext-pudding/04-tree.md +704 -0
  140. package/research/mdcontext-pudding/05-config.md +1038 -0
  141. package/research/mdcontext-pudding/06-links-summary.txt +87 -0
  142. package/research/mdcontext-pudding/06-links.md +679 -0
  143. package/research/mdcontext-pudding/07-stats.md +693 -0
  144. package/research/mdcontext-pudding/BUG-FIX-PLAN.md +388 -0
  145. package/research/mdcontext-pudding/P0-BUG-VALIDATION.md +167 -0
  146. package/research/mdcontext-pudding/README.md +168 -0
  147. package/research/mdcontext-pudding/TESTING-SUMMARY.md +128 -0
  148. package/research/npm_publish/011-npm-workflow-research-agent2.md +792 -0
  149. package/research/npm_publish/012-npm-workflow-research-agent1.md +530 -0
  150. package/research/npm_publish/013-npm-workflow-research-agent3.md +722 -0
  151. package/research/npm_publish/014-npm-workflow-synthesis.md +556 -0
  152. package/research/npm_publish/031-npm-workflow-task-analysis.md +134 -0
  153. package/research/research-quality-review.md +834 -0
  154. package/research/semantic-search/002-research-embedding-models.md +490 -0
  155. package/research/semantic-search/003-research-rag-alternatives.md +523 -0
  156. package/research/semantic-search/004-research-vector-search.md +841 -0
  157. package/research/semantic-search/032-research-semantic-search.md +427 -0
  158. package/research/semantic-search/embedding-text-analysis.md +156 -0
  159. package/research/semantic-search/multi-word-failure-reproduction.md +171 -0
  160. package/research/semantic-search/query-processing-analysis.md +207 -0
  161. package/research/semantic-search/root-cause-and-solution.md +114 -0
  162. package/research/semantic-search/threshold-validation-report.md +69 -0
  163. package/research/semantic-search/vector-search-analysis.md +63 -0
  164. package/research/task-management-2026/00-synthesis-recommendations.md +295 -0
  165. package/research/task-management-2026/01-ai-workflow-tools.md +416 -0
  166. package/research/task-management-2026/02-agent-framework-patterns.md +476 -0
  167. package/research/task-management-2026/03-lightweight-file-based.md +567 -0
  168. package/research/task-management-2026/04-established-tools-ai-features.md +541 -0
  169. package/research/task-management-2026/linear/01-core-features-workflow.md +771 -0
  170. package/research/task-management-2026/linear/02-api-integrations.md +930 -0
  171. package/research/task-management-2026/linear/03-ai-features.md +368 -0
  172. package/research/task-management-2026/linear/04-pricing-setup.md +205 -0
  173. package/research/task-management-2026/linear/05-usage-patterns-best-practices.md +605 -0
  174. package/research/test-path-issues.md +276 -0
  175. package/review/ALP-76/1-error-type-design.md +962 -0
  176. package/review/ALP-76/2-error-handling-patterns.md +906 -0
  177. package/review/ALP-76/3-error-presentation.md +624 -0
  178. package/review/ALP-76/4-test-coverage.md +625 -0
  179. package/review/ALP-76/5-migration-completeness.md +440 -0
  180. package/review/ALP-76/6-effect-best-practices.md +755 -0
  181. package/scripts/apply-branch-protection.sh +47 -0
  182. package/scripts/branch-protection-templates.json +79 -0
  183. package/scripts/prototype-summarization.ts +346 -0
  184. package/scripts/rebuild-hnswlib.js +58 -0
  185. package/scripts/setup-branch-protection.sh +64 -0
  186. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/active-provider.json +7 -0
  187. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/bm25.json +541 -0
  188. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/bm25.meta.json +5 -0
  189. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/config.json +8 -0
  190. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/embeddings/openai_text-embedding-3-small_512/vectors.bin +0 -0
  191. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/embeddings/openai_text-embedding-3-small_512/vectors.meta.bin +0 -0
  192. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/indexes/documents.json +60 -0
  193. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/indexes/links.json +13 -0
  194. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/indexes/sections.json +1197 -0
  195. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/configuration-management.md +99 -0
  196. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/distributed-systems.md +92 -0
  197. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/error-handling.md +78 -0
  198. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/failure-automation.md +55 -0
  199. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/job-context.md +69 -0
  200. package/src/__tests__/fixtures/semantic-search/multi-word-corpus/process-orchestration.md +99 -0
  201. package/src/cli/argv-preprocessor.test.ts +210 -0
  202. package/src/cli/argv-preprocessor.ts +202 -0
  203. package/src/cli/cli.test.ts +627 -0
  204. package/src/cli/commands/backlinks.ts +54 -0
  205. package/src/cli/commands/config-cmd.ts +642 -0
  206. package/src/cli/commands/context.ts +285 -0
  207. package/src/cli/commands/duplicates.ts +122 -0
  208. package/src/cli/commands/embeddings.ts +529 -0
  209. package/src/cli/commands/index-cmd.ts +480 -0
  210. package/src/cli/commands/index.ts +16 -0
  211. package/src/cli/commands/links.ts +52 -0
  212. package/src/cli/commands/search.ts +1281 -0
  213. package/src/cli/commands/stats.ts +149 -0
  214. package/src/cli/commands/tree.ts +128 -0
  215. package/src/cli/config-layer.ts +176 -0
  216. package/src/cli/error-handler.test.ts +235 -0
  217. package/src/cli/error-handler.ts +655 -0
  218. package/src/cli/flag-schemas.ts +341 -0
  219. package/src/cli/help.ts +588 -0
  220. package/src/cli/index.ts +9 -0
  221. package/src/cli/main.ts +435 -0
  222. package/src/cli/options.ts +41 -0
  223. package/src/cli/shared-error-handling.ts +199 -0
  224. package/src/cli/typo-suggester.test.ts +105 -0
  225. package/src/cli/typo-suggester.ts +130 -0
  226. package/src/cli/utils.ts +259 -0
  227. package/src/config/file-provider.test.ts +320 -0
  228. package/src/config/file-provider.ts +273 -0
  229. package/src/config/index.ts +72 -0
  230. package/src/config/integration.test.ts +667 -0
  231. package/src/config/precedence.test.ts +277 -0
  232. package/src/config/precedence.ts +451 -0
  233. package/src/config/schema.test.ts +414 -0
  234. package/src/config/schema.ts +603 -0
  235. package/src/config/service.test.ts +320 -0
  236. package/src/config/service.ts +243 -0
  237. package/src/config/testing.test.ts +264 -0
  238. package/src/config/testing.ts +110 -0
  239. package/src/core/index.ts +1 -0
  240. package/src/core/types.ts +113 -0
  241. package/src/duplicates/detector.test.ts +183 -0
  242. package/src/duplicates/detector.ts +414 -0
  243. package/src/duplicates/index.ts +18 -0
  244. package/src/embeddings/embedding-namespace.test.ts +300 -0
  245. package/src/embeddings/embedding-namespace.ts +947 -0
  246. package/src/embeddings/heading-boost.test.ts +222 -0
  247. package/src/embeddings/hnsw-build-options.test.ts +198 -0
  248. package/src/embeddings/hyde.test.ts +272 -0
  249. package/src/embeddings/hyde.ts +264 -0
  250. package/src/embeddings/index.ts +10 -0
  251. package/src/embeddings/openai-provider.ts +414 -0
  252. package/src/embeddings/pricing.json +22 -0
  253. package/src/embeddings/provider-constants.ts +204 -0
  254. package/src/embeddings/provider-errors.test.ts +967 -0
  255. package/src/embeddings/provider-errors.ts +565 -0
  256. package/src/embeddings/provider-factory.test.ts +240 -0
  257. package/src/embeddings/provider-factory.ts +225 -0
  258. package/src/embeddings/provider-integration.test.ts +788 -0
  259. package/src/embeddings/query-preprocessing.test.ts +187 -0
  260. package/src/embeddings/semantic-search-threshold.test.ts +508 -0
  261. package/src/embeddings/semantic-search.ts +1270 -0
  262. package/src/embeddings/types.ts +359 -0
  263. package/src/embeddings/vector-store.ts +708 -0
  264. package/src/embeddings/voyage-provider.ts +313 -0
  265. package/src/errors/errors.test.ts +845 -0
  266. package/src/errors/index.ts +533 -0
  267. package/src/index/ignore-patterns.test.ts +354 -0
  268. package/src/index/ignore-patterns.ts +305 -0
  269. package/src/index/index.ts +4 -0
  270. package/src/index/indexer.ts +684 -0
  271. package/src/index/storage.ts +260 -0
  272. package/src/index/types.ts +147 -0
  273. package/src/index/watcher.ts +189 -0
  274. package/src/index.ts +30 -0
  275. package/src/integration/search-keyword.test.ts +678 -0
  276. package/src/mcp/server.ts +612 -0
  277. package/src/parser/index.ts +1 -0
  278. package/src/parser/parser.test.ts +291 -0
  279. package/src/parser/parser.ts +394 -0
  280. package/src/parser/section-filter.test.ts +277 -0
  281. package/src/parser/section-filter.ts +392 -0
  282. package/src/search/__tests__/hybrid-search.test.ts +650 -0
  283. package/src/search/bm25-store.ts +366 -0
  284. package/src/search/cross-encoder.test.ts +253 -0
  285. package/src/search/cross-encoder.ts +406 -0
  286. package/src/search/fuzzy-search.test.ts +419 -0
  287. package/src/search/fuzzy-search.ts +273 -0
  288. package/src/search/hybrid-search.ts +448 -0
  289. package/src/search/path-matcher.test.ts +276 -0
  290. package/src/search/path-matcher.ts +33 -0
  291. package/src/search/query-parser.test.ts +260 -0
  292. package/src/search/query-parser.ts +319 -0
  293. package/src/search/searcher.test.ts +280 -0
  294. package/src/search/searcher.ts +724 -0
  295. package/src/search/wink-bm25.d.ts +30 -0
  296. package/src/summarization/cli-providers/claude.ts +202 -0
  297. package/src/summarization/cli-providers/detection.test.ts +273 -0
  298. package/src/summarization/cli-providers/detection.ts +118 -0
  299. package/src/summarization/cli-providers/index.ts +8 -0
  300. package/src/summarization/cost.test.ts +139 -0
  301. package/src/summarization/cost.ts +102 -0
  302. package/src/summarization/error-handler.test.ts +127 -0
  303. package/src/summarization/error-handler.ts +111 -0
  304. package/src/summarization/index.ts +102 -0
  305. package/src/summarization/pipeline.test.ts +498 -0
  306. package/src/summarization/pipeline.ts +231 -0
  307. package/src/summarization/prompts.test.ts +269 -0
  308. package/src/summarization/prompts.ts +133 -0
  309. package/src/summarization/provider-factory.test.ts +396 -0
  310. package/src/summarization/provider-factory.ts +178 -0
  311. package/src/summarization/types.ts +184 -0
  312. package/src/summarize/budget-bugs.test.ts +620 -0
  313. package/src/summarize/formatters.ts +419 -0
  314. package/src/summarize/index.ts +20 -0
  315. package/src/summarize/summarizer.test.ts +275 -0
  316. package/src/summarize/summarizer.ts +597 -0
  317. package/src/summarize/verify-bugs.test.ts +238 -0
  318. package/src/types/huggingface-transformers.d.ts +66 -0
  319. package/src/utils/index.ts +1 -0
  320. package/src/utils/tokens.test.ts +142 -0
  321. package/src/utils/tokens.ts +186 -0
  322. package/tests/fixtures/cli/.mdcontext/active-provider.json +7 -0
  323. package/tests/fixtures/cli/.mdcontext/config.json +8 -0
  324. package/tests/fixtures/cli/.mdcontext/embeddings/openai_text-embedding-3-small_512/vectors.bin +0 -0
  325. package/tests/fixtures/cli/.mdcontext/embeddings/openai_text-embedding-3-small_512/vectors.meta.bin +0 -0
  326. package/tests/fixtures/cli/.mdcontext/indexes/documents.json +33 -0
  327. package/tests/fixtures/cli/.mdcontext/indexes/links.json +12 -0
  328. package/tests/fixtures/cli/.mdcontext/indexes/sections.json +247 -0
  329. package/tests/fixtures/cli/README.md +9 -0
  330. package/tests/fixtures/cli/api-reference.md +11 -0
  331. package/tests/fixtures/cli/getting-started.md +11 -0
  332. package/tests/integration/embed-index.test.ts +712 -0
  333. package/tests/integration/search-context.test.ts +469 -0
  334. package/tests/integration/search-semantic.test.ts +522 -0
  335. package/tsconfig.json +26 -0
  336. package/vitest.config.ts +16 -0
  337. package/vitest.setup.ts +12 -0
@@ -0,0 +1,771 @@
1
+ # Linear: Core Features and Workflow Research (2026)
2
+
3
+ ## Overview
4
+
5
+ Linear is a modern issue tracking and project management tool designed for software development teams. Founded in 2019, it has positioned itself as a streamlined, opinionated alternative to tools like Jira and GitHub Issues. Linear emphasizes speed, simplicity, and a delightful user experience.
6
+
7
+ **Key Philosophy**: Linear takes an "Apple-like" approach - it assumes you want to ship fast and tells you how to work, rather than offering infinite customization.
8
+
9
+ ---
10
+
11
+ ## 1. Quick Ticket/Issue Capture
12
+
13
+ ### Primary Methods for Creating Issues
14
+
15
+ #### Keyboard Shortcut (`C`)
16
+
17
+ The fastest way to create an issue in Linear is pressing `C` from anywhere in the app. This opens the issue creation modal immediately.
18
+
19
+ ```
20
+ C → Open issue creation modal
21
+ V → Open full-screen issue creation
22
+ Option/Alt C → Create from template
23
+ ```
24
+
25
+ #### Command Palette (`Cmd/Ctrl + K`)
26
+
27
+ Linear's command palette provides universal access to all actions:
28
+
29
+ - Press `Cmd/Ctrl + K` to open
30
+ - Type "create issue" or any action name
31
+ - Execute without navigating through menus
32
+
33
+ #### Quick Create URL
34
+
35
+ Navigate to `https://linear.new` in your browser to instantly create a new issue (must be logged in).
36
+
37
+ #### Pre-filled Issue URLs
38
+
39
+ Create issues with pre-populated fields using query parameters:
40
+
41
+ ```
42
+ https://linear.new?title=Bug%20Report&priority=2&labelIds=abc123
43
+ ```
44
+
45
+ Supported pre-fill fields: title, description, status, priority, assignee, estimate, cycle, labels, project, milestone, link attachments.
46
+
47
+ ### Issue Requirements
48
+
49
+ **Minimum Required**:
50
+
51
+ - Title
52
+ - Status (auto-assigned to team default)
53
+ - Team assignment
54
+
55
+ **Optional Properties**:
56
+
57
+ - Assignee
58
+ - Priority (None, Low, Medium, High, Urgent)
59
+ - Estimate (points)
60
+ - Labels
61
+ - Due date
62
+ - Cycle assignment
63
+ - Project assignment
64
+ - Description (Markdown supported)
65
+
66
+ ### Quick Capture Workarounds
67
+
68
+ Linear lacks a native global system hotkey for quick capture. Power users work around this with:
69
+
70
+ **Raycast Integration** (macOS):
71
+
72
+ 1. Install Raycast (free "Spotlight on Steroids")
73
+ 2. Add the Linear extension
74
+ 3. Bind "create issue for myself" to a custom hotkey (e.g., `Cmd+Shift+Space`)
75
+
76
+ ### Draft Preservation
77
+
78
+ - Navigating away from issue creation saves a temporary local draft
79
+ - Press `Esc` to save a persistent draft for later
80
+ - Highlighting text before pressing `C` auto-fills the issue title
81
+
82
+ ---
83
+
84
+ ## 2. Inbox, Triage, and Backlog
85
+
86
+ Linear has three distinct concepts for managing incoming work, each serving a different purpose:
87
+
88
+ ### Personal Inbox (Notifications)
89
+
90
+ **Purpose**: Your personal notification center for activity on issues you're involved with.
91
+
92
+ **Navigation**: `G` then `I` (Go to Inbox)
93
+
94
+ **What Appears Here**:
95
+
96
+ - Updates on issues you created
97
+ - Updates on issues assigned to you
98
+ - Mentions in descriptions or comments
99
+ - Status changes on subscribed issues
100
+ - Reactions to your comments
101
+
102
+ **Inbox Management Shortcuts**:
103
+
104
+ ```
105
+ G, I → Go to Inbox
106
+ J / K → Navigate up/down through notifications
107
+ U → Mark as read/unread
108
+ Option/Alt U → Mark all as read/unread
109
+ Backspace → Delete notification
110
+ Shift + Backspace → Delete all notifications
111
+ Cmd/Ctrl D → Delete all read notifications
112
+ H → Snooze notification
113
+ Cmd/Ctrl F → Search inbox (by title, ID, type, assignee)
114
+ ```
115
+
116
+ **Limits**: Linear retains up to 500 notifications in your inbox.
117
+
118
+ **Notification Channels**:
119
+
120
+ - In-app Inbox (always)
121
+ - Desktop/mobile push notifications
122
+ - Email digests
123
+ - Slack personal notifications (via Linear app in Slack)
124
+
125
+ ### Team Triage (Shared Inbox)
126
+
127
+ **Purpose**: A team-level staging area for reviewing new incoming issues before accepting them into the workflow.
128
+
129
+ **Navigation**: `G` then `T` (Go to Triage)
130
+
131
+ **What Enters Triage**:
132
+
133
+ - Issues created through integrations (Slack, Sentry, Zendesk, etc.)
134
+ - Issues created by workspace members outside your specific team
135
+ - Issues created directly in the Triage view
136
+ - Issues routed via Linear Asks
137
+
138
+ **Triage Actions**:
139
+
140
+ ```
141
+ 1 → Accept (move to team's default status)
142
+ 2 / MM → Mark as Duplicate (merge into existing issue)
143
+ 3 → Decline (cancel with optional explanation)
144
+ H → Snooze (hide until specified time or new activity)
145
+ ```
146
+
147
+ **Accept**: Approves the issue and moves it to your team's default status (typically Backlog or Todo). Option to add a comment.
148
+
149
+ **Mark as Duplicate**: Merges into an existing issue. Attachments, customer requests, and linked items transfer to the canonical issue. The duplicate is marked Canceled.
150
+
151
+ **Decline**: Rejects the issue, marks it Canceled. Option to add an explanation comment.
152
+
153
+ **Snooze**: Temporarily hides the issue from triage. Returns at:
154
+
155
+ - A specified date/time
156
+ - When new activity occurs on the issue
157
+
158
+ #### Triage Intelligence (AI-Powered)
159
+
160
+ Available on Business and Enterprise plans. Triage Intelligence uses LLMs to:
161
+
162
+ - Analyze new issues against existing backlog
163
+ - Suggest properties (assignee, labels, priority)
164
+ - Detect likely duplicates
165
+ - Surface related issues
166
+ - Provide brief explanations for suggestions
167
+
168
+ The AI draws on historical behavior patterns in your workspace to make contextual recommendations.
169
+
170
+ #### Triage Rules (Enterprise)
171
+
172
+ Custom automation rules for issues entering Triage:
173
+
174
+ - Trigger on filterable properties
175
+ - Auto-update team, status, assignee, label, project, or priority
176
+ - Execute in configured order (top to bottom)
177
+
178
+ #### Triage Best Practices
179
+
180
+ 1. **Daily review routine**: Review triage inbox daily
181
+ 2. **Rotate responsibility**: Share triage duty among team members
182
+ 3. **Use templates**: Standardize intake with form templates
183
+ 4. **Connect scheduling tools**: Integrate with PagerDuty, OpsGenie, Rootly, or Incident.io for automated rotations
184
+
185
+ ### Backlog (Accepted Work)
186
+
187
+ **Purpose**: Holds accepted issues that are waiting to be prioritized and worked on.
188
+
189
+ **Navigation**: `G` then `B` (Go to Backlog)
190
+
191
+ **Characteristics**:
192
+
193
+ - Default destination for newly created or accepted issues
194
+ - Organized by priority rather than urgency
195
+ - Not time-bound (unlike Cycles)
196
+ - Teams can have multiple backlog statuses (e.g., "Icebox", "Backlog")
197
+
198
+ **Flow Summary**:
199
+
200
+ ```
201
+ External Input → Triage → Backlog → Todo → In Progress → Done
202
+
203
+ (Declined)
204
+
205
+ Canceled
206
+ ```
207
+
208
+ ---
209
+
210
+ ## 3. Linear Asks (Slack/Email Intake)
211
+
212
+ Linear Asks transforms workplace requests from Slack and email into actionable Linear issues.
213
+
214
+ ### How It Works with Slack
215
+
216
+ **Request Creation Methods**:
217
+
218
+ 1. React with the ticket emoji to any Slack message
219
+ 2. Use `/asks` slash command
220
+ 3. Mention `@Linear Asks` in messages
221
+ 4. Create private Asks via Direct Messages
222
+ 5. Auto-create through configured channels
223
+
224
+ **Key Features**:
225
+
226
+ - Non-Linear users can submit requests (Business/Enterprise plans)
227
+ - Synced comment thread between Slack and Linear
228
+ - Real-time status updates delivered to original Slack channel
229
+ - Works in shared Slack Connect channels
230
+
231
+ ### Templates and Configuration
232
+
233
+ - Create channel-specific templates with custom fields
234
+ - Set required fields to standardize every request
235
+ - Pre-populate issue properties automatically
236
+ - All Asks route to team's Triage for review
237
+
238
+ ### Email Intake
239
+
240
+ - Forward custom email addresses to unique Linear intake addresses
241
+ - Email subject becomes issue title
242
+ - Email body becomes description
243
+ - Attachments supported (25 MB limit)
244
+
245
+ **Availability**: Business and Enterprise plans. Advanced features on Enterprise.
246
+
247
+ ---
248
+
249
+ ## 4. Issue States and Workflow Customization
250
+
251
+ ### Status Categories
252
+
253
+ Linear organizes workflows into five default categories that cannot be reordered:
254
+
255
+ 1. **Backlog** - Unstarted work waiting to be prioritized
256
+ 2. **Todo** (Unstarted) - Work ready to begin
257
+ 3. **In Progress** (Started) - Active work
258
+ 4. **Done** (Completed) - Finished work
259
+ 5. **Canceled** - Rejected or abandoned work
260
+
261
+ Additionally:
262
+
263
+ - **Triage** - Optional inbox category for review before acceptance
264
+
265
+ ### Default Workflow
266
+
267
+ ```
268
+ Backlog → Todo → In Progress → Done
269
+ ↘ Canceled
270
+ ```
271
+
272
+ ### Customizing Statuses
273
+
274
+ **Access**: Settings → Teams → Issue statuses & automations
275
+
276
+ **What You Can Customize**:
277
+
278
+ - Add new statuses within any category (click `+` button)
279
+ - Edit status names, colors, and descriptions
280
+ - Reorder statuses within a category (drag and drop)
281
+ - Remove statuses (minimum one per category required)
282
+ - Set default status for new issues
283
+
284
+ **What You Cannot Customize**:
285
+
286
+ - Category order (Backlog → Todo → In Progress → Done → Canceled is fixed)
287
+ - Category names
288
+
289
+ ### Example Custom Workflow (Linear's Product Team)
290
+
291
+ ```
292
+ Backlog: Icebox, Backlog
293
+ Unstarted: Todo
294
+ Started: In Progress, In Review, Ready to Merge
295
+ Completed: Done
296
+ Canceled: Canceled, Could not reproduce, Won't Fix, Duplicate
297
+ ```
298
+
299
+ ### Status Automations
300
+
301
+ **Auto-Close**: Automatically closes issues inactive for a specified period
302
+
303
+ - Marks as Canceled status type
304
+ - Publishes history item to Activity feed
305
+ - Notifies subscribers
306
+ - Won't auto-close issues in active cycles/projects
307
+
308
+ **Auto-Archive**: Archives issues that have been closed for several months
309
+
310
+ - Archives happen automatically (no manual option)
311
+ - Configurable time period in Team Settings
312
+ - Creator notified when archived (opportunity to unarchive)
313
+ - Archived issues remain searchable and restorable
314
+ - Extends to completed Cycles and Projects
315
+
316
+ **Default Settings**: Auto-close and auto-archive are enabled by default for new teams.
317
+
318
+ ### Duplicate Handling
319
+
320
+ Marked duplicates automatically receive Canceled status. You can customize to use alternatives like "Duplicate" status.
321
+
322
+ ---
323
+
324
+ ## 5. Priority System
325
+
326
+ ### Priority Levels
327
+
328
+ Linear offers five priority levels:
329
+
330
+ | Priority | Shortcut | Use Case |
331
+ | ----------- | ------------ | ---------------------------- |
332
+ | Urgent | `P` then `1` | Immediate attention required |
333
+ | High | `P` then `2` | Important, schedule soon |
334
+ | Medium | `P` then `3` | Normal priority |
335
+ | Low | `P` then `4` | Nice to have |
336
+ | No Priority | `P` then `0` | Unset/unspecified |
337
+
338
+ **Note**: Linear intentionally does not allow custom priorities. "Adding too many options makes it harder to set priority and leads to diminishing returns."
339
+
340
+ ### Micro-Adjusting Priority Order
341
+
342
+ On any view ordered by priority:
343
+
344
+ 1. Drag and drop issues to reorder within the same priority level
345
+ 2. Position is saved globally across your workspace
346
+ 3. All team members see the same relative positions
347
+
348
+ ---
349
+
350
+ ## 6. Estimation System
351
+
352
+ ### Available Scales
353
+
354
+ Teams can choose from four estimation scales:
355
+
356
+ | Scale | Values | Extended |
357
+ | ----------- | --------------- | --------- |
358
+ | Exponential | 1, 2, 4, 8, 16 | 32, 64 |
359
+ | Fibonacci | 1, 2, 3, 5, 8 | 13, 21 |
360
+ | Linear | 1, 2, 3, 4, 5 | 6, 7 |
361
+ | T-Shirt | XS, S, M, L, XL | XXL, XXXL |
362
+
363
+ T-Shirt sizes convert to Fibonacci values for numerical calculations.
364
+
365
+ ### Configuration
366
+
367
+ **Access**: Team Settings → General → Estimates
368
+
369
+ **Options**:
370
+
371
+ - Enable/disable estimates per team
372
+ - Extended scales (adds two higher values)
373
+ - Allow zero estimates
374
+ - Default handling for unestimated issues (default: 1 point)
375
+
376
+ **Keyboard Shortcut**: `Shift + E` to add/edit estimates
377
+
378
+ ### Best Practice
379
+
380
+ "Larger estimates usually mean that there is uncertainty about the issue's complexity. We find that breaking up issues into smaller ones is the best approach."
381
+
382
+ ---
383
+
384
+ ## 7. Labels and Organization
385
+
386
+ ### Label Scope
387
+
388
+ - **Workspace labels**: Accessible to all teams (e.g., "Bug", "Feature")
389
+ - **Team labels**: Scoped to specific teams only
390
+
391
+ ### Label Groups
392
+
393
+ - Provide organizational nesting
394
+ - Maximum 250 labels per group
395
+ - Labels within groups are NOT multi-selectable (only one label per group can be applied)
396
+
397
+ ### Creating Labels
398
+
399
+ **Three Methods**:
400
+
401
+ 1. Settings → Workspace → Labels (or Team → Labels)
402
+ 2. During label application: type new name, auto-saves
403
+ 3. Syntax shortcut: `group/label` or `group:label` (e.g., "Type/Bug" creates both)
404
+
405
+ **Keyboard Shortcut**: `L` to add/edit labels
406
+
407
+ ### Label Descriptions
408
+
409
+ Add descriptions in label settings. They:
410
+
411
+ - Appear on hover over applied labels
412
+ - Help maintain consistent usage
413
+ - Inform Triage Intelligence suggestions
414
+
415
+ ### Reserved Label Names
416
+
417
+ Cannot use: assignee, cycle, effort, estimate, hours, priority, project, state, status
418
+
419
+ ### Managing Labels
420
+
421
+ - Merge duplicate labels
422
+ - Archive labels (keeps on existing issues, prevents future use)
423
+ - Delete labels (irreversible, removes from all issues)
424
+ - Move between workspace and team levels
425
+
426
+ ---
427
+
428
+ ## 8. Cycles (Time-Boxed Sprints)
429
+
430
+ ### Overview
431
+
432
+ Cycles are Linear's equivalent to sprints - fixed-duration time periods for completing work.
433
+
434
+ **Navigation**: `G` then `C` (Go to Cycles) or `G` then `V` (current cycle)
435
+
436
+ ### Configuration
437
+
438
+ **Enable**: Team Settings → Cycles → Enable cycles
439
+
440
+ **Duration Options**: 1-8 weeks (fixed intervals, cannot vary)
441
+
442
+ **Schedule**: Set start day of week; cycles auto-generate on schedule
443
+
444
+ ### Key Features
445
+
446
+ - **Automatic rollover**: Incomplete issues roll to next cycle automatically
447
+ - **Cooldown periods**: Optional breaks between cycles for tech debt/planning
448
+ - **Upcoming cycles**: Pre-create up to 15 future cycles
449
+ - **Auto-add**: Automatically assign started issues lacking cycle assignment
450
+
451
+ ### Capacity Planning
452
+
453
+ The capacity dial estimates completion likelihood based on:
454
+
455
+ - Team's velocity from previous three completed cycles
456
+ - Measured by issues or estimate points completed
457
+
458
+ ### Cycles vs. Projects
459
+
460
+ | Aspect | Cycles | Projects |
461
+ | ---------- | -------------------- | ------------------ |
462
+ | Time-bound | Yes (fixed duration) | Yes (but flexible) |
463
+ | Thematic | No | Yes |
464
+ | Auto-recur | Yes | No |
465
+ | Cross-team | No | Yes |
466
+ | Releases | Not tied | Can be tied |
467
+
468
+ ---
469
+
470
+ ## 9. Projects and Roadmaps
471
+
472
+ ### Projects
473
+
474
+ **Purpose**: Time-bound deliverables like launching a new feature.
475
+
476
+ **Characteristics**:
477
+
478
+ - Can span multiple teams
479
+ - Contains milestones (meaningful completion stages)
480
+ - Has its own status (Backlog, Planned, In Progress, Completed, Canceled)
481
+ - Can have priority, labels, and lead assignee
482
+
483
+ ### Milestones
484
+
485
+ Represent meaningful completion stages within a project. Enable progress tracking at granular level.
486
+
487
+ ### Roadmaps
488
+
489
+ **Purpose**: High-level overview of projects for alignment with long-term goals.
490
+
491
+ - Group projects into roadmap sections
492
+ - Define goals and milestones
493
+ - Provide visibility into active, planned, and completed initiatives
494
+ - Visual timeline view
495
+
496
+ ### Initiatives
497
+
498
+ Manually curated collections of projects that showcase company goals. Enable executive-level planning across extended timelines.
499
+
500
+ ### Hierarchy
501
+
502
+ ```
503
+ Workspace
504
+ ├── Team 1
505
+ │ ├── Issues (in Backlog, Cycles, or Projects)
506
+ │ ├── Cycles
507
+ │ ├── Projects
508
+ │ │ └── Milestones
509
+ │ └── Issue Views
510
+ ├── Team 2
511
+ └── Project Views & Initiatives (workspace-level)
512
+ ```
513
+
514
+ ---
515
+
516
+ ## 10. Complete Keyboard Shortcuts Reference
517
+
518
+ ### Navigation
519
+
520
+ | Shortcut | Action |
521
+ | -------- | ---------------------------- |
522
+ | `G, I` | Go to Inbox |
523
+ | `G, M` | Go to My Issues |
524
+ | `G, A` | Go to Active Issues |
525
+ | `G, B` | Go to Backlog |
526
+ | `G, D` | Go to Board |
527
+ | `G, C` | Go to Cycles |
528
+ | `G, V` | Go to current cycle (View) |
529
+ | `G, P` | Go to Projects |
530
+ | `G, T` | Go to Triage |
531
+ | `G, S` | Go to Settings |
532
+ | `/` | Open search |
533
+ | `?` | Show keyboard shortcuts help |
534
+
535
+ ### Issue Actions
536
+
537
+ | Shortcut | Action |
538
+ | -------------- | -------------------------- |
539
+ | `C` | Create new issue |
540
+ | `V` | Create issue (full screen) |
541
+ | `Option/Alt C` | Create from template |
542
+ | `E` | Edit issue |
543
+ | `A` | Assign to user |
544
+ | `I` | Assign to me |
545
+ | `L` | Add/edit label |
546
+ | `S` | Change status |
547
+ | `P` | Change priority |
548
+ | `Shift + E` | Set estimate |
549
+ | `Cmd/Ctrl D` | Set due date |
550
+ | `#` | Archive issue |
551
+ | `Backspace` | Delete (in list) |
552
+
553
+ ### Issue Relations
554
+
555
+ | Shortcut | Action |
556
+ | ------------------------- | ----------------------- |
557
+ | `M, B` | Mark as blocked |
558
+ | `M, X` | Mark as blocking |
559
+ | `M, R` | Reference related issue |
560
+ | `M, M` (or `2` in triage) | Mark as duplicate |
561
+
562
+ ### Selection and Navigation
563
+
564
+ | Shortcut | Action |
565
+ | ----------------- | ------------------------- |
566
+ | `X` | Select item in list |
567
+ | `Shift + Click` | Select multiple items |
568
+ | `Shift + Up/Down` | Extend selection |
569
+ | `Esc` | Clear selection / Go back |
570
+ | `J / K` | Move down/up |
571
+ | `Arrow keys` | Navigate |
572
+ | `Enter` or `O` | Open focused item |
573
+ | `Space` (hold) | Peek into issue |
574
+
575
+ ### Command Palette
576
+
577
+ | Shortcut | Action |
578
+ | ------------------ | -------------------- |
579
+ | `Cmd/Ctrl K` | Open command menu |
580
+ | `Cmd/Ctrl .` | Copy issue ID |
581
+ | `Cmd/Ctrl Shift .` | Copy git branch name |
582
+ | `Cmd/Ctrl Shift O` | Create sub-issue |
583
+ | `Cmd/Ctrl M` | Comment on issue |
584
+
585
+ ### Filtering
586
+
587
+ | Shortcut | Action |
588
+ | -------------------- | ----------------- |
589
+ | `F` | Open filter menu |
590
+ | `Shift + F` | Clear last filter |
591
+ | `Option/Alt Shift F` | Clear all filters |
592
+
593
+ ### Editor Formatting
594
+
595
+ | Shortcut | Action |
596
+ | ------------------ | ------------- |
597
+ | `Cmd/Ctrl B` | Bold |
598
+ | `Cmd/Ctrl I` | Italic |
599
+ | `Cmd/Ctrl U` | Underline |
600
+ | `Cmd/Ctrl Shift \` | Code block |
601
+ | `Cmd/Ctrl Shift 7` | Numbered list |
602
+ | `Cmd/Ctrl Shift 8` | Bulleted list |
603
+ | `Cmd/Ctrl Shift 9` | Todo list |
604
+ | `Cmd/Ctrl Z` | Undo |
605
+ | `Cmd/Ctrl Shift Z` | Redo |
606
+
607
+ ### Triage Specific
608
+
609
+ | Shortcut | Action |
610
+ | -------- | ----------------- |
611
+ | `1` | Accept issue |
612
+ | `2` | Mark as duplicate |
613
+ | `3` | Decline issue |
614
+ | `H` | Snooze issue |
615
+
616
+ ### Inbox Specific
617
+
618
+ | Shortcut | Action |
619
+ | ------------------- | ------------------------ |
620
+ | `U` | Mark read/unread |
621
+ | `Option/Alt U` | Mark all read/unread |
622
+ | `Backspace` | Delete notification |
623
+ | `Shift + Backspace` | Delete all notifications |
624
+ | `Cmd/Ctrl D` | Delete all read |
625
+ | `H` | Snooze notification |
626
+ | `Shift + S` | Unsubscribe from issue |
627
+
628
+ ---
629
+
630
+ ## 11. Linear vs. Jira vs. GitHub Issues: Philosophy
631
+
632
+ ### Linear's Philosophy
633
+
634
+ **"Opinionated Software"**: Linear is purpose-built for helping teams build better products. Unlike general-purpose tools, it guides you toward a default process.
635
+
636
+ Core beliefs:
637
+
638
+ 1. **Purpose-built software** - Flexible software lets everyone invent their own workflows, creating chaos at scale
639
+ 2. **Simple terminology** - Don't invent terms; projects should be called projects
640
+ 3. **Tasks over user stories** - Write short, simple issues in plain language; user stories are considered an anti-pattern
641
+ 4. **Work in cycles** - Maintain healthy momentum, not rushing toward the end
642
+ 5. **Designer-engineer collaboration** - Best creators have talent for both
643
+
644
+ **Speed as Feature**: Linear loads approximately 2x faster than Jira. Every interaction is optimized for keyboard-first workflow.
645
+
646
+ ### Jira's Philosophy
647
+
648
+ **"Customizable Workflow Engine"**: Jira offers extreme flexibility for every team to configure their own process.
649
+
650
+ Characteristics:
651
+
652
+ - Highly customizable workflows, fields, issue types
653
+ - Complex hierarchies and dependencies
654
+ - Extensive reporting and dashboards
655
+ - 3,000+ integrations via Atlassian Marketplace
656
+ - Native integration with Bitbucket, Confluence
657
+ - Designed for enterprise (1000+ employees)
658
+
659
+ **Target**: Enterprise engineering teams using traditional Scrum/Agile methodologies.
660
+
661
+ ### GitHub Issues Philosophy
662
+
663
+ **"Code-Centric Project Management"**: Keep everything inside the development environment.
664
+
665
+ Characteristics:
666
+
667
+ - Tightly tied to code repositories
668
+ - Lightweight agility (not ideal for SCRUM ceremonies)
669
+ - Tag-based organization with project boards
670
+ - GitHub Actions for automation
671
+ - Best for teams that "live in code"
672
+
673
+ ### Comparison Summary
674
+
675
+ | Aspect | Linear | Jira | GitHub Issues |
676
+ | ----------------- | ----------------------- | ---------------------------- | ------------------------- |
677
+ | Philosophy | Opinionated, fast | Flexible, comprehensive | Code-centric, lightweight |
678
+ | Setup Time | Minutes | Hours to days | Minutes |
679
+ | Learning Curve | Low | High | Low |
680
+ | Customization | Limited by design | Extensive | Moderate |
681
+ | Speed | Very fast | Slower | Fast |
682
+ | Best For | Startups, product teams | Enterprise, complex projects | Dev teams in GitHub |
683
+ | Integration Count | 200+ | 3,000+ | GitHub ecosystem |
684
+ | Pricing Model | Per-user | Per-user | Included with GitHub |
685
+
686
+ ### When to Choose Each
687
+
688
+ **Choose Linear if**:
689
+
690
+ - You want speed and minimal setup
691
+ - You prefer opinionated defaults over configuration
692
+ - Your team is small to medium-sized
693
+ - You value clean, modern UI
694
+ - You want to reduce decision fatigue
695
+
696
+ **Choose Jira if**:
697
+
698
+ - You need custom workflows and hierarchies
699
+ - You have complex reporting requirements
700
+ - You're in a large enterprise environment
701
+ - You need extensive third-party integrations
702
+ - You use other Atlassian products
703
+
704
+ **Choose GitHub Issues if**:
705
+
706
+ - Your team lives in GitHub
707
+ - You prefer minimal tooling
708
+ - You want everything in one place
709
+ - You have simple project management needs
710
+
711
+ ---
712
+
713
+ ## 12. Best Practices Summary
714
+
715
+ ### Issue Capture
716
+
717
+ 1. Use `C` for rapid issue creation
718
+ 2. Set up Raycast/Alfred for global hotkey access
719
+ 3. Leverage Linear Asks for non-technical team members
720
+ 4. Use templates for standardized intake
721
+
722
+ ### Triage Management
723
+
724
+ 1. Review triage inbox daily
725
+ 2. Rotate triage responsibility among team
726
+ 3. Use Triage Intelligence suggestions (Business/Enterprise)
727
+ 4. Set up triage rules for automation (Enterprise)
728
+
729
+ ### Backlog Health
730
+
731
+ 1. Keep backlog clean and prioritized
732
+ 2. Enable auto-close for stale issues
733
+ 3. Enable auto-archive for completed work
734
+ 4. Break large issues into smaller ones
735
+
736
+ ### Workflow Customization
737
+
738
+ 1. Start with Linear's defaults
739
+ 2. Only customize when pain points arise
740
+ 3. Keep statuses minimal and meaningful
741
+ 4. Use consistent label naming conventions
742
+
743
+ ### Keyboard-First Workflow
744
+
745
+ 1. Learn navigation shortcuts (`G` + letter)
746
+ 2. Use command palette (`Cmd/Ctrl K`) for discovery
747
+ 3. Master issue actions (`C`, `S`, `P`, `L`, `A`)
748
+ 4. Use peek (`Space` hold) for quick preview
749
+
750
+ ---
751
+
752
+ ## Sources
753
+
754
+ - [Linear Triage Documentation](https://linear.app/docs/triage)
755
+ - [Linear Issue Status Configuration](https://linear.app/docs/configuring-workflows)
756
+ - [Linear Conceptual Model](https://linear.app/docs/conceptual-model)
757
+ - [Linear Cycles Documentation](https://linear.app/docs/use-cycles)
758
+ - [Linear Creating Issues](https://linear.app/docs/creating-issues)
759
+ - [Linear Inbox Documentation](https://linear.app/docs/inbox)
760
+ - [Linear Asks Documentation](https://linear.app/docs/linear-asks)
761
+ - [Linear Estimates Documentation](https://linear.app/docs/estimates)
762
+ - [Linear Labels Documentation](https://linear.app/docs/labels)
763
+ - [Linear Priority Documentation](https://linear.app/docs/priority)
764
+ - [Linear Method Principles](https://linear.app/method/introduction)
765
+ - [Linear Keyboard Shortcuts - KeyCombiner](https://keycombiner.com/collections/linear/)
766
+ - [Linear vs Jira 2026 Guide - Everhour](https://everhour.com/blog/linear-vs-jira/)
767
+ - [Linear vs Jira Comparison - Nuclino](https://www.nuclino.com/solutions/linear-vs-jira)
768
+ - [Linear Review 2026 - Work Management](https://work-management.org/software-development/linear-review/)
769
+ - [How to Use Linear - Morgen](https://www.morgen.so/blog-posts/linear-project-management)
770
+ - [The Linear Method: Opinionated Software - Figma Blog](https://www.figma.com/blog/the-linear-method-opinionated-software/)
771
+ - [Linear: Designing for Developers - Sequoia Capital](https://sequoiacap.com/article/linear-spotlight/)