Planning
The pages where a project's scope is written down: epics, the backlog of stories, tasks, bugs and spikes with their acceptance criteria, the functional and non-functional requirements, the business rules, the use cases with their flows, the RAID log, the decisions, the links between them, the comments and the files on each, every save kept as a restorable version, and the approvals that turn a draft into an agreed version; the rest as it lands.
The planning record is what a business analyst writes down once and every later phase reads: the scope the client agreed to, broken into the work the team will build, with the rules, the words and the risks around it. It begins with epics, the bodies of work the client recognises, the backlog of stories, tasks, sub-tasks, bugs, spikes and improvements under them, each story with the acceptance criteria that say when it is done, the requirements the system must honour (what it shall do and the qualities it shall keep) and the business rules the business has decided, and the use cases that say how each persona reaches a goal with the system, step by step, the RAID log of what may go wrong and what the project leans on, the decisions that record every choice with its options and consequences, the links that join all of these into one record read from either side, and the comments that carry the conversation on each of them, the baselines that freeze the agreed record at its approved versions, and the change requests that are the one way to reopen a frozen record. Every artefact in it carries a version for every save, by a person or by Heimdall, and any version can be put back.
| Piece | What it is |
|---|---|
| Epic | A body of work the client recognises, numbered from the project's tracker sequence (CRM-12), with its goal, value, measures, owner, MoSCoW priority, status from draft to done and dates. Releases are cut from epics and work items hang under them. |
| Work item | One row of the tracker: a story, task, sub-task, bug, spike or improvement, in the same number series as the epics, with its status from the backlog to done, its priority, the people on it, its estimates and the fields its kind adds. |
| Acceptance criterion | One sentence that says when a story is done, with an optional Given, When and Then and a kind (functional, negative, edge case, non-functional); QA ticks them and test cases are drafted from them. |
| Requirement | One sentence the system must honour: a functional requirement (CRM-FR-12) says what it does, a non-functional one (CRM-NFR-3) a quality it keeps, with a category and a measure. Each carries its statement, source, MoSCoW priority, verification method, owner and status from draft to baselined. |
| Business rule | A decision of the business the system must honour (CRM-BR-7): a constraint, derivation, computation, inference, action enabler or policy, in plain words with when it applies and what follows, exceptions, worked examples, authority, priority, the dates in force and the same status lifecycle as a requirement. |
| Use case | How an actor reaches a goal with the system (CRM-UC-4): the persona who acts, the other actors, the goal, the trigger, what must be true before and after, how often it happens, the priority, the same status lifecycle as a glossary term, and the steps of the main flow with the alternate and exception flows that leave it. |
| RAID item | An entry of the log (CRM-RSK-4): a risk scored by probability and impact with its mitigation and contingency, an assumption the plan rests on, an issue hurting now or a dependency on others, each with its area, owner, due or review date and a status from open to closed. Internal: a client guest never sees the log. |
| Decision | The record of a choice the project made (CRM-DEC-5): its kind, the context, the options weighed with their pros and cons, what was decided, the consequences, who decided and when, the decision it supersedes, and a status from proposed to accepted, superseded or deprecated. Internal: a client guest never sees the decisions. |
| Attachment | A file pinned on one artefact: a wireframe on a story, a signed specification on a requirement, a sample on a data entity. Kept on a private disk and served only through the application to a person who may see the artefact; added and removed, never versioned. |
| Comment | A note on one artefact: a question, an answer under it (a thread is one level deep), a finding, a decision taken in the margin. Open to everyone who sees the artefact, or internal and kept from client guests. Names people with @ to tell them; the first comment of a thread is resolved when the question is settled. |
| Follower | A person told of every comment posted on an artefact: anyone who commented on it, and anyone who pressed Follow in its discussion panel. |
| Label | A word the project pins on its work items (payments, tech-debt), with a colour and a meaning; the project's own vocabulary, unique within it, filtered by on the backlog and shaped from the backlog's label manager. |
| Link | A join between two artefacts of the project with a kind read from the source (CRM-142 implements CRM-FR-12) and read back from the target (CRM-FR-12 is implemented by CRM-142), kept once in the Links panel of both flyouts. Internal: a client guest never sees the links. |
| Reference | The key an artefact is known by, spelled from the project's key and a number that is never reused; epics and work items share one sequence, each kind of requirement and the rules have their own. |
| Priority | MoSCoW for epics, requirements and rules (must, should, could, won't) and five steps from lowest to highest for work items; the sprint planner and the release composer read them. |
| Version | What a save of an artefact leaves behind: the snapshot of its captured columns (a work item's criteria and a rule's examples inside it), the diff from the version before, who wrote it, through what, and why. Restoring one writes a new version rather than rewriting the past. |
| Baseline | A named set of approved records frozen together (the scope the client signs, what a release ships, what a sprint commits to, what a milestone promised): each record pinned at its approved version and locked once the project manager's approval freezes the baseline; a scope baseline then signed by the client's stakeholders. |
| Change request | The one way a frozen record changes (CRM-CR-2): why, who asked, the baseline it changes and the records it touches, the impact on scope, schedule, effort, cost and risk with a level, written by the analyst or drafted by Heimdall; its approval unlocks the records it names, and the change is seen through to verified. |
Approved means approved
Nobody moves an epic, a story, a requirement, a rule or a use case to approved by hand. The record is submitted, the people the project's policy names decide, and the approval stamps the version that was read; a client guest sees the record from that moment on. See approvals.
Pages
Epics
Write down the bodies of work the project will deliver, with their goal, value, measures, owner, priority, dates and colour; move them from draft to done.
Backlog
Write down the stories, tasks, sub-tasks, bugs, spikes and improvements, move them along their lifecycle, hand them to people and size them.
Acceptance criteria
Write the sentences that say when a story is done, each with an optional Given, When and Then, ordered and kept with every version of the story.
Functional requirements
Write down what the system shall do, one testable sentence each, with its source, priority and verification method; move them from draft to baselined.
Non-functional requirements
Write down the qualities the system shall keep, each with the category it belongs to and a measurable target.
Business rules
Write down the decisions of the business in plain words, with when they apply, what follows, their exceptions and worked examples; move them from draft to baselined.
Use cases
Write down how each actor reaches a goal with the system: the actor, the goal, the trigger, the conditions before and after, and the steps of the main flow with the branches that leave it.
RAID log
Write down what may go wrong and what the project leans on: risks scored and placed on the matrix, assumptions, issues and dependencies, each owned, dated and moved from open to closed.
Decisions
Record every choice the project made with the context, the options weighed, what was decided and what follows; accept, reject and supersede them, and keep the reasoning.
Traceability
Link a story to the requirement it implements, a bug to the story that fixes it, a decision to the epic it shapes; read every link from either side and open the other end.
Comments and mentions
Ask and answer in threads under any artefact, name people to tell them, keep a note from the client, resolve the thread, and follow what you care about.
Labels
Give the project a short vocabulary of its own, pin the words on stories and bugs, filter the backlog by one, and rename or retire a word without touching the items.
Attachments
Pin wireframes, signed specifications and sample files on any artefact, open them through the application, and remove them when they no longer apply.
Revisions and versions
Read how an artefact changed, version by version, who changed it and through what, and put an earlier version back without losing anything.
Approvals
Submit an epic, story, requirement, rule or use case for review, let the people the project's policy names decide, and keep every signed verdict; the inbox, the clocks and the policies.
Baselines
Compose a baseline from the approved record, have the project manager's approval freeze it and the client sign the scope, read what it holds, and supersede it when the next one lands.
Change requests
Raise a change against a frozen baseline, name what it touches, write or ask Heimdall for the impact, convene the council, and let the approvers' word unlock exactly the records named.
What reads the planning record
- The project overview and the sidebar count the epics, the open items, the requirements, the rules and the use cases a person may see, and the RAID items that still need attention.
- Heimdall reads epics, the backlog, the requirements, the rules and their versions through the same tools the MCP server offers, drafts stories, requirements and rules as drafts a person reviews, and moves and assigns items when asked; the brief import will draft whole epics' worth of them into a review queue once it lands.
- A baseline freezes approved epics, stories, requirements, rules and use cases at their approved versions and locks them; an approved change request unlocks the ones it names, and nothing else does.
- Use cases will link to requirements, rules and stories and share their numbering style, their versions and their review lifecycle; the board, the sprints, the test cases and the traceability matrix will read the backlog, the requirements and the rules as those modules land.
Permissions
| Action | Permission |
|---|---|
| See the epics | epic:view-any and epic:view; a client guest sees agreed epics |
| Add, change, move an epic | epic:create, epic:update |
| Delete an epic | epic:delete |
| See the backlog | work-item:view-any and work-item:view; a client guest sees agreed items |
| Add, change an item or its criteria | work-item:create, work-item:update |
| Move or hand over an item | work-item:transition, work-item:assign |
| Delete an item | work-item:delete |
| See the requirements | requirement:view-any and requirement:view; a client guest sees agreed requirements |
| Add, change, move a requirement | requirement:create, requirement:update |
| Delete a requirement | requirement:delete |
| See the rules | business-rule:view-any and business-rule:view; a client guest sees agreed rules |
| Add, change, move a rule | business-rule:create, business-rule:update |
| Delete a rule | business-rule:delete |
| See the use cases | use-case:view-any and use-case:view; a client guest sees agreed use cases |
| Add, change, move a use case | use-case:create, use-case:update |
| Delete a use case | use-case:delete |
| See the RAID log | raid:view-any and raid:view; never a client guest |
| Raise, change, move an item | raid:create, raid:update |
| Delete an item | raid:delete |
| See the decisions | decision:view-any and decision:view; never a client guest |
| Record, change, move a decision | decision:create, decision:update |
| Delete a decision | decision:delete |
| See the links of an artefact | link:view-any and link:view; never a client guest |
| Link two artefacts | link:create |
| Remove a link | link:delete |
| See the discussion | comment:view-any and comment:view; a client guest the open comments only |
| Post a comment | comment:create; a client guest only when the project's Guests may comment is on |
| Post an internal comment | comment:internal; never a client guest |
| Edit, resolve or delete anyone's comment | comment:update, comment:delete |
| See the labels and filter by one | work-item:view-any |
| Pin labels, add, rename or remove a word | work-item:update |
| See and open the files on an artefact | attachment:view-any and attachment:view; a client guest on the agreed record |
| Attach a file | attachment:create; never a client guest |
| Remove anyone's file | attachment:delete |
| Read and restore versions | The artefact's view and update permissions; staff only |
| See the baselines | baseline:view-any and baseline:view; a client guest sees the frozen baselines |
| Compose, change, supersede a baseline | baseline:create, baseline:update |
| Submit a baseline, ask the client to sign | baseline:freeze |
| Delete a draft baseline | baseline:delete |
| See the change requests | change-request:view-any and change-request:view; a client guest sees their own |
| Raise, change, move a change request | change-request:create (a client guest too, without the impact), change-request:update |
| Analyse, submit, verify a change request | change-request:analyse, change-request:approve, change-request:verify |
| Delete a change request never agreed | change-request:delete |
Related
- Brief import — Heimdall drafts the whole planning record from a brief; you accept what fits
- Projects — the record the planning pages hang under
- Status reference — every status, kind, priority, resolution and revision reason
- Epics API, Work Items API, Requirements API, Business Rules API, Use Cases API, RAID Log API, Decisions API, Links API, Comments API, Watchers API, Labels API, Attachments API, Baselines API, Change Requests API, the Planning tools and the Build tools
How is this guide?
Last updated on
Clients
The Clients page: the organisations your team does projects for, adding one with its contacts and status, editing it, archiving and restoring it, and why a client with projects is never deleted.
Epics
The Epics page of a project: each body of work with its reference, goal, value, measures, owner, MoSCoW priority, status, dates and colour, its lifecycle and its versions.