Epics
An epic is a body of work that doesn’t fit inside one board. “Passwordless auth” touches the web app, the API and the CLI; each has its own project, but it’s one piece of work with one story.
Epics belong to a product and can gather issues from any project in that product. An issue belongs to at most one epic, and unlinking or deleting an epic never deletes the issues.
What an epic holds
- A brief — name, description, status (
planned,active,paused,done,cancelled), priority and an optional target date - Issues — pulled from any project in the product, with a live progress rollup
- People — an owner who is accountable, plus everyone else involved
- A journal — the part that matters most
The journal
Every epic has a chronological, typed journal. Notes are written oldest-first, so reading top to bottom gives you the history rather than a pile of latest comments.
Each note has a kind:
| Kind | Use it for | Resolvable |
|---|---|---|
| Comment | Ordinary discussion | no |
| Update | Progress since the last note | no |
| Decision | A choice that was made, and why | no |
| Blocker | What is stopping progress | yes |
| Context | Durable background worth keeping | no |
| Risk | Something that may go wrong | yes |
Filter by kind to read just the decisions, or just what’s currently blocking.
An issue’s comments are the same object. Same kinds, same threading, same resolution — a comment is simply the kind an issue defaults to, where an epic note defaults to an update. So anything below about blockers and risks is as true of an issue as it is of an epic. See Core concepts.
Threads
Any note can have replies, one level deep. Discussion about a blocker stays
attached to the blocker instead of scattering through the journal. Filtering by
kind always returns a whole thread — otherwise you’d filter for blocker and
lose the reply that explained how it was cleared.
What a blocker is blocked on
A blocker or a risk can name the things it is waiting on, as links rather than a ticket number typed into the prose. Each link is one of:
- another issue, in any project in the organization
- an epic
- an external URL — a vendor ticket, a contract, anything outside Projectrr, with an optional label
A note can carry several. They render as clickable chips under the note, each showing the target’s current status, and a link whose target is already done or cancelled is dimmed — that’s the signal the blocker can probably be resolved. Links appear on the issue’s Needs attention panel too, so what a stuck issue is stuck behind is readable without opening the thread.
Linked issues and epics must belong to the same organization; the API rejects anything else. Deleting the linked issue or epic removes the link, not the note.
Resolving blockers and risks
Blockers and risks stay open until someone closes them. Resolving one stamps who closed it and when, and records the explanation as a reply — the original note still reads as what it was at the time. Nothing is edited away.
Reopen a note if it turns out the problem came back.
Open blockers and open risks are counted on the epic list and on the epic page, independently of whatever filter you’re looking through, so a blocker can’t hide. An issue with open items counts them the same way, on the issue page.
The organization dashboard rolls the same counts up across every product, in a
Needs attention panel: everything with an open blocker or risk — epics and
issues together, each row labelled and linking to its own page — most blocked
first, then most at risk. It leaves out epics that are done or cancelled,
issues in a done or closed status, notes that have been resolved, and
replies: a blocker raised as a reply belongs to its thread rather than standing
as an item of its own. The panel lists the ten worst and tells you when it is
showing a capped list.
Each row also shows what its open items are
blocked on, as the same clickable chips — so
the dashboard answers “what is holding this up” and not only “how much is”. A
target named by two blockers on the same row is shown once, and a row waiting on
more than four things shows the first four and a +N more count.
Resolve a blocker with a note saying how you cleared it. Editing or deleting the original destroys the history that made the journal worth keeping.
Status reports and sharing
Every epic has a report view: progress, the people on it, open blockers and risks, work grouped by state, and the journal. Print it to PDF straight from the browser, or publish it as a read-only share link for stakeholders who don’t have an account. Share links are revocable.
Epics and AI agents
The journal is the reason Projectrr’s MCP server exists. An agent is told to read an epic before it starts work and to write back what it decided when it finishes, which means:
- The agent starts from the decisions you already made rather than re-litigating them
- The next session — human or agent — picks up where the last one left off
- Blockers an agent hits are recorded as blockers, not lost in a chat transcript
From the CLI that’s prr epic view <slug> --product=<slug> and
prr epic note add. Over MCP it’s epic_view and epic_note_add.