engineering-handbook/issue-tracking.md

Issue Tracking

Work is tracked in Jira (seahaven.atlassian.net). This page covers how tickets are written and maintained. For how tickets link to branches, commits, and PRs, see Linking to Jira.

Projects

Key	Project	Use for
PLAT	Infrastructure & Platform	AWS, networking, CI/CD, internal tooling, developer platform
SEC	Security	Findings, remediations, audits, access reviews
DEV	Product Development	Product features, application bugs, customer-facing work

Boards use the columns To Do / In Progress / Blocked / Done. SEC adds Risk Accepted for findings that are acknowledged and deliberately not remediated; a ticket moved there must say who accepted the risk and why.

INFRA is a closed-ticket archive (zero open tickets). SCRUM and SUP are idle legacy projects. Do not create new work in any of these three projects.

Ticket Description Template

Every ticket uses the same four-section description. The template is set as the default description on each project's issue types, and each project pins a TEMPLATE ticket (issue 1 in the project, e.g. PLAT-1) as the reference copy. Fill in all four sections; a section that genuinely has nothing in it should say so explicitly rather than be deleted.

## Context

## Scope

## Business rules

## Acceptance Criteria

Context

Why the work exists. Cover the background, the triggering event or finding, and the affected systems by their concrete identifiers (stack name, repo, Lambda name, hostname), not vague descriptions like "the backend". Link related tickets and PRs so the reader can trace the history without asking around.

Good	Bad
The payments-processor Lambda in the payments-dashboard stack times out on files over 10 MB. Found while working PROJ-123.	The importer is slow sometimes.

Scope

What the ticket covers, and explicitly what it does not. Naming the out-of-scope items is as important as naming the in-scope ones: it stops scope creep during the work and prevents the reader from assuming a related problem was handled. When something is out of scope, link the ticket that owns it, or create one.

Good	Bad
In scope: raise the timeout and add a size guard. Out of scope: streaming rewrite of the parser (PROJ-124).	Fix the importer.

Business rules

The constraints and invariants that must hold during and after the work. These are the conditions under which a technically complete change is still wrong: data that must not be lost, behavior that must not regress, orderings that must be respected, limits that must not be exceeded. If the implementer could pass every acceptance criterion and still break something you care about, that something belongs here.

Good	Bad
In-flight uploads must not be dropped during the deploy. Existing records keep their original IDs.	Don't break anything.

Acceptance Criteria

A checklist of independently verifiable items. Each item should be checkable on its own, and each should prefer a command or an observable state over a claim: "curl against the endpoint returns 200 with the new field" beats "the endpoint works". When the change is architectural, include the documentation update (Confluence page, project memory, README) as its own criterion; the work is not done until the docs reflect it.

## Acceptance Criteria
- [ ] A 25 MB upload completes without a timeout error in the Lambda logs
- [ ] Uploads over the 50 MB limit return 413 with a descriptive message
- [ ] The alarm on p99 duration stays out of ALARM for 24h after deploy
- [ ] The architecture page reflects the new size limit

Ticket Hygiene

Close with evidence

A ticket is closed with a comment stating what resolved it: the merged PR, the teardown date, or the successor ticket that absorbed the remaining work. "Done" with no evidence forces the next reader to reconstruct the outcome from git history.

Rewrite drifted descriptions before working them

Descriptions go stale: the affected system was renamed, half the scope was done elsewhere, the triggering finding was superseded. Before starting work on an old ticket, verify the description against current state and rewrite the parts that no longer hold. Working from a stale description produces work nobody needs.

Keep epics honest

An epic must not sit open and empty after all its children are done. Either close it with an evidence comment like any other ticket, or add the children that represent the remaining work. An open epic is a claim that work remains; keep the claim true.

Keys in PRs and Commits

The Jira key goes in the PR title as a suffix in parentheses — feat(scope): description (DEV-123) — and in the commit Refs: trailer. Branch names do not carry Jira keys. The PR-title suffix is required; the Refs: trailer is recommended. The mechanics are covered in git-workflow.md and commit-messages.md.