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](git-workflow.md#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.

## 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.

```markdown
## 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.

```markdown
## 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 Branches, Commits, and PRs

The Jira key goes in the branch name, the PR title, and the commit `Refs:` trailer, which threads the code into the issue's development panel. The mechanics are covered in [git-workflow.md](git-workflow.md#linking-to-jira) and [commit-messages.md](commit-messages.md#referencing-issues).