# Comment Templates

Canonical templates for all workflow transitions. Copy exactly, fill bracketed values.

## Comment discipline

The rules require a comment on every transition. They do not ask for a
narrative. An issue's comment history exists to be skimmed by the next
person; five long entries that each restate the last one defeat that
(FLY-1561).

- **One substantive comment per session or milestone, not per action.**
  Progress belongs in the acceptance criteria — tick them as you go with
  `issue_acceptance_update`; that is already the structured progress record.
- **Transition comments are pointers, not summaries.** Two to four lines:
  what changed, and where the detail lives (the PR, the doc, the criteria).
  Cap: about 300 words.
- **Long analysis goes in the deliverable, and the comment links it.** An
  audit, a design note, a findings list belongs in `flydocs/knowledge/` or
  the PR body, not in the comment. A progress comment tops out around 800
  words; if you need more, you are writing a document.
- **Never restate a prior comment.** Reference it ("builds on the progress
  note above") and add only what is new.
- **A correction is one line.** If a transition mis-mapped or a comment
  needs amending, say what is now true and stop.

### Provider formatting

Bodies are markdown. Linear renders it natively. Jira receives it converted
to Atlassian Document Format by the relay, which supports headings, bullet
and numbered lists, task lists, fenced code, pipe tables (a header row and a
`---` separator row), bold, italic, inline code and links. Anything outside
that subset lands as plain text. Keep comment bodies inside it, and keep
tables small — a wide table reads worse in Jira's comment column than a
list does.

---

## Capture

```
**Captured** — [Brief description of what was captured]. Type: [feature/bug/chore/idea].
```

## Triage

```
**Triaged** — Classified as [type]. Priority: P[1-4]. [Any initial observations].
```

## Refine

```
**Refined** — [What was clarified or improved]. Priority: P[1-4]. Dependencies: [list or none].
```

## Activate

```
**Activated** — Assigned to @[name]. Estimate: [XS/S/M/L/XL]. Starting implementation.
```

## Progress

Post at a milestone, not after every step. Criteria ticks are the running
record; this is the pointer to what a reader cannot see from them.

```
**Progress** — [One line: what moved]. Criteria: [X]/[Y]. Detail: [PR / doc link, or "see criteria"].
```

## Blocked

```
**Blocked** — [What is blocking progress].
**Needs:** [Specific action or decision required to unblock].
```

## Unblocked

```
**Unblocked** — [How it was resolved]. Resuming work.
```

## Ready for Review

A pointer. The PR carries the description; the criteria carry the progress.

```
**Ready for Review** — PR [link or "direct commit"]. [One or two lines: what changed, what to verify]. Criteria: [X]/[Y]. Tests: [status].
```

## Code Review Passed

```
**Code Review Passed** — Implementation meets standards. Moving to QA.
```

## Code Review: Changes Needed

```
**Code Review: Changes Needed** —

1. [Issue and suggested fix]
2. [Issue and suggested fix]

Returning to implementation.
```

## QE Approved

```
**QE Approved** — Acceptance criteria verified by user. Ready for close.
```

## QE Issues Found

```
**QE: Issues Found** —

1. [What failed or didn't meet expectations]
2. [What failed or didn't meet expectations]

Returning to implementation.
```

## QE Partial

```
**QE Partial** —

Passed:
- [Criterion that works]

Issues:
- [What needs fixing]

Returning to implementation.
```

## Close

```
**Closed** — [One-line summary of what was delivered].
```

## Archive

```
**Archived** — Deferring. Reason: [why not now].
```

## Cancel

```
**Canceled** — Not pursuing. Reason: [why].
```

## Duplicate

```
**Duplicate** — See [ISSUE-ID].
```