epic-doc

Maintains a single markdown brief per epic tracking status, open threads, and next tickets.

Updated Jul 19, 2026
One-click install
npx skills add https://github.com/forhas/pure-dev --skill epic-doc-forhas
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: epic-doc
Source: https://github.com/forhas/pure-dev/tree/main/plugins/notion-dev/skills/epic-doc
Command: npx skills add https://github.com/forhas/pure-dev --skill epic-doc-forhas

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Epic-level context in Notion tickets is scattered and stale: developers lose track of why an epic exists, what has landed, what is blocked, and which ticket to pick next. This Skill keeps one concise markdown brief per epic inside the repository, updated automatically as tickets start, stop, and resolve. ## Core Features & Use Cases - Single owned brief per epic: One markdown file at <knowledge.dir>/epic/<KEY>-<n>-<slug>.md with a fixed template (Why, Goal, Where we stand, Open threads, Decisions & constraints, Next), committed to the PR target branch. - Read, record, refresh, and note operations: Reads the brief as context when a ticket starts, rewrites it when a ticket resolves, derives the ## Next recommendation from live Notion child-ticket state, and routes new facts into the brief. - Bootstrap and drift repair: Distills an existing hand-written plan or the Notion epic page into a first brief, and detects and repairs drift between the brief and live ticket status. - Safe concurrent writes: All commits go through a locked, fetch-pull-commit-push write path with retry-on-rejection, so parallel runs never clobber each other or human edits. - Use Case: When a developer runs /notion-dev:ticket on a ticket belonging to an epic, the brief is read for background context; when the ticket merges, the brief is rewritten with what landed, which threads unblocked, and the next recommended ticket. ## Quick Start Ask the agent to read the epic brief for the current ticket and show the recommended next ticket and open threads.

Frequently Asked Questions about epic-doc

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep epic context up to date across Notion tickets?

Keep one markdown brief per epic in the repository and update it at ticket lifecycle events. This Skill reads the brief when a ticket starts, rewrites it when the ticket resolves, and refreshes the next-ticket recommendation from live child-ticket status.

How is the next ticket in an epic recommended?

The brief's Next section is derived from live state: unresolved children are ordered by phase, step, then numeric id, and item 1 is the first ticket with no unresolved blockers. In-progress and blocked tickets are listed separately so the three lists partition all unresolved children.

Can I edit the epic brief manually in git?

Yes, human edits are first-class. You can edit and commit the brief directly, and the record operation only changes lines it has evidence for, preserving everything else. Uncommitted local edits cause the writer to fail safely rather than overwrite them.

What happens if the epic brief does not exist yet?

The brief is bootstrapped from a seed: either a hand-written plan in docs/ matching the epic key, or the Notion epic page's overview plus its child tickets. The first record operation then writes the file to the epic branch.

How are concurrent writes to the epic brief handled?

Every commit goes through a locked write path: take a primary lock, fetch and fast-forward the epic branch, commit only the brief and index paths, then push with up to three retries on rejection. Failures are best-effort and never fail the caller's run.