@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-devin/skills/lisa-linear-sync/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: lisa-linear-sync
+description: "Syncs plan progress to a linked Linear Issue. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep Linear Issues in sync. The Linear counterpart of lisa-jira-sync and lisa-github-sync."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Sync Plan to Linear: $ARGUMENTS
+
+Post milestone updates to the linked Linear Issue at key plan-lifecycle moments. This skill is the destination of the `lisa-tracker-sync` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## When to invoke
+
+Callers (planning skills, lifecycle skills) invoke this skill at:
+
+| Milestone | What to post | Suggested role |
+|-----------|--------------|----------------|
+| Plan created | Plan contents (sections + ordered tasks) as a comment | `ready` |
+| Implementation in progress | Branch URL + first commit | `claimed` |
+| PR ready for review | PR URL + summary, the implementation handoff comment | `review` — **optional; omitted by most projects, in which case there is no transition to suggest** |
+| PR merged | Merge SHA + deploy environment (if known) | env-keyed `done`, **then run Phase 4b — mandatory when the merge target is a non-terminal env branch** |
+
+**Roles, never literal state names.** Resolve each through the shared resolver; the state names above are whatever the project configured, and a role the project did not configure has no suggestion at all:
+
+```bash
+resolve() {
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor linear --intent read 2>/dev/null
+}
+```
+
+**This skill SUGGESTS transitions. It never writes the lane.** That matches `lisa-jira-sync` ("suggest, but don't automatically perform") and `lisa-github-sync` ("this skill never relabels"), and it is what this skill's own dispatcher already advertises: `lisa-tracker-sync`'s description reads *"Suggests (never auto-transitions) the next status."* Lane writes belong to the build-intake / agent owner, which is already true on the other two trackers.
+
+`--rollup` is the one exception and is documented in Phase 4b — parent derivation is its entire purpose and is separately gated.
+
+## Input
+
+`$ARGUMENTS` is `<IDENTIFIER> <milestone>` where:
+
+- `<IDENTIFIER>` is the Linear Issue identifier (e.g. `ENG-123`). If not provided, the skill searches the active plan file for a linked Linear Issue.
+- `<milestone>` is one of `plan-created`, `implementation-in-progress`, `pr-ready`, `pr-merged`.
+- Optional tokens include `pr_url=<url>` for the live pull request and `merge_sha=<sha>` once merged.
+
+## Phase 1 — Resolve Issue
+
+1. If `$ARGUMENTS` includes an identifier, parse it.
+2. Else search for the active plan file (most recent file under `plans/`) and extract the linked Linear Issue identifier from its frontmatter.
+3. Fetch the Issue via `lisa-linear-access operation: get-issue` to confirm it exists.
+
+## Phase 2 — Compose Milestone Comment
+
+Per the milestone, build the comment body. Include:
+
+- A milestone header (e.g. `**Plan created** — <plan-file>`)
+- Relevant links (plan file, branch, PR)
+- A short summary (first 5 lines of the plan section / commit message / PR description)
+- The suggested status transition
+
+Example for `plan-created`:
+
+```markdown
+**Plan created** — `plans/feat-X.md`
+
+Sections:
+- Phase 1: Schema doc
+- Phase 2: Linear destination skills
+- ...
+
+Tasks: 7 ordered items.
+
+Next: implementation begins. Suggested state: **Ready**.
+```
+
+## Phase 3 — Post Comment
+
+Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <comment>})`.
+
+## Phase 3b — Ensure PR Backlink
+
+When `$ARGUMENTS` includes `pr_url=<url>` for `pr-ready` or `pr-merged`, ensure the Linear Issue has a durable ticket -> PR link:
+
+1. Prefer Linear's native GitHub attachment / pull request link when the integration has attached the PR through the branch name, PR title, or PR body issue identifier. Verify by re-reading the Issue and its attachments / relations where the Linear access layer exposes them.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
+
+The PR branch/title/body identifier is the PR -> Linear side. This phase is the required Linear -> PR side.
+
+## Phase 4 — Suggest the Next State (never write it)
+
+Name the suggested next state in the milestone comment and stop. **This skill does not set `stateId`.** The lane write belongs to `lisa-linear-build-intake` / `lisa-linear-agent`, exactly as the `status:*` write belongs to `lisa-github-build-intake` on GitHub.
+
+Resolve the suggestion by role, and **say nothing when the role is unset**:
+
+| Milestone | Role to resolve | When the role is unset |
+|---|---|---|
+| `plan-created` | `ready` | required — report a setup defect |
+| `implementation-in-progress` | `claimed` | required — report a setup defect |
+| `pr-ready` | `review` | **optional — suggest no transition; the Issue stays in `claimed`** |
+| `pr-merged` | `done` for the PR's target env (via `deploy.branches`) | required — report a setup defect |
+
+If a resolved state doesn't exist on the team, that is a setup defect — report it and point at `/lisa:setup:linear`. Never create a workflow state here: a state carries a `type` and a board position, and guessing either puts the Issue somewhere no human sanctioned. Equally, never *find* one: resolving a role by scanning the team for a state whose name or `type` looks right picks by board position, not intent, and the states that surface that way are the human-only lanes a project deliberately left out of its config.
+
+> **Removed: `--update-state`.** This flag previously let a caller make Phase 4 write the state. It was the only lane-write path in any sync skill, and combined with a defaulted `review` role it moved Issues into review states that projects had never configured. Callers that relied on it should let the build-intake owner make the transition; `--rollup` is unaffected.
+
+No single-lane verification is needed: an Issue holds exactly one workflow state by construction, so the two-lanes-at-once corruption the old label-driven lane could produce is unrepresentable. (It was not hypothetical — 16 issues carried two `status:*` labels at the time of the migration.)
+
+## Phase 4b — Reconcile Native Auto-Close (Linear-specific)
+
+Linear's per-team **git automations** complete a linked Issue on merge to **any branch** — unlike GitHub's default-branch-scoped `Closes` auto-close — so a magic word (`Closes`/`Fixes`/`Resolves ENG-123`) or branch-name linkage can move the Issue to a `completed` state at a **non-terminal** env merge, front-running the env-keyed ladder.
+
+**Since the build lane moved to native states, this phase is a BACKSTOP, not the primary defence.** The lifecycle now writes the same field the automation writes, so the disagreement it repairs can only arise when something outside Lisa moves the Issue. The primary fix is upstream and structural: `/lisa:setup:linear` detects the team's `merge → Done` git automation and offers to delete it, because with this model that automation is a redundant second writer as well as a wrong one. Keep this phase — a workspace can always re-add the automation, and a magic word in a hand-written PR body still fires — but a recurrence here is a **setup defect to report**, not routine repair to absorb silently.
+
+Run it whenever the resolved env is **intermediate** (below the production terminal `done`):
+
+1. Resolve the merged PR's base branch to its env via `.lisa.config.json` `deploy.branches` (`config-resolution`). If it maps to the production/terminal `done`, this phase is a **no-op** — native completion is correct there.
+2. **Uniform / single-environment no-op.** When the project's env-keyed `done` map is uniform — every environment resolves to the same `Done`, as in this repo (`production: main` only) — dev-merge == terminal, so native completion is correct. Do nothing. Only a **non-uniform** env→`done` map (distinct `On Dev`/`On Stg`/`Done` rungs) can desync.
+3. Otherwise (non-uniform map, resolved env intermediate): re-read the Issue's `state`. If it sits in a `completed`-typed state while the derived role is a lower env rung, **re-open** the native state by moving it back to the correct env rung (via `lisa-linear-access operation: save-issue lifecycle_role: done env: <resolved-rung>` — the backstop names the role and the rung like every other lifecycle write; it never re-derives a state ID itself) and post a short `[lisa-linear-sync]` reconciliation comment **naming the likely cause** — a live `merge → Done` git automation, or a magic word in the PR body. This applies the `leaf-only-lifecycle` "Terminal native closure" rule — closure fires **only** at the production terminal `done`. Cite the rule by slug; do not restate it.
+4. **Safe default.** If the true terminal cannot be resolved (ambiguous env or unresolvable `done` map), do not change the `state` — post a `[lisa-linear-sync]` reconciliation-suggestion comment and leave it untouched, mirroring the Phase 5 safe default.
+
+## Phase 5 — Parent Status Rollup (`--rollup`)
+
+When the caller passes `--rollup`, this skill **derives a parent/container's workflow state from the roll-up of its children** instead of acting on a leaf. A **Project** (the Epic equivalent) rolls up from its Issues; an **Issue** rolls up from its sub-Issues. This implements the Linear child-issue-status arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy.
+
+**Resolve the child set the same way `lisa-linear-read-issue` does** — `lisa-linear-access operation: list-issues({project: <id>})` for a Project's Issues, or `lisa-linear-access operation: get-issue` per child for an Issue's sub-Issues (via `parentId`). Capture each child's workflow state. If the item has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
+
+**Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the Linear env-keyed `done` map) and take the first match** (canonical roles from `config-resolution`; the Linear state map is the configured `blocked`, `claimed`, optional `review`, and env-keyed `done` — resolve each by role, and treat an unset `review` as simply having no such rung):
+
+| If among the required child leaves… | Derived parent role | Linear state |
+|---|---|---|
+| any child carries `Blocked` | `blocked` | `Blocked` |
+| else **every** required child has shipped to some env (each at a `done`-map state, e.g. `On Dev`/`On Stg`/`Done`) | `done[min-env]` | the **least-advanced** env state among them (all `On Stg` → `On Stg`; mixed dev+staging → `On Dev`; all production → `Done`) |
+| else any child has **started** (at the `claimed` state, at the `review` state where the project configures one, or shipped to an env while a sibling has not) | `claimed` | the configured `claimed` state |
+| else (children exist, none started) | — | unchanged — parent keeps its non-ready container state |
+
+- **Blocked dominates** — one blocked child surfaces `Blocked` on the parent even while siblings progress. It never says *which* child or *which kind* of hold; resolve and run the shared classifier exactly as `lisa-tracker-sync` specifies, then carry its per-class report — blocking leaf, path, and who must act — into the rollup note. A missing classifier or non-zero exit is a strict **no-write** result: do not save parent state and do not post/update a rollup comment; report the failure, never an all-clear. See `leaf-only-lifecycle` → **Classifying a hold**.
+- **Least-advanced env wins** — the parent reaches an env only when every required child has reached at least that env; it never sits ahead of its laggard child. Native completion (moving the workflow `state` to Done) fires only when the resolved env is the production `Done`, never at `On Dev`/`On Stg`.
+- **"Required" children only** — won't-do / optional (e.g. `Canceled`) children do not hold the parent open.
+- **Recursive** — a Project reaches an env only when its Issues have themselves rolled up to at least that env. Evaluate bottom-up.
+- **Never roll a parent into the `ready` state** — `ready` is leaf-only. Rollup only moves the parent between non-ready container states.
+
+**Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to the single `Done` state, the only env rung is production, and the lifecycle is `ready → claimed → done` with **no** dev/staging promotion hops and no configured `review` rung; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to the intermediate env states.
+
+**Apply the derived state**, naming the derived role — the access layer resolves the configured state for that role and dispatches it. This skill never computes a `stateId` of its own; a role the project never bound is refused there rather than approximated here.
+
+- **Issue parent** → `lisa-linear-access operation: save-issue lifecycle_role: <derived role> [env: <key>]`. An Issue's lane IS a team workflow state, so this is the guarded write.
+- **Project parent** → `lisa-linear-access operation: save-project`. A Linear Project has no team workflow state — it carries its own coarse project status — so there is no `stateId` and no `lifecycle_role` to declare. Map the derived role onto the Project's own status and say in the rollup comment which role produced it. Do not send `lifecycle_role` here; the workflow-state guard governs Issues and has nothing to resolve for a Project. Post an idempotent rollup comment naming the derived state and the child tally. Because the terminal `done` state is itself typed `completed`, a parent rolled to terminal is natively closed by the same write — there is no second closure step. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's state untouched.
+
+## Rules
+
+- Never transition a leaf Issue's workflow `state` from this skill except for the narrowly defined Phase 4b backstop that reopens a leaf auto-closed at an intermediate environment. `--rollup` remains the only other write path (parent derivation, per the `leaf-only-lifecycle` rule); every normal milestone SUGGESTS a transition in its comment and nothing more. The state is the lifecycle lane, so an unscoped write here would move the item in the build queue.
+- Never resolve a role by searching the team's states. Only a name the project configured may be written; a `type`- or position-derived match may inform a read and must never supply a write target (`config-resolution`, R2).
+- Rollup derives a *parent's* workflow state from its children and never rolls a parent into the human-owned ready lane (never `$READY`). It cites the `leaf-only-lifecycle` rule by slug rather than restating the state machine.
+- Never post empty or minimal comments — if a milestone has no meaningful content, skip the post.
+- Do not delete prior milestone comments. They are the audit trail.
+- If `save_comment` fails, retry once. If it fails again, surface the error.
+- Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.

package/plugins/lisa-devin/skills/lisa-linear-to-tracker/SKILL.md

@@ -0,0 +1,454 @@
+---
+name: lisa-linear-to-tracker
+description: >
+  Break down a Linear PRD (a Linear Project) into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json). Use this skill
+  whenever the user shares a Linear project URL and wants it converted into tracker tickets, or asks to
+  "break down this Linear project", "create tickets from a Linear project", "turn this Linear PRD into tickets", or similar. This skill mirrors `lisa-notion-to-tracker` and `lisa-confluence-to-tracker` for projects
+  whose PRDs live in Linear — the workflow, gates, dry-run mode, and validation rules are identical;
+  only the source-of-truth tool surface differs (Linear MCP instead of Notion / Confluence MCP).
+allowed-tools: ["Skill", "Bash"]
+---
+
+# Linear PRD to Tracker Breakdown
+
+Convert a Linear PRD (a Linear **Project**) into a structured ticket hierarchy in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json): Epics > Stories > Sub-tasks.
+Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
+
+This skill is the Linear counterpart of `lisa-notion-to-tracker` and `lisa-confluence-to-tracker`. The three skills share the same phases, gates, dry-run contract, and per-ticket validation logic. Only the PRD-side fetch tools differ. When changing workflow logic, change ALL THREE skills together so the source vendors stay behaviorally identical.
+
+## What "PRD" means in Linear
+
+Linear has no native "PRD" entity. This skill treats a **Linear Project** as the PRD container:
+
+- **Project description** (markdown) is the PRD body — equivalent to a Notion page body or a Confluence page body.
+- **Project documents** (Linear's long-form markdown docs attached to projects, fetched via `list-documents({projectId})` / `get-document`) are treated as additional spec content and merged into the analysis. A multi-document Linear PRD is the analog of a multi-page Confluence PRD.
+- **Project sub-issues** (`list-issues({project})`) act as the candidate set for epics and user stories — the same role child Epic pages play in a Notion/Confluence PRD.
+- **Linear comments live on Issues, not on Projects.** This skill aggregates comments from every issue under the project to capture decisions and engineering notes. Project-level discussion that isn't reflected on an issue is invisible to this skill.
+
+## Modes
+
+This skill supports two modes, controlled by a `dry_run` flag in `$ARGUMENTS`:
+
+- **`dry_run: false`** (default — full mode): run all phases, write tickets via `lisa-tracker-write`, run the preservation gate, report.
+- **`dry_run: true`** (planning + validation only — no writes): run Phases 1, 1.5, 1.6, 2, 3, 4 to plan the hierarchy and draft each ticket spec, then call `lisa-tracker-validate` (with `--spec-only`) on every drafted ticket. Aggregate the per-ticket validator reports into a single dry-run report. **Skip Phase 5 (sub-task creation), Phase 5.5 (preservation gate), and Phase 6 (results report)** — none of those make sense without writes. Return the dry-run report so the caller (e.g. `lisa-linear-prd-intake`) can decide whether to proceed.
+
+Dry-run output format is identical to `lisa-notion-to-tracker`'s and `lisa-confluence-to-tracker`'s. Reuse the same fields, including `prd_anchor` and `prd_section`, the `### Requirement register` section, and the per-node `requirements:` lists. The only difference: Linear has no inline-comment selection-anchor primitive at the project level — `prd_anchor` is the anchor a downstream caller would use to *post a comment on the related sub-issue* (typically the issue identifier, e.g. `LIN-123`, scoped to a section heading). When the failure does not map to any single sub-issue, set `prd_anchor: null` and the caller posts it on the project itself.
+
+```text
+## linear-to-tracker dry-run: <PRD title>
+
+### Requirement register
+- R1 §"<section heading>": "<verbatim requirement text>"
+- R2 §"<section heading>": "<verbatim requirement text>"
+- ...
+
+### Planned hierarchy
+- Epic: <summary>
+  prd_section: "<heading text from the project description / document that produced this epic>"
+  prd_anchor: "<linear issue identifier or null>"
+  requirements: [R1, R2]   # register ids this ticket exists to satisfy; [] only for derived work
+  - Story 1.1: <summary>
+    prd_section: "<heading or user-story line>"
+    prd_anchor: "<linear issue identifier or null>"
+    requirements: [R1]
+    - Sub-task [<repo>]: <summary>
+      prd_section: "<heading or AC bullet>"
+      prd_anchor: "<linear issue identifier or null>"
+      requirements: [R1]
+    - ...
+  - Story 1.2: ...
+
+### Per-ticket validation
+- <ticket-id>: PASS | FAIL — <count> failures
+  prd_section: "<heading text>"
+  prd_anchor: "<linear issue identifier or null>"
+  failures:
+    - gate: <gate-id>
+      category: <category from validator>
+      product_relevant: <true|false>
+      what: <plain-language description from validator>
+      recommendation: <1–3 candidate resolutions from validator>
+
+### Verdict: PASS | FAIL
+### Total failures: <n>
+```
+
+The dry-run mode never writes to JIRA and never writes through any vendor tool directly. It also never modifies the source Linear project, never adds/removes labels, never edits sub-issues, and never posts comments — that is the orchestrating skill's responsibility (`lisa-linear-prd-intake`).
+
+## Hard Rule: All Writes Go Through `lisa-tracker-write`
+
+**Every JIRA ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa-tracker-write` skill. Never call a vendor MCP tool or REST endpoint directly from this skill or from any sub-agent it spawns.**
+
+`lisa-tracker-write` enforces gates this skill does not:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation
+- Explicit issue-link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Single-repo scope check on Bug / Task / Sub-task / Improvement
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+Bypassing `lisa-tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. Atlassian reads in this skill are limited to the tools listed in `allowed-tools` (currently `getJiraIssueRemoteIssueLinks`) for the Phase 5.5 preservation gate. The Linear read tools listed in `allowed-tools` above are PRD-side only and never write.
+
+## Source Requirement Section (shared format)
+
+Every ticket created by this skill — epic, story, and sub-task alike —
+carries a `## Source Requirement` section in its description so anyone can
+answer "why was this done?" without leaving the ticket:
+
+```markdown
+## Source Requirement
+
+- **PRD**: [<PRD title>](<PRD URL>) §"<section heading>"
+- **Requirement (R3)**: "<verbatim requirement text from the PRD>"
+
+This ticket exists to satisfy the quoted requirement. If implementation
+scope drifts from the quoted text, the PRD is the authority — raise the
+conflict rather than silently reinterpreting it.
+```
+
+Rules:
+
+- **Verbatim quotes, never paraphrases.** The quote is what survives later
+  PRD edits, and it must be readable by a non-technical operator.
+- **Multiple requirements** → one `**Requirement (Rn)**` line each.
+- **Derived / cross-cutting work** (no single requirement) uses the
+  supporting form instead:
+  `- **Requirement**: Derived work supporting R3, R7 — no single PRD section.`
+- **All the way down**: sub-tasks carry full quotes, not just a pointer at
+  the parent Story, so a leaf claimed by build-intake in isolation is
+  self-explanatory.
+- JIRA descriptions render the section as `h2. Source Requirement`;
+  GitHub/Linear use the markdown heading. `lisa-tracker-write` and the
+  validators treat the section as mandatory for PRD-sourced tickets.
+
+## Input
+
+A Linear project URL, slug, or ID. The PRD is expected to have:
+- A project with a description containing context, problems, and (optionally) a list of user stories
+- One or more sub-issues that act as candidate epics or user stories
+- Optionally one or more Linear documents attached to the project, with deeper spec content
+- Issue comments capturing engineering notes and product decisions
+
+URL parsing — Linear project URLs come in this shape:
+
+```text
+https://linear.app/<workspace>/project/<slug>-<short-id>
+https://linear.app/<workspace>/project/<slug>-<short-id>/<view>
+```
+
+Extract the trailing `<short-id>` (the alphanumeric segment after the last `-` in the slug). If only a workspace or team URL is provided (no `/project/<slug>-<id>` segment), stop and report — single-PRD mode requires a specific project. The caller wanted `lisa-linear-prd-intake` (batch mode).
+
+## Configuration
+
+This skill reads project configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key) and operational E2E test config from environment variables. See the `config-resolution` rule for the full schema.
+
+### From `.lisa.config.json`
+
+This skill is a **PRD source** (Linear); destination tracker resolution is handled by `lisa-tracker-write` and `lisa-tracker-validate` internally — this skill does NOT read `tracker` directly. The relevant config for the source side:
+
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `linear.workspace` | Linear workspace slug (used for URL synthesis on remote links) | always |
+
+### From environment variables (E2E test config — operational, not tracker)
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `E2E_TEST_PHONE` | Test user phone number for verification plans | `0000000099` |
+| `E2E_TEST_OTP` | Test user OTP code | `555555` |
+| `E2E_TEST_ORG` | Test organization name | `Arsenal` |
+| `E2E_BASE_URL` | Frontend base URL for Playwright tests | `https://dev.example.io/` |
+| `E2E_GRAPHQL_URL` | GraphQL API URL for curl verification | `https://gql.dev.example.io/graphql` |
+
+If env vars are not available, ask the user to provide them explicitly before proceeding. Do not retrieve credentials from repository files or local agent settings.
+
+## Workflow
+
+### Phase 1: Fetch & Analyze the PRD
+
+1. **Resolve the project** via `lisa-linear-access operation: get-project` with the slug or ID, including milestones and resources (`includeMilestones: true`, `includeResources: true`). Capture the project title, description, state, labels, lead, dates, attached documents, attached links.
+2. **Fetch attached Linear documents** via `lisa-linear-access operation: list-documents({projectId})` then `lisa-linear-access operation: get-document` per result. Treat each as additional PRD content. (A Linear PRD with a single rich project description and no attached documents is the common case; multi-document PRDs are valid too.)
+3. **Identify candidate epics and user stories** from project sub-issues via `lisa-linear-access operation: list-issues({project: <id>})`. Capture identifier, title, description, labels, state, parent issue, and `parentId` chain so the issue hierarchy is reproducible.
+4. **Fetch full comments per sub-issue** via `lisa-linear-access operation: list-comments({issueId})` for every issue surfaced in step 3. Walk thread parents/children — comments are threaded via `parentId` references on the comment object.
+5. **Synthesize decisions and blockers** from the project description + every document + every issue comment:
+   - Decisions already confirmed by the team (look for agreement in comment threads)
+   - Open questions that need product/engineering input
+   - Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
+   - Cross-PRD dependencies (references to other Linear projects, documents, or shared infrastructure)
+
+### Phase 1.4: Requirement Register (traceability)
+
+Every ticket this skill creates must be able to answer "why was this done?"
+by pointing at the PRD requirement it satisfies. Build that mapping now,
+while parsing the PRD — it cannot be reliably reconstructed afterwards.
+
+1. **Atomize the PRD into requirements** in document order: goals, user
+   stories, functional and non-functional requirements, acceptance-criteria
+   bullets, and important notes — across the project description, every
+   attached document, and every sub-issue description. Use the same
+   atomization `lisa-prd-ticket-coverage` uses so the two views line up.
+2. **Assign sequential register ids** (`R1`, `R2`, …). Ids are
+   per-generation, not durable — the **verbatim quote is the durable
+   anchor**; if the PRD is edited and re-planned, ids may shift but quotes
+   still identify the requirement.
+3. **Record each entry** as `{ id, verbatim_text, section_heading }`,
+   where `section_heading` is the markdown heading (or the sub-issue
+   identifier) the requirement lives under — the same value used for
+   `prd_anchor`.
+4. **Tag every planned ticket** — epic, story, AND sub-task — with the
+   register ids it exists to satisfy. All the way down: sub-tasks carry
+   their own requirement quotes so a leaf dispatched in isolation is
+   self-explanatory. A ticket that genuinely traces to no single
+   requirement (cross-cutting infrastructure, derived enablement work)
+   gets `requirements: []` and must say which requirements it *supports*
+   in its Source Requirement section instead.
+
+The register feeds three consumers: the `## Source Requirement` section on
+every created ticket (Phases 3–5), the dry-run report (above), and the
+requirement tokens in the PRD back-link (Phase 7).
+
+### Phase 1.45: Requirement Quality Gates (prd-definition-of-ready)
+
+Validate every Phase 1.4 register entry against the `prd-definition-of-ready` rule before
+planning proceeds. Per atom:
+
+- **Singular** — one behavior per entry. An entry welding multiple shall/when clauses together is
+  split in the register (R4 → R4a/R4b) when the split is mechanical and meaning-preserving; when
+  the split would change meaning, it is a product question, not a repair.
+- **Unambiguous** — FAIL on the vagueness lexicon ("as appropriate", "user-friendly", "fast",
+  "handle gracefully", "etc.", "and/or", unbounded "optimize"/"support"): phrasing no test can
+  check. The full lexicon lives in the rule's reference body.
+- **Verifiable** — a fit criterion (the measurable test of satisfaction) is present or
+  mechanically derivable from the text; a requirement no test could check is not admitted as a
+  requirement.
+- **Pattern shape (SHOULD)** — an EARS pattern (ubiquitous / When / While / If-then / Where) or an
+  equivalent single-behavior sentence; conforming shapes decompose into Gherkin mechanically.
+
+Failures here are **requirement-level product clarifications**, not internal errors: report each in
+the dry-run report as a `product-clarity` item quoting the atom verbatim, naming the defect, and
+offering 1–3 candidate rewrites (an EARS-shaped rewrite is the default recommendation). In intake
+flows these route to the PRD's `blocked` role with comments, exactly like ticket-validator
+failures. Mechanical splits and derived fit criteria are repaired in-register and recorded in the
+report — never silently.
+
+### Phase 1.5: Extract Source Artifacts
+
+PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, peer Linear or Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
+
+1. **Scan the project description, every attached document body, every sub-issue description, and every fetched comment thread** for:
+   - URLs to design/prototype tools (Figma, FigJam, Figma Make, Lovable, Framer, Penpot)
+   - URLs to recording/walkthrough tools (Loom, YouTube, Vimeo, Descript)
+   - URLs to collaborative docs (Google Docs/Slides/Sheets, peer Confluence pages, Notion peer pages, peer Linear documents)
+   - URLs to code sandboxes (CodeSandbox, StackBlitz, Replit, GitHub permalinks/gists)
+   - URLs to diagramming tools (Miro, Mural, Excalidraw, Mermaid Live, draw.io, Lucid)
+   - URLs to data/observability tools (Grafana, Datadog, Sentry, Metabase, Looker)
+   - Embedded images and file attachments referenced in the project / documents
+   - Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
+
+2. **Classify each artifact and apply taxonomy rules** by invoking the `lisa-tracker-source-artifacts` skill. That skill is the single source of truth for: domains (`ui-design` / `ux-flow` / `data` / `ops` / `reference`), per-tool classification rules (Figma `/proto/` vs design, Lovable as `ux-flow`, Loom, screenshots), and coverage smells. Do not restate the rules here — invoke the skill so any drift in the rules propagates uniformly.
+
+3. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable. The `source_page` lets you trace each reference back to where it appeared (project description vs a specific document title vs a specific sub-issue comment).
+
+4. **Surface coverage smells** as defined in `lisa-tracker-source-artifacts` §5. Record any detected smells on the epic.
+
+### Phase 1.6: Source Precedence & Conflict Resolution
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa-tracker-source-artifacts` §3 and §4. Apply them during ticket synthesis: every conflict between artifacts must be recorded under `## Open Questions` on the affected ticket, never silently reconciled.
+
+The existing-component reuse expectation is defined in `lisa-tracker-source-artifacts` §7. Encode it on every UI-touching story.
+
+### Phase 2: Codebase + Live Product Research
+
+Identical to `lisa-notion-to-tracker` Phase 2 and `lisa-confluence-to-tracker` Phase 2. Two complementary inputs ground PRD analysis: the **code** (what's there to reuse / extend) and the **live product** (what users see today). Skipping either produces tickets that misjudge the change.
+
+**2a. Codebase research.** If the session doesn't already have codebase context, explore the repos to understand what exists. Use Explore agents for repos not yet examined.
+
+**2b. Live product walkthrough.** If the PRD touches existing user-facing surfaces, invoke the `lisa-product-walkthrough` skill against `E2E_BASE_URL` using the test user from config.
+
+Skip the *walkthrough* only when the work has no user-visible surface, or affects a screen that does not yet exist in dev/prod — and when you skip it, run 2c instead. Skipping 2b never means authoring the ticket with no live-state grounding.
+
+**2c. Deployed-state readback — required whenever 2b does not apply.** Per the `blocker-containment`-style shared-slug precedent, cite the `deployed-state-readback` rule for the full contract; do not restate its routing table here.
+
+2b is waived for work with no user-visible surface. That waiver is about the **observation method**, not about whether to observe: backend, infrastructure, CI-config and dependency work all have live state, it is simply not visible through a browser. So the skip selects a **different probe**, never no probe — describe the deployed resource, call the deployed endpoint, read the configuration the last pipeline run used, read the *installed* artifact. For each thing the candidate tickets would create or change, confirm it is genuinely **absent from the deployed environment** before authoring a ticket for it, and record what was probed and what came back.
+
+**Git ancestry, a merge check and `cdk synth` are never deployment evidence** — a discarded pipeline execution leaves a commit merged and unshipped, and all three still report "present". **An unanswerable probe is not a "no"**: when the state cannot be read back, record that the check could not be performed rather than defaulting to absent.
+
+
+Walkthrough findings are surfaced back to product via the orchestrating intake skill (`lisa-linear-prd-intake`), which posts them on the project itself. This skill itself does NOT post to Linear — it only reads. The walkthrough section is also inherited onto the resulting epic / stories under a `## Current Product` subsection in the JIRA description.
+
+### Phase 3: Create Epics
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa-tracker-write` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `lisa-tracker-validate --spec-only`. Record the drafted spec (including a placeholder epic key like `DRY-RUN-EPIC-1`) for Phase 4 to use as parent references. In `dry_run: false` mode (default), proceed as described below.
+
+For each epic identified in Phase 1, **invoke the `lisa-tracker-write` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
+
+- `project_key`: resolved by `lisa-tracker-write` from `.lisa.config.json`
+- `issue_type`: `Epic`
+- `prd_source`: the originating PRD URL — mandatory for every ticket this skill creates; it arms the validator's S16 traceability gate
+- `summary`: epic title from the PRD
+- `description_body`: a draft of the 3-audience description containing:
+  - A **Source Requirement** section (see the shared format above) citing the Linear project URL, section heading, and the verbatim text of every register requirement (`R-id`) this epic exists to satisfy
+  - **Context / Business Value**: epic summary from the PRD, originating Linear project URL, business outcome
+  - **Technical Approach**: cross-cutting integration points and constraints surfaced in Phase 2 codebase research
+  - List of user stories the epic contains
+  - Key decisions from comments (with attribution)
+  - Blockers and open questions
+  - Dependencies on other epics or PRDs
+  - A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
+- `artifacts`: the full Phase 1.5 artifact list — every artifact, regardless of domain. The epic is the canonical hub. No filtering at the epic level.
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa-tracker-write` must not be passed the build-ready role for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready role is applied only in Phase 5.
+
+Capture the returned epic key — Phase 4 needs it as the parent for stories.
+
+### Phase 4: Create Stories
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa-tracker-write` in this phase. Instead, draft each story spec and validate it with `lisa-tracker-validate --spec-only`. Use placeholder keys (e.g. `DRY-RUN-STORY-1.1`) for any downstream references. In `dry_run: false` mode (default), proceed as described below.
+
+For each Epic, plan two kinds of stories:
+- **One "X.0 Setup" story** for data model and infrastructure prerequisites
+- **One story per user story** from the PRD (numbered to match the PRD's structure or the source Linear sub-issues)
+
+**Story naming convention**: Prefix the summary with a short code derived from the PRD title (e.g., `[CU-1.1]` for "Contract Upload").
+
+For each story, **invoke `lisa-tracker-write`** with:
+
+- `project_key`: resolved by `lisa-tracker-write` from `.lisa.config.json`
+- `issue_type`: `Story`
+- `prd_source`: the originating PRD URL — mandatory for every ticket this skill creates; it arms the validator's S16 traceability gate
+- `epic_parent`: the Epic key captured in Phase 3 (mandatory)
+- `summary`: prefixed per the naming convention above
+- `description_body`: 3-audience description as in `lisa-notion-to-tracker` Phase 4, including as its first element a **Source Requirement** section (shared format above) quoting the register requirement(s) this story satisfies
+- `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below
+
+| Story type | Inherits domains |
+|------------|------------------|
+| Frontend / UI | `ui-design`, `ux-flow`, `reference` |
+| Backend / API / data model | `data`, `reference` |
+| Infrastructure | `ops`, `reference` |
+| Mixed / setup ("X.0") | All domains |
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass the build-ready role to `lisa-tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready role is applied only in Phase 5.
+
+Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
+
+### Phase 5: Create Sub-tasks
+
+**Auto-split cross-repo work before delegation.** For each candidate sub-task, apply `lisa-task-decomposition` step 1.5: if the work touches more than one repo, split it into one sub-task per repo under the same parent Story (e.g., `[backend-api] Add field` + `[mobile-app] Display field`), and encode the producer-before-consumer ordering via dependencies. Work units that may span repos (Epic, Story, Spike) stay as planned; work units that must be single-repo (Bug, Task, Sub-task, Improvement) are split now. Splitting is this skill's responsibility — the validator's S10 gate is `product_relevant: false` because cross-repo failures are decomposition errors caught here, not product questions sent back to the PRD.
+
+**S10 hard gate repair loop.** Dry-run validation is not advisory. Before any Phase 5 write, every planned leaf spec MUST pass `lisa-tracker-validate --spec-only` for S10 Single-repo scope. If any Bug / Task / Sub-task / Improvement fails S10 (missing `Repository`, more than one repo, or cross-repo AC), stop the write path, auto-split or restamp the spec using `lisa-task-decomposition` step 1.5, add the repo bracket and `## Repository` / `h2. Repository` section, then re-run `lisa-tracker-validate --spec-only`. If S10 still fails after repair, abort the ticket write and record an internal Error in the dry-run report; do not create the ticket, do not bypass with direct vendor writes, and do not surface the `product_relevant: false` failure as a product clarification.
+
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa-tracker-write` for each sub-task — no agent may call `createJiraIssue` directly.**
+
+Each sub-task MUST:
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]` and in the description's `## Repository` / `h2. Repository` section
+2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
+3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready role. `lisa-tracker-write` applies the build-ready role here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. **Pass `build_ready: true` explicitly on every Sub-task create** — per the `ready-role-filing` rule an omitted `build_ready` is NOT build-ready on any tracker, so a decomposition that relies on a vendor default silently produces a queue nothing ever claims. Apply the build-ready role to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+
+Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task.
+
+### Phase 5.5: Artifact Preservation Gate (mandatory)
+
+Run the preservation gate defined in `lisa-tracker-source-artifacts` §8 against the artifacts extracted in Phase 1.5 and the tickets just created. Do NOT restate or modify the gate logic here — invoke the rules from `lisa-tracker-source-artifacts`.
+
+To run the gate, this skill must:
+
+1. Pull the remote links of every epic and story created in this run via `lisa-tracker-read (vendor-neutral; dispatches to jira-read-ticket or github-read-issue)`.
+2. Apply the §8 preservation matrix and verdict rules.
+3. If the gate fails: list each dropped/misrouted artifact and either re-attach via `lisa-tracker-write` (UPDATE mode) or stop and ask the human.
+4. If the gate passes: print the matrix compactly and proceed to Phase 6.
+
+This gate is not optional.
+
+### Phase 6: Report Results
+
+After all tickets are created, present a summary table to the user:
+- All Epics with keys and URLs
+- All Stories grouped by Epic
+- All Sub-tasks grouped by Story with repo tags
+- **Requirement coverage** — one row per Phase 1.4 register entry (`R-id`, quote excerpt, tickets that declare it); requirements with zero tickets are a gap to resolve before reporting success
+- Repo distribution
+- **Artifact Preservation Matrix**
+- Blockers list with recommendations and alternatives
+- Cross-PRD dependencies
+
+### Phase 7: PRD Back-link
+
+> **Mode guard**: In `dry_run: true` mode, skip this phase entirely — no tickets exist to link.
+
+After Phase 6, invoke the `lisa-prd-backlink` skill to write a `## Tickets` section back into the source Linear project (or its description). The section becomes the canonical anchor for the **Debrief** flow once the initiative ships.
+
+Invoke `lisa-prd-backlink` with:
+
+- `source_type: "linear"`
+- `source_ref`: the original Linear project URL
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key, requirements }` — `requirements` is the list of Phase 1.4 register ids the ticket satisfies (empty for derived work)
+- `requirement_register`: the Phase 1.4 register (`{ id, verbatim_text, section_heading }` entries), so the back-link section can render the requirement → tickets view
+
+If `lisa-prd-backlink` fails (permission denied, Linear unreachable), surface the error in the Phase 6 report rather than aborting — the tickets are already created. Recommend the user re-run `lisa-prd-backlink` standalone once the source is reachable.
+
+## Handling Ambiguities and Blockers
+
+When you encounter something the PRD + comments + codebase can't resolve:
+
+1. **Don't guess** — mark the ticket with a BLOCKER section
+2. **Include your recommendation** with rationale
+3. **List 2-3 alternatives** so the user/product can choose
+4. **State what's needed to unblock**
+
+## Agent Prompt Template for Sub-task Creation
+
+When delegating to agents, provide this context. **The "MUST invoke jira-write-ticket" instruction is load-bearing — do not edit it out when adapting this template.**
+
+```text
+Create JIRA sub-tasks in the [PROJECT] project at [CLOUD_ID].
+
+CRITICAL: For each sub-task, invoke the `lisa-tracker-write` skill via the Skill tool.
+Do NOT call a vendor MCP tool directly. The `lisa-tracker-write` skill
+enforces required quality gates (Gherkin acceptance criteria, 3-audience description,
+single-repo scope, sign-in/environment fields, post-create verification). Bypassing it
+produces broken tickets that downstream skills (triage, journey, evidence) cannot use.
+
+For each sub-task, invoke `lisa-tracker-write` with:
+- issue_type: "Sub-task"
+- build_ready: true  # explicit per `ready-role-filing`; omitted is NOT build-ready on any tracker
+- prd_source: [the originating PRD URL — mandatory; arms the S16 traceability gate]
+- parent: the parent story key
+- project_key: [PROJECT]
+- summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo, plus `h2. Source Requirement` quoting the PRD requirement(s) this sub-task satisfies VERBATIM with the PRD link and register id(s) — [paste the exact requirement text and R-ids for each sub-task from the requirement register; do not let the agent paraphrase]
+- gherkin_acceptance_criteria: derived from the story's functional requirements
+- sign_in_account: [test user credentials from config — name + role + how to obtain]
+- target_environment: "dev"
+- empirical_verification_plan: real user-like verification (curl + auth token,
+  Playwright browser flow, CLI check after deploy) using the test credentials.
+  NOT unit tests, linting, or typechecking.
+
+Each sub-task must:
+1. Be scoped to ONE repo only — repo named in brackets in the summary and in `h2. Repository`
+2. Include the Empirical Verification Plan in the description
+3. Be created via `lisa-tracker-write`, not via direct MCP calls
+
+If `lisa-tracker-write` rejects a sub-task, fix the input and re-invoke. Do NOT fall back
+to a direct `createJiraIssue` call to bypass the gate.
+
+Test user info: [credentials from config]
+
+[Then list all sub-tasks grouped by parent story with details]
+```
+
+## Cross-PRD Shared Infrastructure
+
+Track tickets that are shared across PRDs to avoid duplication. When a sub-task overlaps with an existing ticket, reference it instead of creating a duplicate. Search JIRA for existing tickets in the project before creating new ones for shared infrastructure.
+
+## Linear-specific notes
+
+- **Project description format**: Linear project descriptions are markdown. Treat headings (`#`, `##`, `###`) as section markers for `prd_section`.
+- **Document parents**: Linear documents are attached to either a Project or an Issue (exactly one). For PRD intake, only documents attached to the project being processed are in scope. Documents attached to a child Issue are picked up via that issue's content surface.
+- **Comment threading**: Linear comments are threaded via a `parentId` field on each comment. When fetching comments via `list_comments`, capture the full reply tree — replies often hold the actual decision while the root comment was the question.
+- **No inline selection anchors on a project**: Linear has no equivalent of a Notion selection snippet or a Confluence inline comment, so an unanchored failure has no in-text location to attach to. It still lands on the project — `lisa-linear-access operation: save-comment project_id:<ID>` posts a project-level comment — just as a whole-page comment rather than an inline one. This skill does not write to Linear at all; it only reads.
+- **Issue identifiers** (`LIN-123`, `ENG-456`, etc.) are the closest analog to a Confluence inline-comment anchor. When dry-run output sets `prd_anchor` to an issue identifier, the caller knows it can post a clarifying-question comment on that specific issue if it wants block-level anchoring.