Software Development Life Cycle + The way we work

Assignee is not "who owns this". It is who has to act next.

The ticket is a ball. Assignee is whoever is holding it right now.

If you transition a ticket and do not change the Assignee, you have thrown the ball and left your own name on it.

🤾

Assignee — changes at almost every transition

Standard Jira field. The single person who must do the next thing. It changes six or seven times over a ticket's life — from PO, to Tech Lead, to the engineer, to QA, to DevOps, back to the engineer, and finally back to the requester.

Developer — set once, never changes

customfield_10148, a user array. The engineer who wrote the code. Set once, at Evaluation → To Do, and never touched again — not when QA rejects, not when it ships. It is how the standup dashboard groups work, and it is why a rejected ticket still shows up under the right person.

Every rejection is exactly three moves, in this order

1. Comment

   What you did, what you expected (quote the acceptance criterion verbatim), what actually happened, the evidence, the environment and the build. Written before anything else, so the reason is attached to the ticket and not to a Slack thread.

2. Reassign

   Set Assignee to the person who must act — normally the engineer named in the Developer field. Leave the Developer field alone. It is not a punishment field; it is a grouping field.

3. Transition

   Move the status last. Doing it in this order means the ticket is never visible in a new column with the wrong face on it, not even for a second.

Six actors. Each has a role to play on the same infinite loop.

Product Owner

Tech Lead

Developer

Reviewer

QA Engineer

DevOps / Release

Names below are placeholders — swap in your own on the day. What matters is the role, the columns it owns, and the line it must not cross.

Role	Owns	Never
Product Owner Ana / Fernanda	The Backlog, Refinement, Release Verification and Done. Writes acceptance criteria, sets priority, decides what gets refined and what gets parked. The last signature before Done.	Never estimates on the team's behalf, never assigns a developer, and never closes a ticket they have not seen working on production.
Tech Lead Hector / Abdullah	Planning, Evaluation and Ready for Tech. Sets the Developer and Assignee fields at the To Do handover. Signs off production health after a release.	Never lets a ticket into To Do with an empty Developer field, and never uses the hotfix door on ordinary work.
Developer Hector / Abdullah / Afaq / Adnan / Nadeem / Hamid / Sajaad	To Do and In Progress. Writes the code and the tests, keeps the pipeline green, opens the PR, addresses review, merges, and hands over to QA with notes.	Never moves their own ticket past Ready for QA. Never transitions to Ready for QA without reassigning to QA in the same breath.
Reviewer Hector / Abdullah / Afaq / Adnan / Nadeem / Hamid / Sajaad	A peer engineer. Owns the pull request, not a Jira column. Approves or requests changes, and is the second pair of eyes on anything touching auth, money or migrations.	Never merges someone else's PR for them, and never approves a PR whose checks are red.
QA Engineer Pablo	Ready for QA and In QA. The only actor who decides pass or reject. Verifies every acceptance criterion, hunts the edges, and attaches the evidence either way.	Never fixes the code, never re-estimates, never passes something on a hunch, and never quietly opens a Bug instead of rejecting.
DevOps / Release Hector / Abdullah / Afaq / Adnan	Ready for Prod Release and Cloud (Pre-Production). Batches the release train, cuts the tags, runs the production pipeline, owns the rollback decision.	Never decides whether a feature is correct — that is QA's call, then the requester's. Never moves on a partially-green run.

Thirteen stations, and who hands off to whom

Each station is held by exactly one actor — the person whose name belongs in the Assignee field while the ticket sits there. Read the last column first: that is where hand-offs break.

What the Product Owner actually does at 01 and 02

Two of the thirteen stations belong to the PO at the start, and they are the two whose output everybody else is then stuck with. Planning sequences what Refinement named. Evaluation prices what Refinement scoped. QA passes or fails the criteria Refinement numbered. Station 12 hands the ticket back to whoever Backlog recorded as the requester. None of those actors can repair a bad ticket — they can only send it back, and sending it back costs the three moves. So the checks below are not administration; they are the cheapest place in the whole line to catch the thing.

01 Backlog — what gets decided here, and what must not

Triage is not "reading the new tickets". It is a short list of decisions that are cheap because nothing downstream has been committed to yet — no estimate, no sprint, nobody's week — and a shorter list that belongs to somebody else entirely. This is the last station where changing your mind costs nothing at all.

