lisa-prd-backlink

PRD Back-link

Write or update the ## Tickets section of a source PRD so it links to every work item created from that PRD. The Debrief flow (and a human reading the PRD months later) uses this section as the canonical work-item set for the initiative.

This documented section is the always-written, machine-readable record of the generated child set. It is written for every source_type — including the vendors that also get a native hierarchy link (github / linear / jira) — so the generated top-level work is readable later from the PRD body alone, without parsing free-form comments or depending on a native relationship that may be unavailable on older hosts or across vendors. Native hierarchy linking (see the per-vendor sections below) is additive to this section, never a substitute for it. This is the documented-section leg of the prd-lifecycle-rollup rule (cited by slug; its taxonomy is not restated here).

Input

Pass $ARGUMENTS as a single JSON-style block:

{
  "source_type": "notion" | "confluence" | "linear" | "github" | "file",
  "source_ref": "<URL, page id, project id, issue ref, or absolute file path>",
  "tickets": [
    { "key": "<tracker-key>", "title": "<summary>", "type": "Epic|Story|Task|Sub-task|Bug|Spike", "url": "<link>", "parent_key": "<key or null>" }
  ],
  "section_heading": "## Tickets"   // optional override; default "## Tickets"
}

Behaviour

1. Fetch the current PRD content using the source's native read tool:

   • notion → notion-fetch
   • confluence → getConfluencePage
   • linear → Linear MCP project / issue read
   • github → gh issue view
   • file → Read tool on the absolute path

