docs: add linear-ticket-format org standard#1
Merged
Conversation
📝 WalkthroughWalkthroughAdds a new documentation file establishing a formatting standard for Linear tickets, specifying metadata fields and markdown style rules including header structure, summary formatting, and prohibited elements like em dashes, emoji, and footers. ChangesLinear Ticket Format Documentation
Estimated code review effort: 1 (Trivial) | ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsThese MCP integrations need to be re-authenticated in the Integrations settings: Linear Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@entries/org/linear-ticket-format.md`:
- Around line 2-7: Update the Linear ticket standard in the markdown doc so it
is self-consistent and lint-friendly: the body text should follow the same
no-em-dash, scannable structure it describes, not a single prose paragraph.
Revise the content under the standard to use plain text sections and bullets,
and ensure the summary/title guidance is formatted to avoid MD041 by making the
first visible content line start with real content, not a paragraph placeholder.
Keep the changes aligned with the existing standard text in the document and the
“Summary”/“Links” conventions it defines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 28efc3dc-1aaa-46d7-8926-1c982e0c15db
📒 Files selected for processing (1)
entries/org/linear-ticket-format.md
Comment on lines
+2
to
+7
| description: Linear tickets use clean, scannable markdown — short title, links under labels, no emoji or middots | ||
| type: standard | ||
| author: sneroboto | ||
| date: 2026-07-02 | ||
| --- | ||
| Keep Linear tickets clean and scannable. No em dashes (use "-" or parentheses). Title is short, e.g. "Homepage - Figma/live site parity", not a long title padded with counts. In a Links section, each label is an H4 with no colon ("Figma design", "Live site", "Summary") and the URL sits on the line directly below the label, not inline. No emoji status dots in headers or the summary — keep headers plain text. Make "Summary" a bullet list, not a middot-separated line. No filler sentences (e.g. "Depth: existence-only, not a pixel diff") and avoid "·" middot separators — use bullets or commas. Do not end the ticket with a horizontal divider or a "Generated by" footer. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Make the standard self-consistent and lint-friendly.
The description/body still use em dashes, and the main content is a single paragraph instead of a scannable structure. That conflicts with the rule set you’re defining and matches the MD041 warning on the first visible content line.
Proposed shape
----
-description: Linear tickets use clean, scannable markdown — short title, links under labels, no emoji or middots
+description: Linear tickets use clean, scannable markdown - short title, links under labels, no emoji or middots
type: standard
author: sneroboto
date: 2026-07-02
---
-Keep Linear tickets clean and scannable. No em dashes...
+## Linear ticket format
+
+- Keep titles short.
+- Put each link label in an H4.
+- Put the URL on the next line.
+- Use plain-text headers and bullet lists.
+- Avoid em dashes, middots, and footer text.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| description: Linear tickets use clean, scannable markdown — short title, links under labels, no emoji or middots | |
| type: standard | |
| author: sneroboto | |
| date: 2026-07-02 | |
| --- | |
| Keep Linear tickets clean and scannable. No em dashes (use "-" or parentheses). Title is short, e.g. "Homepage - Figma/live site parity", not a long title padded with counts. In a Links section, each label is an H4 with no colon ("Figma design", "Live site", "Summary") and the URL sits on the line directly below the label, not inline. No emoji status dots in headers or the summary — keep headers plain text. Make "Summary" a bullet list, not a middot-separated line. No filler sentences (e.g. "Depth: existence-only, not a pixel diff") and avoid "·" middot separators — use bullets or commas. Do not end the ticket with a horizontal divider or a "Generated by" footer. | |
| description: Linear tickets use clean, scannable markdown - short title, links under labels, no emoji or middots | |
| type: standard | |
| author: sneroboto | |
| date: 2026-07-02 | |
| --- | |
| ## Linear ticket format | |
| - Keep titles short. | |
| - Put each link label in an H4. | |
| - Put the URL on the next line. | |
| - Use plain-text headers and bullet lists. | |
| - Avoid em dashes, middots, and footer text. |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 7-7: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@entries/org/linear-ticket-format.md` around lines 2 - 7, Update the Linear
ticket standard in the markdown doc so it is self-consistent and lint-friendly:
the body text should follow the same no-em-dash, scannable structure it
describes, not a single prose paragraph. Revise the content under the standard
to use plain text sections and bullets, and ensure the summary/title guidance is
formatted to avoid MD041 by making the first visible content line start with
real content, not a paragraph placeholder. Keep the changes aligned with the
existing standard text in the document and the “Summary”/“Links” conventions it
defines.
Source: Linters/SAST tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an org Standard
linear-ticket-formatthat captures how we format Linear tickets: short titles, a Links section with H4 labels and the URL on the line below, plain-text headers (no emoji dots), a bulleted Summary, no em dashes, no middot separators, no filler sentences, and no trailing divider or footer.Why
Keeps tickets clean and scannable, and codifies the convention so both people and agents format tickets the same way.
Scope
org(everyone writes tickets). Owners: narrow the scope if you prefer it at squad level.Verification
roboto-mem lintpasses locally (22 entries, 0 problems).Summary by CodeRabbit