• Does this already exist? Search open JNET tickets, then the Ideas Backlog. If it does, link the two and say which is the survivor — a duplicate that is silently closed reads as "ignored" to the person who filed it, and they will file it a third time.
• Is it one thing? One user, one problem, one outcome. A ticket carrying two problems cannot be half-rejected at station 08, so QA either fails work that was fine or passes work that was not.
• What type is it, decided rather than defaulted? Story — a user-visible change. Bug — something that worked and stopped. Task — necessary work with no user-visible outcome (a migration, a credential rotation). Epic — a container that is never worked directly. The type is what tells the room whether an estimate is even meaningful.
• Where does it sit in the order? Priority is a sequence, not a temperature. If two tickets are both the highest, Planning is the one that has to break the tie, and it will break it on something other than product value.
• Who asked? Name them in the description. Station 12 reassigns the ticket to the requester, so "someone raised it in Slack" produces a ticket on production that nobody is entitled to close.
• And if it is not next: park it out loud. A comment saying not this quarter, because X is a decision. Silence is also a decision, but the requester has to guess which one, and they usually guess wrong in the direction of asking again.

02 Refinement — until a stranger could build it

Refinement is finished when someone who was not in the conversation could pick the ticket up and start. Not when the PO has finished writing — those are different moments, and the gap between them is where sprints go. The Definition of Ready below is the gate; this is the work that gets you through it.

• Number the acceptance criteria, and make each one somebody else's to judge. The test is not "is it true" but "can Pablo mark this pass or fail without asking me what I meant". See the table below.
• Name every affected portal and every affected service, by repository. organizer-portal and documents-manager-api, not "the invoices screen". This is the field Planning reads to sequence against dependencies and Evaluation reads to price the work — a missing repository is a missing estimate.
• Name what is not affected, when it is close enough to be assumed. "udm-portal unchanged" saves an argument in Evaluation and a regression sweep in QA.
• Get the technical note in from someone who could build it. That is the Tech Lead's line on this station and it is a hand-off inside the station, not after it. A ticket whose only technical content is the PO's own guess is a ticket that gets re-refined during the sprint.
• Attach the designs, or describe the UI in words. On the ticket. A mock-up living in a Slack thread is not on the ticket, and the developer at station 05 will not find it.
• Split anything larger than one sprint, here. If it genuinely will not split, it is an Epic — and the first slice still has to come out before anything moves to Planning.
• Close every question that blocks a start. Station 05 is where questions are still free, but only the answerable ones. A blocking question sitting in a comment is not a refined ticket, it is a parked ticket with extra steps.

The wording is most of the job. These are the same four criteria as the worked example above, written both ways:

The left column is not lazier than the right — it is the same intention with the judgement left in the PO's head. Every one of those rows becomes a conversation during QA, on the day the sprint is trying to end.

A squad is the smallest team that can finish a ticket

Everything so far has been about one ticket and the people holding it. Here is how those people are actually grouped: five seats, and the rule that a squad with an empty seat has to borrow one. Borrowing is where hand-offs start to slip, which is why the shape is deliberately this small.

Either engineering seat can be filled by a full-stack engineer, and one person can hold two seats — but the seat still exists, and somebody has to answer for it.

Three squads, and the seat they share

The platform and QA seats are the ones held in common — Hector across all three squads, Pablo across two. The product seats are not shared, and that asymmetry is on purpose: pipelines and test standards are worth holding in common, product decisions are not.

Capacity is a ceiling, and the sprint in flight is closed

Sprints run one week. The cap is per person, not per squad, so a squad's ceiling is only real if every seat in it is actually free that week — and the platform seat never is, because it is the same person in all three squads.

An estimate that pushes a person past their cap is not a scheduling problem to solve later — it is the signal to split the ticket, at Evaluation, before it reaches To Do.

Four buckets, and only one of them is closed

Recommended rituals: a week shaped like the workflow

Sprints run one week, so the cadence below is the sprint. Each ritual exists to move a ticket across a specific hand-off, and it belongs to exactly one actor — the same rule as the Assignee field, applied to the calendar. If a meeting on your week does not move a ticket between two stations, it is not on this list, and that is deliberate.

What has to be true before each transition is legal

If you cannot tick every box in the row, the transition is premature. Say so out loud rather than moving the card and hoping.

Definition of Ready, Definition of Done

Definition of Ready — leaving Refinement

• A user and a problem, not a solution shopping list
• Acceptance criteria written as verifiable statements, numbered
• Every affected portal named (organizer-portal, …)
• Every affected service named (documents-manager-api, …)
• A technical note from someone who could build it
• Designs or a described UI, attached to the ticket
• Fits inside one sprint, or it has been split
• No open question blocking a start

# What that looks like on JNET-2801, the ticket used later in this workshop
AC 1  Select multiple patents from the results table
AC 2  A single Download selected action
AC 3  Works for at least 50 patents in one request
AC 4  Filename carries the org code and the date

Definition of Done — leaving Release Verification

• Every acceptance criterion ticked, by the requester, on production
• QA evidence attached — screenshots, request ids, log links
• Merged to main in every repository it touched
• Version tag cut and the changelog entry written
• Production pipeline green on the cloud stage
• Production healthy — alarms quiet, no new dead letters
• Any follow-up raised as its own ticket, linked, not as a comment
• Assignee is the requester, not the developer

