Foundations: Product, Code and the Working Environment

Jira, Work Tracking and the Studio Operating System

How Jira, pull requests and commits together hold a small studio's agreements, owners, completion criteria and evidence, and how to read statuses,…

Chapter 6Foundations: Product, Code and the Working Environment

A client writes: "We need a portal where customers can see the status of their order." The request describes a desired outcome, but it does not give anyone a shared understanding of the scope, the owner, the acceptance criteria or how the result will be checked. If the work is handed out only by word of mouth, within a few days people may remember different agreements. The team has to find out whose orders the portal should show, who will accept the work, and how access to the data will be verified.

Jira can hold those agreements, the next actions and the evidence. Its fields and workflows do not define the process by themselves, though: the team has to agree on responsibilities, acceptance criteria and the rules for calling something finished.

Earlier material covered the map of digital product development, the anatomy of a code project, the local environment, change history in Git and GitHub's role in reviewing code. This unit ties the client's agreed intent, planning, execution, verification and support into a controlled cycle in Jira and in a small studio. How to decide what exactly should be agreed in the first place is the subject of product discovery and client diagnosis.

Jira stores working context; it does not define the product

Keep the product, the direction of change, time-bound work and the Jira space separate:

  • Product: creates lasting value for users, for example a customer portal.
  • Initiative: sets a broader direction of change and may bring together the work of several teams, products or business projects; it does not need its own Jira type.
  • Business project: work limited in time and resources with a defined outcome, for example launching the first version of the portal by the end of the quarter.
  • Jira space: a container for work items, settings and views; it may correspond to a product, a team or some other scope, but it does not define the product model.

In February 2026, Atlassian announced that Jira projects were being renamed Jira spaces. The update is rolled out automatically, so both names may appear in interfaces and documentation during the transition. It is a change of terminology and icon: boards, workflows and data stay the same. Atlassian Projects is a separate, cross-space level for initiatives: it can bring together work items from different spaces and show their wider context. In this unit, "Jira space" means a container for work, and "business project" means time-bound work; the two concepts are related but not necessarily hierarchical (Atlassian on Jira Spaces, 21 February 2026, Atlassian Projects in Jira, 22 July 2026).

In our teaching model, the initiative "Make orders transparent to customers" covers launching the portal by 30 June as well as separate work for the support team. The product will live longer than this business project. This is an example of how the concepts relate, not a corporate template or a set of Jira types.

The working structure in Jira

Record or concept Question it answers Example for the portal
Work item Which record is the team tracking? A task, bug, request or another configured type
Epic Which large piece of work has value of its own? A customer sees the list and status of their own orders
Task or story What is the verifiable unit of work? Show the list only to an authorised customer
Subtask Which separate step does the parent task need? Check access on the list request
Feature Which concrete capability does the user get? Filter orders by date; in Jira this might be a requirement or a configured type

The "epic, feature, task" relationship describes intent and delivery, not a mandatory Jira hierarchy. A team can record it through parent items, links or the text of the requirements.

In Jira Cloud, Atlassian increasingly uses the term work item; older documentation still says issue. Either way it is a record of a certain type: a task, a bug or some other configured kind of work.

The epic, task and subtask levels and any additional types depend on the plan and the configuration. "Feature" means a capability of the product and is not necessarily a Jira type. Changing the hierarchy can affect existing parent and child items (Atlassian: what is a work item, configuring the hierarchy).

An epic or a story helps keep the link to the outcome, but over-decomposition has a cost too: every record has to be clarified, linked and maintained. Break work down just far enough that each piece can be done, reviewed or accepted independently; do not create subtasks simply to make the board look fuller.

The backlog, working states and evidence of completion

A backlog is the visible stock of potential work that has not yet been taken on. It does not have to contain every idea the company has ever had: filters and board settings decide what is visible. In Scrum, items are ordered and selected for a sprint, a short planning cycle; how this is displayed depends on the Jira configuration (Atlassian: using the Scrum backlog).

A team might define the following states. This is an example of a team agreement, not a ready-made process to copy:

