Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

docs(brain): Linear Tickets page for the ENG Feature and Bug templates (#16739)

Othman Abu Ajamiehaa9ea4c8d03c
diff --git a/brain/knowledge/engineering/index.md b/brain/knowledge/engineering/index.md
index c9dfda6c6c0..d51671937d5 100644
--- a/brain/knowledge/engineering/index.md
+++ b/brain/knowledge/engineering/index.md
@@ -37,6 +37,7 @@ The **Activepieces engineering brain**: how the system works, and *why* it was b
- **Helm Chart** — the Kubernetes install we ship to self-hosters, its two competing paths for an `AP_*` variable, and the secrets it never creates
- **CI Pipeline** — the PR checks that build and test a change: the affected-packages gate, the api matrix, and why install and test time grew
- **CI PR Review Hygiene** — draft-first Greptile review, the per-area PR size gate, and the workflow conventions reviewers keep re-litigating
+- **Linear Tickets** — the Feature and Bug templates of the Engineering team, their section names, and the E2E tag on each acceptance criterion
- **E2E Tests & Monitors** — the one Playwright suite behind CI, the Checkly monitors that run it against production Cloud, and the BetterStack script the repo pushes on merge
- **Architecture Spine** — the load-bearing structure of the codebase, and the gotchas that come with it: request-body `.max()` as data loss, TypeORM soft-delete across a canary window, and canary not proxying websockets
- **Reproduce a Self-Hoster's Proxy Topology** — standing up a reverse proxy, a second hostname, a path prefix and a real SAML IdP locally, so a redirect or discovery bug can be measured instead of argued about
diff --git a/brain/knowledge/engineering/linear-tickets.md b/brain/knowledge/engineering/linear-tickets.md
new file mode 100644
index 00000000000..3ea574ada89
--- /dev/null
+++ b/brain/knowledge/engineering/linear-tickets.md
@@ -0,0 +1,27 @@
+---
+icon: 🎫
+---
+
+# Linear Tickets
+
+How a ticket in the Engineering (ENG) Linear team is written, so people and agents find the scope by heading. The headings below are a contract: agents read and edit sections by these exact names.
+
+**Feature ticket** — an ENG ticket made from the Feature template: `Problem`, `Acceptance criteria`, `Decisions`. The default for team members; presets `🌟 feature` and Backlog.
+**Bug ticket** — an ENG ticket made from the Bug template: `Problem`, `Where`, `Steps to reproduce`, `Expected result`, `Acceptance criteria`, `Decisions`. The default for non-members; presets `🐛 bug` and Triage.
+**Problem** — what is wrong today and for whom. On a Bug ticket, the actual result.
+**Where** — the edition (Cloud, self-hosted CE, self-hosted EE), the surface (app, Embed, MCP client), the version, and a link to the flow or run.
+**Steps to reproduce** — numbered steps another engineer can repeat.
+**Expected result** — what must happen instead, in the reporter's words. The engineer turns it into acceptance criteria.
+**Acceptance criteria** — one check per bullet; each bullet ends with ``E2E: `<test title>` `` or `no-e2e: <reason>`. The contract for done. On a Bug ticket the engineer writes them at triage. _Avoid_: "Done when"
+**Decisions** — one decision per bullet with a one-line why. Out of scope is a decision: "Not X, because Y."
+**no-e2e** — the ticket label for one or more criteria with no E2E test. The bullet markers are the source; the label follows them.
+**Done** — the PR is merged.
+
+## Gotchas
+
+- The AI team keeps its own form templates (Goal / Done when / How) and the `ai-task` skill. The two vocabularies differ on purpose for now.
+- The template text lives in Linear, not in the repo. Renaming a heading means changing the template, this page and the agent rule together.
+- Placeholder text in a template disappears when the writer types, so no rule may live only in a placeholder. Rules live here and in the agent rule.
+- A ticket created through the MCP, the API, Slack or a support integration gets no template, so it can miss headings. The team default applies only in the Linear UI: an agent creating a ticket passes `template: "Feature"` or `"Bug"` to `save_issue`, and adds a missing heading rather than assume the section is empty.
+- A template applied through the MCP keeps the headings and presets but strips the placeholder text, so the sections arrive empty.
+- Both templates are standard templates. A form template may not write the `##` headings that agents parse.