Seven phases. The board only has columns for four of them.

The thirteen stations are a board. The life cycle underneath them is the older, duller list every team has seen: plan, code, build, test, release, operate, monitor. They are not the same thing, and the mismatch is where work goes missing.

Read the third row again. Build has no column, and neither does code review — both live entirely on the pull request. That is deliberate: a column implies someone is holding the ticket, and during CI nobody is. It also means the board cannot tell you the build is broken, so the pipeline has to.

The developer's first move is not code. It is one line.

The station is In Progress, the Assignee is you, and the Developer field has your name on it for good. Before a branch exists, this is the line that opens the ticket — and it deliberately cannot change a single file until you have read what it proposes back.

/plan /jnet-dev /jnet-portal https://cargonaut-team.atlassian.net/browse/JNET-2787

# /plan        → plan mode: it may read everything and change nothing
# /jnet-dev    → the backend skill: Handler → Middleware → Factory/DI →
#                Service → Repository → DB, pytest, Alembic, the shared bus
# /jnet-portal → the portal skill: Vue 3, PrimeVue, Nx, per-portal tags
# the URL      → the ticket, and where the branch name comes from

Both skills are named on purpose. You do not yet know whether the ticket is backend-only — the plan decides that, not you. On JNET-2787 it turns out to be backend-only, so the portal half correctly finds nothing to do; on a full-stack ticket both halves light up.

What actually happens, in order

Every step up to the gate is reading. The first thing that changes a file happens at 10, on the far side of an approval you have to give out loud.

Branch names carry the ticket, so the tooling can too

One convention, three parts: ticket reference, category, short description. The reference comes first so that a branch sorts, autocompletes and greps by ticket — and so the id is the first thing anyone reads. It is not decoration: it is what lets a pipeline, a PR template and a standup dashboard find each other without anyone copying an id by hand.

# reference - category - description
JNET-2801-feature-bulk-patent-download
JNET-2844-hotfix-organizer-500
JNET-2851-fix-presigned-url-ttl

# the reference is the contract: it links branch → PR → ticket → release note

What "green" means, per repository

A red pipeline is not a status. It is a developer with unfinished work. Nothing in this workflow moves on a red build — the ticket stays exactly where it is, In Progress, until every check passes.

# Nx monorepo · Vue 3 · PrimeVue · Vite · yarn
yarn lint                          ✓  ESLint, zero errors
yarn type-check                    ✓  tsc compiles
yarn test                          ✓  Vitest, coverage held
nx build --configuration=production ✓
security scan                      ✓  no new advisories
bundle analysis                    ✓  inside budget

# Per-portal release tags — each portal ships on its own clock.
# Never tag the whole repo against one version.
organizer-v1.31.0   admin-vX   entrywriter-vX   udm-vX   workspace-vX

# Python 3.11 · Lambda Powertools · SQLAlchemy 2 · Serverless
pytest --cov=src                   ✓  unit + integration
lint + type checks                 ✓
alembic revision applies cleanly   ✓
serverless package builds          ✓
submodules resolve                 ✓  python-lambda-common
deploy job green on target stage   ✓

# Stages
dev    → AWS 225725557140 → *.api.junctionnet.dev
cloud  → AWS 894898254520 → *.api.junctionnet.com
shared bus: Platform-Apps-events-{ENV}

The gate is the Required label, not GitHub's summary line

GitHub will tell you the run is unfinished on a pull request that is entirely mergeable. Read the rows, not the headline — this is a real JNET PR, seconds before it merged.

⏳ "Some checks haven't completed yet"
   1 cancelled · 3 skipped · 10 successful · 1 pending review

✓ ci / Display Configuration Info                             3s
✓ ci / Infra Apply (Dev) / Terragrunt apply (dev)
✓ ci / Pipeline Summary + Ticket Comment
✓ ci / PR Notification                                        6s
✓ ci / Run E2E Tests (Ticket Dev)         [Required]
✓ ci / Run Unit Tests                     [Required]  52s
✓ ci / Verify (Ticket Dev)                [Required]   5s
✓ WIP — Ready for review                                      1s
⋯ 2 successful, 1 cancelled, 3 skipped — collapsed below the fold

# MERGEABLE. All three Required checks successful. Nothing cancelled,
# skipped or merely requested carries a ruleset requirement.

The automated first pass, in summary

Claude Code Review reads a pull request with a fleet of agents, each hunting a different class of problem, and a verification step then checks each candidate against what the code actually does before anything is posted. Findings arrive as inline comments on the lines they concern, ranked by severity, with a tally in the review body and a full table behind the Claude Code Review check run's Details link.

