---
name: issue-description
metadata:
  version: "0.24.9"
description: Write rich, durable issue/ticket descriptions. Use when creating or updating tickets by hand, when composing bodies for ticket-sync, or when a work item needs a description a future reader (human or agent) can act on without archaeology.
---

# Rich issue descriptions

An issue is a durable intent record, not a task title. Issues outlive PRs
and are read by more people — including future agents. Every issue should
let a zero-context reader understand what, why, where it sits, and what
"done" looks like.

## The mechanical path (worklog-synced tickets)

For items in the event log, do not hand-write bodies:
`bin/worklog ticket-body <ulid>` renders the item's graph node — summary
(from `--body`), context (epic, generating plan with its frozen wiki page,
milestone, unplanned provenance), and traceability (decides/implements
edges, delivered-by PRs). ticket-sync pushes that. To make a ticket richer,
enrich the SOURCE: `worklog update --body`, `worklog link-pr`, sidecar
`relates_to` edges — never just the remote ticket (it would drift back).

## Template (hand-written issues, or systems without worklog)

    ## Summary
    One or two sentences: what needs to be done and why it matters.

    ## Context / Big picture
    Where this sits in the larger system or epic. Link the parent epic and
    the plan that generated it.

    ## Problem / Motivation
    What is painful or missing today? "What"-only issues rot; "why" keeps
    them useful.

    ## Desired outcome
    What does done look like? Concrete and observable.

    ## Scope
    In scope: ...
    Explicitly out of scope: ...

    ## Proposed approach (optional)
    High-level design or sequence if known. Link relevant ADRs/design docs.

    ## Acceptance criteria
    - [ ] ...

    ## Traceability
    Plan / Epic / ADRs / Spec sections / Related issues.

    ## Notes for implementers & agents
    Traps, sequencing rules, non-obvious constraints, "never do X" guidance
    written for the next agent that picks this up.

## Rules

- Omit sections that have no real content — no boilerplate placeholders.
- Every plan-generated issue links back to its frozen plan page: the why
  lives in the plan, the issue carries the pointer.
- Surface risks and open questions early; uncertainty stated is uncertainty
  managed.
- Body text must be readable by a junior dev or PM: no bare ULIDs in prose
  (spec §13.4); ULIDs belong in the machine footer.