User guide
Design Reviews & Baselines for Jira adds to every Jira project a Reviews & configuration page, a Design reviews panel on issues and an administration page. The interface follows the language of your Jira profile (English or French) and its theme (light or dark).
1. Design reviews
Create a review
Project page > Design reviews > New review. Pick the type (SRR, PDR, CDR, QR, TRR, AR, ORR, document review or other), give a subject, a milestone and the dates: kick-off, RID deadline, board date. You become the chair unless you appoint someone else.
Before it opens, the review is in preparation:
- Documents: the review package (reference, title, issue, link to Confluence, a document system or a Jira issue key).
- Participants: chair, secretary, author (who owns the reviewed design), board members and reviewers.
- Settings: the review's exit criteria, and a “participants only” option that restricts RIDs to listed people.
Phases
| Phase | What happens |
|---|---|
| Preparation | Documents, participants and criteria are set. |
| Reviewing | The package is sealed: its SHA-256 fingerprint is computed and written to the audit log. Reviewers raise RIDs. |
| Responses | The author answers each RID. |
| Board | The chair or secretary records the board decision on each RID. |
| Closed | The minutes are frozen with their fingerprint, then signed. RIDs, decisions and criteria no longer move; only the decided actions can still be closed, with their evidence, and the signed minutes stay as they are. |
The chair, the secretary, the review creator and project admins move between phases (button at the top right). Going back is possible until the review is closed; going back to preparation is refused once a RID exists, because the reviewed package can no longer change.
Raise a RID
RIDs tab > New RID (or from an issue panel, see § 3). A RID carries the document and location (section, page, table), a class (Major: challenges the design, a requirement or safety, and blocks the review exit; Minor; Editorial), a title, the observation and the proposed correction, and optionally the target issue (the requirement or component concerned). A RID raised after the deadline is flagged “late”.
Reviewers edit their RID while it is open and the review is in reviewing phase; they can withdraw it with a reason until a decision is made.
Import RIDs: RIDs tab > Import CSV. The file comes from the Excel form sent to external reviewers (free template) or from your own template: usual English and French headers are recognised (document, location, class, title, observation, proposed correction, originator…). Check validates the whole file (documents, classes, lengths, target issues, duplicate rows) and creates nothing while any row has an error. The import then runs in batches of 20 with a progress bar; a row already present in the review is skipped, so an interrupted import can be restarted without duplicates. 500 rows at most per file.
Respond and decide
- Author response: position (agree, partly agree, disagree, clarification) and text.
- Board decision: accepted with action (description, owner, due date, and a Jira follow-up issue created in one click if you want), accepted, no action, rejected or transferred (to another milestone or body). A rationale is required except for “accepted, no action”. The board can reclassify the RID.
- Action closed: the owner or the board closes it with its evidence (reference, link); the RID becomes “Closed”.
Dashboard
Indicators (RIDs raised, major undecided, awaiting response or decision, open and overdue actions, late RIDs) are clickable and filter the list. The class × status matrix, breakdown by document and by originator, exit criteria status and dates complete the view. Export CSV produces the full RID list (separator by language, protection against formula injection).
Closure, minutes and signatures
Close the review asks for the conclusion:
- Passed: only if every active exit criterion is met;
- Passed with reservations: the only allowed gaps are actions still open;
- Not passed.
A rationale is required unless passed. The closure dialog also records attendance: untick absent members and the minutes show it. Exit criteria are frozen once the review reaches the board. At closure the minutes (participants, documents and issues, package fingerprint, RID table, criteria, decisions, actions, conclusion) are frozen and their SHA-256 fingerprint written to the audit log. The chair, secretary, author and board members sign them in the Minutes tab (simple electronic signature: Jira account, date and fingerprint, written to the log). Download PDF produces A4 minutes with the fingerprint in the footer. When the tab opens, the app recomputes the fingerprint of the stored minutes and warns you if it no longer matches.
2. Configuration management
Project page > Configuration. Configuration managers (appointed by a project admin, who is one by default) create and edit items, freeze baselines, convene change boards and implement changes. Every project user can browse, and can draft and submit a change request.
Configuration items
An item has an identifier unique in the project (e.g. EQ-ALIM-01), a name, a kind (hardware, software, document, interface, system), a revision, a parent item, a linked issue and its definition documents. Changing the revision by hand requires a reason; the normal path is an approved change (below). An obsolete item stays in the history.
Configuration status accounting
The Status accounting tab shows the item tree with, for each item: its revision, the last baseline that contains it (and whether it changed since), pending changes and active deviations. CSV and PDF exports.
Baselines
New baseline freezes the current state (functional, allocated, product or other) with the list of items, their revisions, their tree and the active deviations or waivers, under a SHA-256 fingerprint. Compare shows the differences between two baselines, or between a baseline and the current state: items added, removed, revisions changed.
Changes: ECRs, deviations, waivers
| Type | Use |
|---|---|
| ECR (engineering change request) | Changes the definition: each affected item moves from one revision to another. |
| Deviation | Departure authorised before manufacture, with its effectivity (serial numbers, lots, duration). |
| Waiver | Departure found after manufacture, accepted as is. |
Life cycle: draft > submitted > (board decision) approved, rejected or deferred > implemented > closed. Implement on an approved ECR is only possible once the meeting that approved it is closed; the app checks that every item is still at its starting revision, then moves the revisions and logs them with the ECR reference. An interrupted implementation can be restarted without doubling revisions.
Change control boards (CCB)
A board has a date, members (chair, secretary, members) and an agenda made of submitted requests. The chair or secretary records the board decision on each request (rationale required unless approved). Approving a class I change (one that affects contractual commitments) requires the reference of the customer's agreement, shown in the record. A decided request can no longer be removed from the agenda. Close the meeting freezes the decision record under a SHA-256 fingerprint; it downloads as PDF.
3. Issue panel
On every issue, open the Design reviews panel from the issue's View app actions menu (the first time; Jira then keeps it on the issue). It lists the RIDs that target this issue, across all projects you can browse, with their status and board decision. Raise a RID on this issue offers the reviews in reviewing phase where you can raise a RID: the fastest way to flag a problem on a requirement.
4. Audit log
The Audit log tab of a review, and the log of each item or change, list every operation (who, when, which fields, before and after). Each entry is chained to the previous one by SHA-256: Verify integrity recomputes the project's whole chain, checks it against the log head and reports the first entry that was modified, deleted or inserted, including deletion of the latest entries. It shows the head fingerprint: record it in minutes or an e-mail so you can later prove the log was not entirely rewritten.
5. Permissions
Permissions come from Jira and are recomputed on the server at every call:
| Action | Who |
|---|---|
| Browse | Anyone who can browse the project |
| Create a review | Depending on the site setting: anyone in the project, or project admins |
| Prepare, change phase | Chair, secretary, review creator, project admins |
| Raise a RID | Anyone in the project (or participants only if the review is restricted), in reviewing phase |
| Respond | Author, chair, secretary, creator, project admins |
| Decide | Chair or secretary, project admins, in board phase |
| Sign the minutes | Participants other than reviewers, once the review is closed |
| Configuration | Configuration managers and project admins; change requests: anyone in the project |
| Board decisions | Chair or secretary of the change board |
If the app licence is no longer active, everything remains readable and exportable, but nothing can be changed.
6. Rovo agent, skills and MCP server
On sites where Rovo is enabled, the app adds a Rovo agent, Design Review Assistant. Open Rovo chat, pick the agent and ask in plain language. It reads what you are allowed to read and nothing more: every tool call checks your Jira permissions on the project, then your role in the review.
What you can ask
| Ask | What the agent does |
|---|---|
| “Is the PDR ready for the board? What blocks its closure?” | Checks each exit criterion and names the RIDs that block it, the disputed RIDs, the overdue actions and the conclusions that are reachable now. |
| “Prepare the pre-brief for the next review board” | Writes the board pre-brief: verdict, exit criteria, decisions to take (majors first), RIDs that need arbitration, actions, proposed agenda. |
| “What is waiting for me in the design reviews of this project?” | RIDs to answer as author, decisions to record as chair or secretary, minutes to sign, your open actions, reviews where you can raise RIDs. |
| “Explain REV-2-007” | The RID in full, with the author's response, the board decision, the action and the history. |
| “Which review findings target ALT-42?” | RIDs raised against a Jira issue (a requirement, a component), across the projects you can browse. |
| “Help me raise a RID on the design file, section 4.3: …” | Searches for a RID that already covers the finding, drafts yours (one finding per RID: document, location, class, observation, proposed correction), shows the draft and raises it only after you confirm. Answer “yes” in the chat; Rovo then shows its own “Please review” card for the action, to be confirmed with Confirm selected. |
| “What changed since the last baseline, and which change caused it?” | Compares two baselines, or a baseline and the current configuration, and names the change request behind each revised item. |
| “Explain ECR-3” | Reason, affected items, change board, decision, customer agreement reference, implementation. |
| “Is the audit trail of this project intact?” | Recomputes the SHA-256 chain and gives the head fingerprint. |
The agent answers in your language. From an issue or a project page it uses the project of the conversation; elsewhere it asks for the project key.
What the agent never does
It records no board decision, writes no author response, signs no minutes, freezes no baseline and decides no change request. Those acts belong to the people who hold the role and are done in the app. The only thing the agent writes is a RID, in your name, under the same rules as in the app (review in reviewing phase, participants-only reviews, read-only licence). A RID raised this way carries a via Rovo mark in its panel and a “via Rovo” note in the audit log.
Skills
Three skills in the open Agent Skills format (a SKILL.md file each) hold the method the agent follows: review-board-prebrief (board pre-brief and agenda), rid-drafting (what a well-formed RID contains, and the confirmation step) and baseline-change-brief (configuration status, baseline comparison, change board agenda).
MCP server
The same eleven tools are also exposed to agents built in Rovo Studio through the app's rovo:mcp module, so that they can call them with your permissions. Whether external AI clients may connect is decided by your site admin (see the administration guide).