@codyswann/lisa 2.9.1 → 2.10.0

package/plugins/src/base/skills/prd-backlink/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: prd-backlink
+description: "Update a source PRD with a `## Tickets` section linking back to every work item created from it. Vendor-aware on the source side (Notion / Confluence / Linear / GitHub Issue / file) and tracker-agnostic on the ticket side. Idempotent — regenerates the section on each run rather than appending, so re-planning never accumulates stale links. Invoked by the *-to-tracker skills at the end of their pipeline and standalone if a PRD's Tickets section needs to be refreshed."
+allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
+---
+
+# 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.
+
+## Input
+
+Pass `$ARGUMENTS` as a single JSON-style block:
+
+```json
+{
+  "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`). If present, you will replace it. If not, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.
+3. **Render the section.** 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.
+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. **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.
+
+```markdown
+## Tickets
+
+_Generated by `lisa:prd-backlink`. Regenerated on every Plan run; do not edit by hand._
+
+### <Epic key>: <Epic title>
+
+- [<Epic key>](<url>) — Epic
+  - [<Story key>](<url>) — Story: <title>
+    - [<Sub-task key>](<url>) — Sub-task: <title>
+    - [<Sub-task key>](<url>) — Sub-task: <title>
+  - [<Story key>](<url>) — Story: <title>
+
+### <Epic key>: <Epic title>
+...
+
+### Unparented items
+
+- [<Bug key>](<url>) — Bug: <title>
+- [<Spike key>](<url>) — Spike: <title>
+```
+
+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.
+
+## 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 line `_Generated by ..._` is fixed text — does not include a timestamp. A timestamp would defeat the diff-equality check Debrief relies on.
+
+## Failures
+
+- **Source unreachable / permission denied.** Stop and report. Do not silently swallow.
+- **Section already present but in a non-standard format** (e.g., user hand-edited it). Replace it anyway — the warning line `_do not edit by hand_` is the contract. Note in the run output that an existing section was overwritten.
+- **Source is a Notion database URL, a Confluence space URL, or any other non-page input.** Stop — back-linking only makes sense against a single PRD page, not a queue. Direct the caller to pass the specific page.
+
+## Output
+
+```text
+PRD back-link updated: <source_url>
+Section: ## Tickets — <n> epics, <n> stories, <n> sub-tasks, <n> unparented (<bugs/spikes>)
+```