State When an item moves here When it can move on
Backlog There is an opportunity or a request, but the team is not ready to take it on The goal, rough value and the next clarification step are known
Ready The task is understood, has an owner and verifiable criteria Someone has capacity, and critical dependencies are available
In progress Someone is actually working on the task The result has been handed over for review, or a concrete blocker has been recorded
Blocked A known factor prevents progress or makes continuing unsafe It is recorded what removed the block, who confirmed it and what comes next
Review The result has been handed over for review The review is complete, or a rejection is recorded with its reason
Done The outcome is achieved, and the evidence and any required handover are in place Final state by agreement; any new work is recorded separately

A status shows where an item sits in the configured workflow, but it does not prove that the result was written, checked, released or accepted. A separate Resolution field records the outcome, for example done, rejected or duplicate; in a simplified workflow the transition rules may differ (Atlassian: statuses, priorities and resolutions, simplified workflow).

Agree on what Done means. For a code change, the criteria might include the agreed scope, the required checks and reviews, updated documentation, and a named owner for the release or handover. Add client acceptance if it is part of the agreement. Not every task needs a release; if the code is ready but the release is not, keep a separate "ready for release" state.

A board can group several statuses into one column, and a filter can hide part of the work. That is only a display: the colour of a card does not prove anything is finished. Open the record and compare it with the criteria and the evidence (Atlassian: configuring columns).

Who does the work, who decides and who is accountable for the result

The assignee field shows who the record has been given to, but not necessarily who decides on priority or budget, who accepts the result from the client, or who authorises a risky change. Reporter usually identifies who created or logged the record; due date and priority are separate fields (Atlassian: Jira list view).

Role Responsibility
Action owner Moves a specific task forward and keeps the facts about its state up to date
Product or outcome owner Defines the value, the acceptable scope and fit with the goal
Decision-maker Approves priority and trade-offs between deadline, scope, cost or risk
Reviewer Checks code, behaviour, security or criteria
Operational owner Takes care of release, handover, support, access rights and tracking the consequences

In a team of two, roles can be combined. A critical risk, a change to the contracted scope and access to sensitive data must be approved by an authorised person. The tracker records the decision; it does not grant the authority.

Priority, due date, dependency and blocker are different signals

Priority answers: what matters more right now, relative to everything else? Due date: by when is the result needed, and why? Dependency: what has to be finished or agreed before the next step? Blocker: what is actually stopping progress right now, and who can remove it?

Jira can have configured priorities and dates, but their meaning is not universal. "High" without a reason, an owner and a consequence does not create a queue of decisions. A date without an agreed trade-off does not make the work go faster. Links such as "blocks" or "is blocked by" can be configured differently (Atlassian: linking work items).

For a real blocker, record the cause, the person or event that continuing depends on, when it will next be checked, and the alternatives. Turn "waiting for the client" into a note with the date of the request and the specific answer that is needed. If no answer arrives by the agreed time, the responsible person may renegotiate the deadline or temporarily remove that part from the release. Do not leave a blocker as a silent card that just gets older.

Flow of work, unfinished work and review queues

Work in progress (WIP) is the set of tasks that have been started but not yet finished. Ten cards in In progress do not mean ten people working in parallel: some of them may be waiting for a decision, a reviewer or access.

A WIP limit is a team-agreed upper bound on unfinished work at a given stage or for a given type of work. When the limit is reached, look for the bottleneck or help finish what has been started; raising the limit just because a card is blocked hides the cause. Decide in advance whether incidents, urgent requests or external dependencies need a separate stream or an exception to the limit, and keep blocked tasks visible in the WIP count. This is a diagnostic agreement, not a productivity formula; DORA (DevOps Research and Assessment) recommends setting it according to real capacity and where waiting happens (DORA: WIP limits).

Small batches of change speed up feedback and make checking and fixing easier, but they do not guarantee an increase in speed (DORA: working in small batches).

It is useful to see on the board how old each task is, the review queue and the dependencies. The number of closed records does not measure personal productivity: DORA recommends assessing the flow of changes and the reliability of an individual system, not ranking people or transferring results from large samples onto a small studio (DORA metrics).

Every record started in parallel competes for attention. After switching, a person has to reconstruct what they already checked, which decision is pending and where to pick up; so a large number of In progress items can increase waiting time even if each participant looks busy on their own. Check where a task is actually stuck: in active work, in the review queue, waiting for a client's reply, or waiting for the founder's decision. For each queue, name the next action, the owner and when it will be looked at again.