2. Locate the existing section. Search for section_heading (default ## Tickets). The canonical heading is ## Tickets; ## Generated Work is an accepted alias that the reader recognizes — match either heading when locating an existing section so a PRD authored with either name is found and regenerated in place (never duplicated under the other name). If present under either name, you will replace it (keeping whichever heading was already there, or the explicit section_heading override). If not present, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.

3. Render the section. Always render it — for every source_type, even when a native hierarchy link was also made (additive, not exclusive). Use the format below. Group by Epic. Within an Epic, group by Story. Sub-tasks nest under their Story. Bugs and Spikes that are not under a Story go in a flat list at the bottom. Each entry carries a machine-readable token (ref + URL + type + parent) so the generated child set is parseable without reading prose — see Format.

4. Write the updated PRD back using the source's native write tool:

   • notion → notion-update-page
   • confluence → updateConfluencePage
   • linear → Linear MCP update
   • github → gh issue edit --body
   • file → Edit (preferred) or Write (full rewrite if needed)

5. Record the PRD→child relationship in the source tool's native hierarchy where the source supports it and the destination tracker is the same system. Each supported source has its own native-linking section, all governed by the same generated-top-level-work contract, child-ref idempotency, and graceful-degradation discipline from the prd-lifecycle-rollup rule:

   • github (same repo as the created tickets) → native GitHub sub-issue of the PRD issue — see Native parent linking (GitHub).
   • linear (PRD also lives in Linear) → native parent / project relationship — see Native parent linking (Linear).
   • jira (PRD also lives in the same JIRA/Atlassian instance) → native parent / Epic link or a documented issue-link type — see Native parent linking (JIRA).

   The documented ## Tickets section from step 3 is always written regardless; native linking is in addition to it, not a replacement (the documented section is the cross-vendor and older-host fallback per the prd-lifecycle-rollup rule). Sources without native issue hierarchy (Notion, Confluence, file) rely on the documented section alone, as does any cross-vendor combination (e.g. a Notion PRD with a JIRA tracker).

6. Return the rendered section (so the caller can include it in its own report) and the source URL of the updated PRD.

Format

The rendered section must be deterministic — same inputs produce identical output bytes. This is what makes idempotency reliable. Every entry is simultaneously human-readable (a nested markdown link) and machine-readable (a trailing structured token), so the generated child set can be enumerated by parsing this section alone — the contract LPC-1.3 rollup (github-prd-intake / *-prd-intake) reads against, with no need to scrape free-form comments.

## Tickets

_Generated by `lisa-prd-backlink`. Regenerated on every Plan run; do not edit by hand._

### <Epic key>: <Epic title>

- [<Epic key>](<url>) — Epic <!-- lisa:gw ref=<ref> url=<url> type=Epic parent= -->
  - [<Story key>](<url>) — Story: <title> <!-- lisa:gw ref=<ref> url=<url> type=Story parent=<Epic ref> -->
    - [<Sub-task key>](<url>) — Sub-task: <title> <!-- lisa:gw ref=<ref> url=<url> type=Sub-task parent=<Story ref> -->
    - [<Sub-task key>](<url>) — Sub-task: <title> <!-- lisa:gw ref=<ref> url=<url> type=Sub-task parent=<Story ref> -->
  - [<Story key>](<url>) — Story: <title> <!-- lisa:gw ref=<ref> url=<url> type=Story parent=<Epic ref> -->

### <Epic key>: <Epic title>
...

### Unparented items

- [<Bug key>](<url>) — Bug: <title> <!-- lisa:gw ref=<ref> url=<url> type=Bug parent= -->
- [<Spike key>](<url>) — Spike: <title> <!-- lisa:gw ref=<ref> url=<url> type=Spike parent= -->

Machine-readable entry token

Every list entry ends with a single-line HTML comment — invisible in rendered markdown, so the section stays clean for humans, but a stable, greppable record for machines:

<!-- lisa:gw ref=<ref> url=<url> type=<type> parent=<parent-ref or empty> -->

• lisa-gw — a fixed sentinel (gw = generated work). A reader enumerates the generated child set by matching <!-- lisa:gw lines; it never has to parse the surrounding prose, headings, or indentation.
• ref — the child-ref identity from the prd-lifecycle-rollup rule: <org>/<repo>#<n> for GitHub, the issue/project identifier (e.g. TEAM-123) for Linear, the issue key (e.g. PROJ-123) for JIRA. This is the same dedupe key native linking uses, so the documented record and the native record agree.
• url — the canonical URL of the work item.
• type — Epic | Story | Task | Sub-task | Bug | Spike (verbatim from the ticket's type).
• parent — the ref of this entry's parent (its parent_key resolved to the parent's ref), or empty when the entry is top-level (parent_key null/empty). A reader selects the generated top-level child set — exactly what the PRD owns per the rule — as every lisa-gw line whose parent is empty.

The visible markdown link and the token always carry the same ref/url/type; the token is the authoritative machine field (the prose may wrap or be reflowed by a host editor, the comment line will not). Field order within the token is fixed (ref, url, type, parent) so output is byte-stable.

If the input contains zero items, write the section header with a single line: _No tickets created — Plan flow may not have completed._ Do not omit the section; presence-of-section is itself a signal to Debrief, and the always-written guarantee means a reader can always distinguish "ran, produced nothing" from "never ran."

Idempotency

Rendering rules:

• Sort epics by key (lexical). Sort stories within an epic by key. Sort sub-tasks within a story by key. Sort the unparented list by (type, key). The same sort applies to the lisa-gw tokens (each token sits on its entry's line), so the machine-readable order is identical across runs.
• The line _Generated by ..._ is fixed text — does not include a timestamp. A timestamp would defeat the diff-equality check Debrief relies on.
• Regenerate the whole section from the current ticket set on every run — never append. Dedupe is by child-ref (the token's ref, per the prd-lifecycle-rollup idempotency dedupe key): the same ticket set produces a byte-identical section with no duplicate entries, and re-running over an existing section is a no-op diff. A ticket present in a prior run but absent now simply does not reappear (stale links never accumulate).
• Match by stable ref, never by title (prd-lifecycle-rollup idempotency dedupe key). A child is identified by its ref token alone — a ticket whose title changed but whose ref is unchanged is the same entry: its displayed title is refreshed in place and it appears exactly once, never duplicated. Title is rendered, never matched on.

Native parent linking (GitHub)

When source_type: github and the PRD issue lives in the same repository as the created tickets, make the PRD the structural parent of the work it generated by linking each generated top-level work item as a native GitHub sub-issue of the PRD issue. This is the GitHub leg of the PRD→child native-hierarchy requirement in the prd-lifecycle-rollup rule (cite it by slug; do not restate its taxonomy here). The documented ## Tickets section is still written either way — native linking is the first-class relationship; the documented section is the durable fallback for cross-vendor and older hosts.

This section is GitHub-only. The Linear and JIRA native parents have their own sections below (Linear, JIRA); the documented-section-only fallb

Content truncated.