It is deliberately incapable of being a gate. The check run always completes with a neutral conclusion, so it can neither block a merge nor authorise one, and nothing in the workflow above changes: station 06 still ends when a human reviewer approves and the developer merges. Treat it as a first pass that arrives before the human one, and whose value is the round trip it saves the author — not as a reviewer.

• 🔴 Important — a bug to fix before merging · 🟡 Nit — worth fixing, not blocking · 🟣 Pre-existing — real, but this PR did not introduce it
• When it runs is set per repository: once when the PR opens, on every push, or manual only. Every-push costs the most, and reviews average $15–25 each, billed as usage credits rather than against the plan.
• Replying to a finding does nothing. Fix the code and push. On a push-subscribed PR the next run resolves the thread itself.
• Tuning lives in the repo. A newly introduced CLAUDE.md violation comes back as a nit — so the files we already keep for Claude Code are doing double duty. A REVIEW.md at the repo root is injected into every review agent at highest priority: use it to redefine what Important means here, cap nit volume, or skip generated paths.

Post it as a top-level PR comment with the command at the start of the comment — an inline comment on a diff line will not trigger anything. You need owner, member or collaborator access, and the PR has to be open; unlike the automatic triggers, a manual request runs on a draft. If a review is already in flight the request queues behind it. And when a run errors or times out, GitHub's Re-run button does not restart it — comment again or push.

Before any of that, the same review runs locally: /code-review in a Claude Code session reads your branch's commits ahead of upstream plus whatever is still uncommitted, so it can be the last thing you do before opening the PR rather than the first thing that happens after. --fix applies what it finds, --comment posts the findings to the PR. It reads CLAUDE.md like any session, but not REVIEW.md.

Between "merged" and "on production" there is a branch strategy

Stations 09 and 10 hide an entire discipline. QA passing a ticket does not put it on production — a release does, and a release is a branch, a tag and a decision about what travels together.

# the whole flow, and the only four moves in it
main ──┬──────────────────────────────┬──► main
       │                              │
       ├─ JNET-2801-feature-… ────────┘        1. ticket branch off main, merged back
       │
       └─ release/v1.32.0 ──┬──► tag v1.32.0 ──► production
                            │                   2. release branch cut from main
                            └─ fix branch ─┘    3. patches land on the release branch
                                                4. release merges back into main

Versions are semantic, and the tag is what deploys

MAJOR.MINOR.PATCH: major for a breaking change, minor for a backward-compatible feature, patch for a fix. The tag — not a branch, not a green build — is what the production pipeline runs from, which is why the tag is cut at station 09 and not before.

Steps 1–6: the train leaves, and the requester closes it

1. Fixed, green, handed back → Ready for QA. The zip moves into a Step Function; the endpoint returns 202 with a job id and the client polls. New PRs on both repos, all checks green, both merged, dev redeployed. Karim's handover says the one thing that matters: "re-test the 62-file case and the original 5-file case — the happy path changed, it is asynchronous now."
2. Both cases pass → Ready for Prod Release. Pablo re-tests the 62-file case and the 5-file regression, attaches the evidence, ticks all four criteria, reassigns to Adnan and transitions. QA decides whether it is correct, never whether it ships.
3. The train leaves → Cloud (Pre-Production). Adnan batches JNET-2801 with four other passed tickets, decides the version bump, writes the changelog entry, cuts the tags, and the production pipeline runs against the cloud stage.
4. Every job green — only then does it move → Ready for Tech. A partially-green production run is a rollback decision, not a transition. This is where the pipeline stops being a developer concern and becomes a release gate.
5. Technical sign-off, then back to the person who asked → Release Verification. Hector watches production for thirty minutes, not thirty seconds: alarms quiet, 5xx flat against the previous hour, POST /patents/bulk-download returning 202s, nothing new in the dead-letter queue. Then he reassigns to Fer.
6. Verified on production, then Done. Fer runs all four criteria against a real Hutchison Ports org with 71 patents — precisely the case Karim flagged as untestable in his very first handover comment. All four pass. Only the requester closes.

# Step 22 — the release train
tag  organizer-v1.31.0
tag  documents-manager-api-v2.14.0

AWS 894898254520 · stage cloud
  alembic migration       ✓
  serverless deploy       ✓
  s3 sync + CF invalidate ✓
  smoke suite             ✓

Ten ways this workflow gets broken, and the fix for each

Read these aloud in the room. Ask, honestly, which ones happened last sprint.

Facilitator run sheet — 09:00 to 12:45

Have the board open on a second screen the whole time. Every abstract point gets pointed at a real ticket within thirty seconds, or it gets cut.

The timings follow the six actor cards, because that is where the thirteen stations are now taught — an actor, then the stations they hold, then the command they run. The stations table is page-only reference and never goes on the projector, so there is no block for it below. Two roles carry more than one body: the PO has four cards and the Reviewer three, which is where the minutes go.