One author on Atlassian Community described using two boards for every Jira record: one for the main story or task, and another for its linked subtasks. He explained the choice by the fact that a single story could have 20–30 subtasks. This is an example of one team's local adaptation, not evidence that every project needs two boards. For a small studio, that many views can create needless navigation; start with the simplest view in which the work and the waiting are visible, and change it when the real structure calls for it (Atlassian Community: Implementing Jira in Small Business).

As a temporary hypothesis rather than a norm, a team of two might try no more than two active planned tasks per person and one shared task in review, and after a few weeks see whether the queues have shrunk. Incidents, urgent support and external dependencies need exceptions or a separate stream that are visible in advance. If the rule harms service or delays safe parallel work, revisit it; the limit exists to diagnose flow, not to judge people.

How to connect Jira with GitHub

Jira stores the reason for the work, the acceptance criteria, the owners and the decisions. A pull request (PR) shows the proposed changes, the discussion and the automated checks; a commit identifies the exact version of the code. Reviews and checks are covered in more detail in GitHub as a development control plane.

Record What it shows Example for the portal
Jira work item Why the change is needed, the agreed outcome, criteria, owners and decisions Show the list only to an authorised customer
Pull request (PR) The proposed file differences, a description of intent, the discussion and checks Add the order list page
Commit The exact recorded set of changes that a check or a release can refer to The code revision that was actually reviewed and checked

These records are not levels of one product tree. Jira provides the working context and the criteria; a PR is a candidate change plus a review decision; a commit is the exact identifier of the code. How GitHub displays checks and reviews, and what a merge means, is covered in detail in GitHub as a development control plane.

One Jira task can lead to several PRs, for example one for data changes and one for the interface. One PR can relate to several connected tasks, but bundling independent changes together makes them harder to review, check and roll back. A link carries context; it does not replace the acceptance criteria.

Integrating Jira with GitHub requires setup and permissions. A Jira key in a branch, commit or PR name helps link them to the work item; mere similarity of names does not achieve that (Atlassian: GitHub with Jira, viewing development information).

A merged PR will not necessarily move a Jira item to Done: that requires a configured trigger or automation; otherwise the status is updated according to the team's procedure (Atlassian: workflow triggers). The GitHub phrase Closes #10 closes a GitHub issue after a merge into the default branch, but it does not close a Jira work item (GitHub: linking a PR to an issue).

The acceptance criteria and the acceptance decision stay in Jira; the mechanics of review, checks and merging are explained in GitHub as a development control plane.

What to do when the scope changes mid-work

While the work is under way, the team may discover a new need. An AI agent can summarise it, but it does not approve a change of scope or assess the risk in place of the responsible person. Do not add a new requirement to the original task as if it had always been part of the agreement:

  1. Update the current task when the clarification changes how the same outcome is achieved, or when the client has explicitly agreed to the change of scope. Record what changed, who approved it and how it affects the deadline or cost.
  2. Create a linked follow-up task when the finding is separate from the original outcome and can be done later. Set up the link, and the dependency if there is one, and keep the original criteria.
  3. Stop the unsafe step and hand the decision to a person when continuing could damage data, expose access to the wrong audience or hide a critical defect. Record the risk, who owns the decision and the condition for resuming.

The shared record can be another official tracker, but the decision must not live only in a private chat. When handing over work, state its status, the latest evidence, the next owner, the unknown facts and the risk. Finished code may still be waiting for acceptance, release or handover to support.

How a small studio organises its work

A minimal studio cycle might look like this:

qualify the request → diagnose → agree scope and criteria → do the work → verify and accept → release or hand over → support → lessons for the next job.

Qualification matches the request against the studio's skills, timelines and goals; diagnosis uncovers what is unknown. The agreement sets the scope, verification checks fit, and acceptance records who confirmed the result. After a release you need a support owner, a channel for reporting problems and agreed limits on response. A review of the work looks for systemic improvements, not someone to blame.

In The E-Myth Revisited, Michael Gerber distinguishes the entrepreneurial role (vision and opportunity), the managerial role (systems) and the technical role (doing the work). This is a useful lens for a founder who moves between selling, planning and development, but it is not a mandatory job structure. The practical point is not to let agreements, priorities and follow-up exist only in the founder's head, while still leaving specialists room for their own judgement. The EMyth explanation of the roles was written by Tricia Huebner; it is her account of Gerber, not his own text (Huebner, "The Three Business Personalities").

