epiq

name	epiq
description	Workflow rules for working the epiq issue board — use the epiq MCP, sync on demand, scope tickets small, keep status/tags accurate, and communicate via comments.

Epiq board workflow

• Never test against the real board. Point any dev server, manual test or test run at a throwaway project, never at this repo's own. Deleting test tickets afterwards does not undo the events. Stop the dev server when you're done rather than leaving it autosyncing.
• Use the epiq MCP tools (epiq_*) for all board operations — never the epiq CLI or hand-edited state files.
• Never edit the state branch directly. Don't check it out, don't write to its worktree, don't touch the event log or any file under it by hand or by script — go through the MCP for every read and write. The event log is the system of record: an edit made outside it bypasses validation and ordering, and can corrupt history in ways no later fix can undo.
• Sync is on-demand only. MCP reads/writes operate on local state and never pull/push automatically. Call epiq_sync explicitly when you need the latest remote state or want to publish local changes.
• Break work into small, scoped tickets. One ticket per independent unit of work, not one giant ticket for a whole feature/epic. Small tickets move through the board cleanly and are easier to review.
• Keep the status column current as work progresses
• Assign the ticket to yourself when you pick it up, alongside moving it to Ongoing — so the board shows who is on what, not just what is in flight.
• Work under the name you were given, for the whole session. Your board identity comes from EPIQ_USER_NAME in the environment that launched you, and it holds for the session — every ticket, comment and move you write is attributed to it, so keep working under it rather than borrowing the user's. Never invent or change a name yourself: an identity is permanent once it has authored anything (tombstoneContributor refuses authors), and each one adds a contributor and an event log file. If EPIQ_USER_NAME is unset you are writing as the user — say so once rather than silently signing their name to your work.
• **Prefix commits with the ticket ref. **Retrieve the ref programmatically, NEVER DERIVE IT.** Read the ref field off the MCP response (epiq_issue_list and epiq_board_list include it on every entry). This is what link-by-reference feature matches on.
• Never work on main, and never merge into it locally. Every change reaches main through a pull request. Branch before the first edit, push the branch, open the PR, let the gate run, then integrate it. A local merge into main looks like it worked and is invisible to everyone else: the work is on nobody's remote, no PR ran the gate over it, and it is one git fetch origin +main:main away from vanishing from the branch you are sitting on. That has already happened here — a tag-filter feature and a scrubber-URL feature lived only in one machine's local main for a day, and disappeared the moment somebody synced main with the remote. If you find yourself with commits on local main, move them onto a branch and open a PR before doing anything else.
• Always rebase-merge. Rebase the branch onto the target first, then integrate with a rebase merge — gh pr merge --rebase, never --merge and never --squash. Main stays a flat sequence of ref-prefixed commits, which is what the commit↔ticket linking reads. A merge commit adds a subject carrying no ref and buries the branch's commits behind it; a squash folds every ref-prefixed commit into one, so main ends up with no trace of which commits belonged to which ticket. Squashing is fine within a run of commits that share the same ref prefix (they're already one ticket's worth of history); never squash across commits carrying different refs into one.
• Tag tickets properly. Reuse existing tags where they fit (check current issues/tags first) instead of inventing near-duplicates.
• Read the ticket's comments before starting, not just its description. The description is what was known when the ticket was written; comments carry later context — narrowed scope, a decision already taken, a dead end someone hit, a correction to the original diagnosis. Working from the description alone risks redoing settled work or implementing something that was already ruled out.
• Use comments to communicate deviations. If the work diverges from what the ticket describes — scope changes, findings, blockers, test results — record it as a comment on the ticket, not just in chat.
• When a ticket is done, Document the outcome in a comment starting with Solution:. Use that exact prefix as the comment's opening line, so ^Solution: finds every resolved ticket on the board. Say what actually resolved it — the commit, the approach taken, and anything a reader would otherwise have to reverse-engineer from the diff; a bare commit hash is not a solution. Use the same prefix when a ticket is closed without a code change, and say why.
• Be concise. Titles, descriptions, and comments should be scannable, not essays.
• If a ticket is blocked, record the blocker in a comment and move it to Blocked (or tag it blocked if there is no Blocked column).
• If a you decide to take a new approach, make sure to document the fork in a new comment, and tag the ticket with a "fork" tag, update the description to reflect the new plan. Don't leave it as-is and expect readers to infer the change from comments.
• Park decisions that are the user's to make. A design fork, a change with blast radius beyond its ticket, anything you'd want a second opinion on — file a ticket tagged human-input-needed naming the options and the trade-off, then carry on with whatever doesn't depend on the answer. Settling it alone in chat, while nobody is reading, is a decision the user never made.
• Findings from a code review get their own tickets, tagged from-review, with the description saying which branch or PR the review covered — so the provenance survives even if the tag doesn't.