The last article named a comment format in passing: marker on line 1, byline on line 2, six required sections below (six for readiness; the count varies by phase). It moved on because all it needed from the format was that an auditor can write things an author can't. This article is about the format itself. Why it's fixed, and what each part does.
A human team's documentation is a mix. Some of it is conversation. Some of it is the team's substrate: the ways-of-working playbooks and conventions that govern what gets written and how. The whole team has often not read that substrate, and people absorb the gap through intuition and each other.
For an agentic team, the part of an item's documentation that carries state stops being something readers can work around. It becomes load-bearing state: the substantive evidence that a phase happened, in a shape the next actor can read at a glance. Once documentation is state, its grammar has to be treated as protocol rather than prose.
Two kinds of comment
Open any Jira item that's been through a few humans. You'll see comments that fall roughly into two categories.
Some are conversational. "Do we want to include archived users?" "Yeah, probably, but check with Barry." "OK, going to assume yes for now." This is how humans work. The comments are context; the actual state of the item is somewhere else, in someone's head or in the code.
Others are structural, even if nobody labels them that way. The comment that says "deployed to staging, verified the migration ran" is not conversation; it's evidence that a specific thing happened, and downstream actors will take it at face value. The comment that says "approved to merge" has the same shape. Nobody is going to reply to it with an opinion. It's a state change dressed up as a comment.
Human teams handle the mix by intuition. They know which comments are conversation and which are state. Agents can't. Left to their own devices they will treat every comment as advisory prose, weighted by recency and vibe, and they will read the discussion of whether to include archived users as if it were the answer.
The workflow's job is to say, structurally, which is which, and to make the state comments unmistakable.
Markers on line 1
The mechanism this project uses is small and consistent. State-carrying comments open with a phase marker in bold, on line one. The marker is drawn from a fixed vocabulary, one phrase per outcome per phase:
Phase | Forward | Back to refine | Unclaim (could not do it) |
|---|
Refinement | Refinement: SHAPED | Refinement: NEEDS DECISION | Refinement: NOT REFINED |
Readiness | Readiness: READY | Readiness: NOT READY | Readiness: NOT ASSESSED |
Development | Development: COMPLETE | Development: SPEC WRONG | Development: NOT COMPLETED |
Review | Review: APPROVED | Review: CHANGES REQUESTED (code, back to development) Review: SPEC WRONG (spec, back to refinement) | Review: NOT REVIEWED |
Thirteen markers in the current vocabulary: three each for refinement, readiness and development, and four for review, whose "back" has two destinations, since the code returns to development and the specification returns to refinement. Every one of them is a fixed string. No synonyms, no variants, no "looks like the item is good to go" readings. The grammar is fixed on purpose, because it is the thing the next actor's intake gate scans for.
The intake gate from article 3 doesn't do sentiment analysis on the previous phase's output. It looks for a specific string, in a specific place, posted after a specific claim transition. When the readiness reviewer's marker reads "Readiness: READY", exactly that, on line 1 of a comment, in bold, the development-phase entry check passes.
When it reads "Readiness: ready to go" or "item is READY", the entry check fails. The reviewer had good intentions; the workflow can't tell.
Fixed grammar means the reviewer's comment survives translation from the reviewer's prose into the development agent's parsing without loss. It also means the analyst returning the item on a NOT READY verdict knows exactly what shape their next intake check is going to look for, because the shape is the same for every item.
Bylines on line 2
Line 2 of a state-carrying comment is a byline, in italics:
Author: Bulbasaur (7f3a1c9d) · Via: Claude Code CLI
Two pieces of additional attribution context, structurally embedded with each comment, provide quick visual context that’s baked into the change history:
- Author: which session wrote the comment. It is a session name handed to the agent at startup, a character name plus a short hash suffix, used verbatim for every comment in that session. It is never introspected: not the model the agent believes itself to be, and not a role. A model name reads as fact when the agent cannot reliably know it. Where no session name exists the fallback is the configured identity (for the Jira-hosted agents, Claude Agent for Jira), then Unrecognised Agent.
- Via: how the agent was invoked. One of ten fixed values, verbatim, with nothing appended: Jira board transition, Jira
@mention, Jira assignment, Jira Agent panel, Jira automation, Claude Code CLI, GitHub Copilot CLI, Rovo Dev CLI, IDE, or unknown. This makes the tool substitutability from article 4 observable in the record. Worktree and branch names belong in the comment body, not here.
There is deliberately no third attribution point for the human principal. This project’s agents, Claude and GitHub Copilot, act through service accounts. As a result, the account Jira shows beside a comment already makes clear that an agent did the work. On an agentic team, we can also treat that work as having been carried out end to end by the agent.
If an agent does post through a human’s account (say, because no service account has access), the byline still names the agent session and how it was invoked. The role isn’t in the byline either: the phase marker on line 1 already says which phase’s skill was speaking.
The byline captures context Jira can’t: which agent wrote the comment under a shared account, and how it was invoked. Weeks later, someone can see which session signed off and how, without having to dig through logs or history.
Reference note: As discussed in article part 6, the byline also gives agents enough attribution context to run independence checks, such as confirming they are not “marking their own homework.” Achieving the same safeguard through account attribution alone would require every agent to use a unique account, or every agent to run in a fresh session for each task. The latter is much harder to control when agents are used through CLI or IDE-based interaction surfaces.
Note: Atlassian's platform-level Agentic Multiplayer Protocol (AMP), announced at Team '26 Europe, is designed to improve context-sharing and agent attribution across tools, and will keep evolving on that front. The byline makes the same thing explicit at the workflow level.
So what does this actually buy you? A paper trail that doesn't rely on anyone's memory.
The reason it sits on line 2, in a fixed shape, is that a machine reads it. Before a readiness reviewer claims an item it runs a check that compares the Author on the refinement markers against its own session name, and a code reviewer does the same against the development markers. The strings must match exactly, suffix included; a match means the auditor is looking at its own work and must stop. So it's a check, not a courtesy. To be fair, there are limits: only suffixed session names are comparable, the byline is self-reported, and it only runs if the agent runs it.
The whole exercise is just two lines of grammar. These lines make the rest of the comment easy to find, trace, and audit. Depending on the phase, there are four to eight required sections underneath.
The AC field, not the AC heading
The other place the grammar-as-protocol rule lands hardest is the acceptance criteria.
Every Jira space I've led or administered has, at some stage, had a conversation about multi-line text fields. Should open-ended input like the Description hold everything, or should specific information get its own custom fields? Acceptance criteria are where that conversation lands hardest: should they live under a heading in the description, or in a dedicated custom field? For humans the answer is often "wherever it's easier to read", which usually means a heading. For an agentic team the answer is the field, and the reason is one query away from being obvious.
In this project the readiness reviewer runs, as a pre-check on every audit:
"Acceptance Criteria" IS EMPTY
That JQL clause tells the reviewer, before it reads a single word of the item, whether the acceptance criteria field has anything in it. If the field is empty, the review is a one-line verdict: Readiness: NOT READY because there's nothing to audit against, and the item goes straight back to refinement. No prose parsing, no heading detection, no guessing at where the analyst put the AC this time.
You cannot run that query against a description heading. Jira exposes the description as one blob of text; the "Acceptance Criteria" heading inside it is invisible to JQL. The reviewer would have to fetch the description, run its own heading extraction, and hope the analyst spelled the heading the same way as the previous items. The failure modes multiply immediately: a heading typo, a missing heading, an AC placed under a differently-named heading, an item where AC and scope have been merged under a single "Requirements" heading.
It falls apart fast.
Every one of them is now a machine-readable false positive that the workflow can't check against.
The custom field is what makes acceptance criteria queryable at scale, and queryable is what makes them enforceable. The workflow's board can visually identify any Awaiting Readiness Evaluation item whose AC field is empty. Nobody has to run the query manually. The status is visible because the field is queryable.
The same rule sits behind the marker and the AC field: if documentation carries state, put it where an automated check can read it. For a phase outcome, that is a fixed string on line 1 of a comment. For acceptance criteria in Jira, it is a custom field. Other tools will have their own version, which is usually a structured field rather than free text.
The verification clause on every criterion
Even with the AC in the right field, the AC themselves can be documentation or protocol. The rule this project uses is small, but it has big consequences: every criterion carries a verification clause.
Instead of:
Users can bulk-move issues between projects.
Write:
Users can bulk-move issues between projects. Verified by: a user in the operator role submits a valid move payload, observes each source issue's project field updated, and receives an event log entry per moved issue.
The verification clause is the reviewer's future job written down. It answers, at the moment the criterion is written, the question the reviewer will ask when the PR arrives: how do I know this passed? If the answer is "I don't know, look at the code", the criterion was under-specified, and any verdict the reviewer produces will be on the strength of its own vibe rather than a real audit.
Two things fall out of the rule. The first is that criteria without verifications stand out at a glance. The analyst can catch their own under-specification before the reviewer bounces the item. The second is that the reviewer's Review: APPROVED marker now has structural evidence behind it: the third acceptance criterion was verified by running the operator submission described above; the log entries are visible in the test output; the criterion passes. No prose, no vibe.
Under-specification of acceptance criteria is the single most common reason well-shaped items produce bad audits. The verification-clause rule doesn't remove the risk of getting the AC wrong; it makes wrong AC visible during refinement rather than during review.
The description's zones
The description isn't formless prose either. The item's description carries three zones, in order, and every phase of the workflow reads them for different purposes:
- Context. Why this item exists, what the reader needs to know that isn't in the linked issues, and what problem it's solving. This is the analyst's writing zone during cold refinement, and the developer's re-reading zone before implementation.
- Reasoning. How the analyst arrived at the shape of the item: the tier-2 decision record from part 6, plus any deliberate scoping choices. This is where "we chose per-tenant table storage on the strength of CLAUDE.md's per-tenant precedent" lives. A reviewer looking at the item three phases later reads this zone first to understand what's already been decided.
- Suggested improvement / implementation notes. Concrete pointers where the analyst can offer them without straying into tier-3 territory: existing extension points to reuse, files to read, gotchas the codebase carries. Optional; if the analyst can't offer them without inventing, the section stays empty.
The Acceptance Criteria custom field sits alongside the description, not inside it. The description tells the reader what shape this item has and why; the AC field tells the reader what has to be true for it to be done. Different questions, different homes, different queries.
Naming the zones sounds like ceremony. It isn't. The zones exist because a downstream reader, a reviewer, a later analyst returning an item for re-refinement, or a developer returning three months later to fix a bug, needs to be able to jump straight to the part of the description they need. Prose that mixes context and reasoning and pointers into a single voice forces every reader to re-parse the whole thing. Zoned prose lets the intake gate, the reviewer's rubric, and the human reader all read only the section they came for.
Grammar drift, and the discipline that fights it
The failure mode of documentation-as-contract is grammar drift. Someone posts a Readiness: OK instead of Readiness: READY because it felt more natural. Someone splits the byline across three lines because the tool auto-wrapped it. Someone "improves" the description zones with a new one called "Notes" because there wasn't an obvious place for a couple of paragraphs. Each one looks small on its own. Together they turn a workflow guarantee into a guess.
The discipline that fights drift is not "everyone remembers the format". It is:
- The grammar is written down in one place: a shared documentation skill file, in this project jira-documentation.
- Every role's skill file references it by path, per article 4's self-contained rule, so the format is present at the point of writing whether or not the documentation skill loaded.
- The intake gate refuses drift: a Readiness: OK doesn't pass a check for Readiness: READY, and the item stays where it is until the marker is right. That's hostile-feeling until you see it save you from a whole class of failure.
- New markers require a decision, not an addition. Adding a marker to the vocabulary is a workflow change, and workflow changes go through the same commitment boundary humans own for everything else. An agent that finds itself needing a marker that doesn't exist doesn't invent one; it escalates.
It's not complicated. It's how any two systems agree to talk:
- A fixed format
- Written down in one place
- Checked at the boundary
- Changed only on purpose
Software teams do this for API contracts without a second thought. The only new part is doing it for a Jira comment.
Try this before the next article
Take the handoff from "ready for development" to "in development". Most teams have one, whether or not they call it a definition of ready. Work through it from the side of the developer picking the item up, and answer four questions.
- Output. What does an item need for it to count as ready? Name the things, not the status: not "it's been refined" but "acceptance criteria that can be verified, open questions answered, dependencies named". Is that list written down, or does everyone carry their own version?
- Input. What does a developer need before they can start without asking anyone a question? Compare it with your answer to question 1. Wherever the two lists differ is where the "was this really ready?" arguments begin.
- Shape. Does the readiness evidence sit in a fixed place and form, such as acceptance criteria in a field and decisions in a labelled section, so the developer can find it at a glance? Or do they have to read the whole item and judge for themselves?
- Gate. If an item arrives that isn't ready, what happens? Does anything stop it being picked up, or does the developer find out halfway through, or by asking in a comment?
If the two lists match, the shape is fixed, and something enforces it, your definition of ready is already a contract. If not, it is an understanding, and humans make understandings work by asking each other. An agent in the developer's seat usually won't ask. It will fill the gap with a guess and present it like a fact. That guess is the substrate this whole series has been arguing against.
Next: Code-colocated docs vs. Confluence: two audiences, two disciplines. Why the docs an agent needs to act on live next to the code where they can be updated as the first step of a change, and why Confluence stays for the human-facing narrative, and what happens when you try to serve both audiences from the same page.
Every idea in my writing comes from real work — built, broken, and figured out before a single word is written. The writing is documentation, not speculation. I start with voice dictation: a raw thought dump of ideas, objectives, and what I've actually been working on. From there, I collaborate with AI to shape that into something readable — structuring drafts and editing through a custom Rovo agent, configured with carefully curated instructions to review and refine work against my preferences, personality, and style. Artwork is a separate creative process — concepts originate from my own ideas and are brought to life using a combination of Google Gemini, ChatGPT, and Photoshop. The ideas, the experience, the creative direction — those are mine. AI is how I move fast and bring them to life.
Before anything is published, every claim and every idea goes through multiple review cycles to make sure it accurately reflects the thoughts and experience I originally set out to convey. If something reads well, that's the process working. If something doesn't, that's on me.