David Maister's openly available chapter "The Anatomy of a Consulting Firm" looks at professional services in terms of the share of repeatable routine, uncertain analysis, client contact and required experience. It is the author's practical typology, adapted from his books, not the full text of those books. A standard packaged change and a one-off integration carry different levels of uncertainty, so they may need different diagnosis, different involvement of experienced people, different frequency of client contact and a different style of review. Match tasks to people's current skills, but also plan for controlled growth: a less experienced colleague can take on part of a more complex job with a mentor who teaches the craft and checks the result. That way, building skills becomes part of how work is assigned rather than a promise to "learn it someday" (Maister: "The Anatomy of a Consulting Firm"). The publisher describes Managing the Professional Service Firm in terms of balancing client service, team development and financial health; here we used that description and the available excerpt, not the full book (Simon & Schuster: Maister's book).

Peopleware, by Tom DeMarco and Timothy Lister, reminds us that software development needs time for focused intellectual work. The publisher's excerpt of the third edition contains a full chapter on leadership as service to the team and the contents of the other chapters, but not the whole book, so we draw no quantitative rules from it. The practical question is: does the operating system remove obstacles, or does it only collect reports? Planning should also account for the cost of interruptions: after an unplanned switch of attention, a person has to rebuild their context, and frequent notifications can break up time for focused work. For example, a team might gather routine check-ins into fixed time slots and agree separately on what counts as a real incident. This is a way to protect working time, not a claim that quiet or privacy affects everyone in the same way. The InformIT piece describes observed associations and managerial arguments, not causal proof of a universal policy (Peopleware, Pearson excerpt with the book's fifteenth chapter, Glass, "People," InformIT).

DORA analyses team practices and software delivery outcomes. Its open 2018 report and its current guidance are not a personal-productivity calculator. They do not imply that one person closing many cards means better work, or that a small studio can be compared directly with percentages from a large sample. Look at the flow of changes and the reliability of the system for a specific product rather than ranking different people or teams (DORA 2018 report, DORA metrics). Accelerate was not read in full here; we used the report and the public guidance and do not pretend to have read the book (publisher's page).

AI can summarise a brief, find a related task, and propose acceptance criteria, a draft plan or questions that are still missing. A person checks every claim against its source and decides whether to take the job, what is in the contract, which deadlines and risks are acceptable, who may be given access, whether the result meets expectations, and whether it is safe to release. AI-generated text is a proposal to be checked, not the client's permission and not evidence that the work is done.

Examples: criteria, queues and scope changes

Example 1: A customer portal, from brief to accepted change

Names, dates, tasks and events are invented. The client has agreed the first version of the portal: an authenticated user sees only their own orders, their statuses and when each was last updated. Filters, export and editing orders are not part of this delivery.

Situation. The brief arrived by email. The team does not yet know whether there is an authentication method in place, where the data will come from, or who on the client's side will accept the version. The phrase "show the status" cannot be read as permission to show orders to any user.

Action. The product owner establishes that the portal uses existing authentication, that the query returns only the current customer's orders, and that the list shows the order number, date and a text status. The client's contact person will accept the behaviour on the test environment. In the Jira space, the team creates the epic "A customer sees their own orders," with the goal, the brief, the unknown dependencies and the delivery criteria.

Two tasks are created under the epic:

  1. "Fetch only the authenticated customer's orders." Criteria: a request without a session is rejected; customer A sees no records belonging to customer B; an automated check covers both cases. This is a higher-risk access boundary, so a separate reviewer is assigned.
  2. "Show the list and status of orders." Criteria: the page shows the number, date and status; an empty list produces a clear message; a service error does not show someone else's data or stale data.

Once the dependency on the service is confirmed, both tasks move from Ready to In progress. The first PR adds the access check and automated tests; its title contains the Jira key, and its description records the decision and how it was verified. After the security review and the mandatory automated checks, the PR is merged. Because no trigger is configured, the owner records the completion of the first task in Jira manually.

The second PR adds the list page, references the task and the epic, and adds no filters or editing. The reviewer checks the change against the criteria on the test environment; the client's contact person confirms the agreed behaviour. The owner records the acceptance, and the team checks that the accepted version contains exactly the commits that were reviewed. Only then is the task moved to Done.

Result. The Jira records hold the criteria and the acceptance decisions, while the PRs and commits hold the technical trail of the changes. The epic's name alone does not prove that both tasks were accepted.

Why this split helps. Access to data has its own security condition, which can be checked earlier than the interface. Jira shows the criteria and the owners, and the PR links the proposed changes to what the reviewer and the checks verified. Client acceptance is recorded as a separate fact; it does not follow automatically from the merge.

These records also make it possible to hand the work over if one person is unavailable: the next owner sees the original brief, the agreed criteria, the dependencies and the exact version that was checked. Without them, the team might wrongly conclude that the merged PR by itself confirms client acceptance, or that export is already part of the epic.

Alternative and limits. For a prototype without real data, the two tasks could be combined, as long as access is still checked separately. If several environments, payment data or order editing are added, a separate diagnosis is needed. A single Jira task can be fine for a very small change, but here it would have hidden the risky access check inside the interface work. An automatic transition after a PR is merged requires separate configuration and does not replace acceptance.

Example 2: Ten active tasks in a two-person studio

The people, tasks and events are invented. The studio consists of Olena, the founder, and Marko, an engineer. The board shows ten records in In progress: five are waiting for Olena's decision (one of them has not even been started), three are waiting for Marko's review, one is blocked by the client's access, and Marko is actively working on one.

Situation. Every day the team opens new tasks so that nobody looks idle. Older changes keep switching between branches; quick "take a look when you have time" messages have built up into a review queue with no owner and no review time. The client's replies arrive through different channels, so it is unclear which decisions are urgent.

Action. The team goes through the records and sorts out the waiting:

  • four tasks are waiting for a decision; each is given a decision owner and an agreed waiting state;
  • the fifth has not been started, so it goes back to Ready;
  • the three PRs are given reviewers and a review time;
  • for the blocked task, the team records the cause, the client contact and the date of the next request.

For the following week, the team takes on no new planned work until it has reviewed those PRs and finished the active task. Urgent support runs as a separate, visible stream.

Over the next few days, Marko reviews the oldest PR instead of starting a new task; Olena makes one product decision and hands another to a person who has the necessary context. At the next review meeting they check whether the queue has shrunk, where waiting still occurs, and whether support work changed the plan. They do not compare people by the number of cards closed.

Result. Every queue now shows the next action, the owner and when it will be checked. A few days of observation explain where the waiting comes from, but they do not prove any gain in productivity.

At the next review, the team checks whether the queue really did shrink and where waiting now builds up. If the oldest PR is still waiting, they find out whether it needs more context, a different reviewer or a change of plan; if the client's access is still blocked, they set a date for the next contact and an owner. In this way the team looks for the cause of the delay instead of rewarding the creation of new cards.

Why. A temporary pause on new starts makes it possible to finish what was started and see where the bottleneck forms.

The point of the review is not to insist that everyone has the same workload, but to tell active work apart from queues. If Marko is reviewing code for which he lacks domain context, the PR can go to another reviewer, or Olena can be asked to supply the decision; simply adding more In progress cards will not remove that need.

Alternative and limits. If the team has a support rota, it must not be paused for the sake of planned PRs: agree separate capacity and rules for critical cases. If a reviewer is unavailable, assign a backup or change the plan. Two people can work in parallel on independent tasks when context and review are available. This limit should not be copied into another team without observing how that team works.

Example 3: An agent finds a new requirement just before completion

The participants and the request are invented. While working on the first version of the portal, an AI agent finds a sentence from the client in the correspondence: "It would be nice to download a table of orders." Export is not part of the agreed criteria.

Situation. The agent proposes adding a CSV (comma-separated values) export to the same PR, because it "looks similar to the order list." The file would contain personal data, and the client has not yet decided who the audience is or which fields are allowed. The agent's suggestion is neither the client's permission nor a risk assessment.

Action. The product owner moves the export into a linked task that does not block the agreed release. There, the team has to clarify the client's scenario, the file's fields, access roles, auditing and acceptance. Until that is confirmed, the PR covers only the list of the customer's own orders, and no export is released.

If the client decides to include export in the first release, an authorised person will add the criteria and agree the deadline and cost. If the query returns another customer's orders, stop that path until it is fixed; safe, independent work can continue.

Result. The first release keeps to the agreed boundaries, and the new request has its own owner and is waiting for diagnosis. Decisions about scope, risk and release are made by an authorised person.

Why. Renegotiation changes the contracted scope; a linked follow-up task preserves the original outcome when the new capability can be separated; stopping protects users when there is a risk of a data leak or data damage. In all three cases the decision is made by a person with the appropriate authority, not by the agent or the PR's author.

Limits. Do not create a separate record for every small detail: excessive decomposition adds noise. If a clarification fits entirely within the agreed outcome, it is enough to update the current criteria and record who agreed to the change. Stopping an unsafe path does not have to freeze all the work: safe, independent steps can continue after the responsible person has decided.

Summary

Jira is useful when its records hold the agreements, the owners and the conditions for completion. Priority, due date, dependency and blocker are different signals; a board helps you see where work is waiting and which decision is needed.

Together, Jira, PRs and commits hold the context, the technical trail and the acceptance decision. Automation can move records along, but it does not decide what risk or what result is acceptable.

Sources and further reading

Documentation and web pages were reviewed on 23 September 2026. Names and features of cloud products may change.

Jira and Atlassian

  • Jira product team, "Jira Spaces: A new name that matches how you work", 21 February 2026. Used for the renaming of Jira projects to spaces and for distinguishing the work container from the portfolio-level Atlassian Projects. This is a product announcement about rolling out a terminology update, not a recommendation about how to model an organisation.
  • Jira team, "Atlassian Projects, now in Jira", 22 July 2026. Re-checked 10 October 2026. The official announcement describes linking Jira work items to cross-space Atlassian Projects and using them for initiatives with goals, owners, deadlines and status; it does not mean that work items and spaces must follow a fixed universal hierarchy.
  • Atlassian Support: What is a work item?, Configure the work type hierarchy, Statuses, priorities, and resolutions, Simplified workflow, Scrum backlog, and Configure columns. Used for work items and configurable levels, the difference between status and resolution, the visible backlog, simplified transitions and how statuses map onto a board. This is documentation for specific Jira Cloud products; the example statuses in this unit are a teaching agreement, not a list of values that is the same for every team.
  • Atlassian Support: Link work items, Jira list view, GitHub integration, Development information for a work item, and Workflow triggers. Used for the kinds of links, the role of fields, and how development information depends on the integration, permissions and work keys. These pages describe configurable links and triggers; a particular space may have a different scheme or automation, and a PR link alone does not confirm acceptance.
  • Thomas B, "Implementing Jira in Small Business", Atlassian Community, 3 December 2018; the byline on the page is Thomas B. The author's example of two boards, one for stories/tasks and one for subtasks, including jobs with 20–30 subtasks; it shows a local solution, not a universal template.

GitHub and the flow of work

Professional services and teamwork

  • Tricia Huebner, "The Three Business Personalities: Entrepreneur, Manager & Technician", an applied explanation of Gerber's roles. This author's account, not wording from Gerber's book, is the source of the short description of the three roles in this unit.
  • David H. Maister, "The Anatomy of a Consulting Firm", a chapter on the types of work in a professional firm, the level of routine and uncertainty, experience and teaching the craft; the author notes that the text is adapted from his earlier books.
  • David H. Maister, Managing the Professional Service Firm, Free Press, 1997. The publisher's page and the available excerpt were used for bibliographic context on balancing client service, team development and financial health, not the full book.
  • Tom DeMarco, Timothy Lister, Peopleware: Productive Projects and Teams, 3rd edition (2013), Pearson excerpt containing the book's fifteenth chapter. The excerpt supports the question of leadership as service to the team; it gives no grounds for claiming a quantitative effect of any particular interruption policy, and the full book was not read here.
  • Robert L. Glass, "People," InformIT, a section from Facts and Fallacies of Software Engineering, 22 November 2002. Used as a managerial overview of work and interruptions, not as a controlled causal study.
  • Michael E. Gerber, The E-Myth Revisited: Why Most Small Businesses Don't Work and What to Do About It, 3rd edition, HarperBusiness, 1995. A bibliographic record; the example of roles in the text relies on Huebner's separate explanation of the model and does not present any quotation as coming from the book.