@codyswann/lisa 2.10.0 → 2.11.0

package/plugins/src/base/skills/linear-validate-issue/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: linear-validate-issue
+description: "Validates a proposed Linear work item spec (Project, Issue, or sub-Issue) — or an existing Linear item — against the organizational quality gates without writing anything. Returns a structured PASS/FAIL report per gate with concrete remediation. Single source of truth for what makes a valid Linear item — both the write path (linear-write-issue runs it pre-write) and the dry-run path (linear-to-tracker runs it during PRD intake) call this skill so the bar can never drift."
+allowed-tools: ["Bash", "mcp__linear-server__list_teams", "mcp__linear-server__get_team", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+---
+
+# Validate Linear Work Item: $ARGUMENTS
+
+Run all organizational quality gates against a Linear work item spec OR an existing Linear item. **This skill is read-only — it never writes to Linear.** The output is a structured report consumed by callers (`lisa:linear-write-issue` for pre-write gating, `lisa:linear-to-tracker` for PRD dry-run, `lisa:linear-verify` for post-write checks).
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override) for any feasibility lookups.
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+1. **An existing Linear identifier** (e.g. `ENG-123` for an Issue, or `<workspace>/project/<slug>-<id>` for a Project): fetch and validate the live state.
+2. **A proposed item spec** (YAML block, see schema below): validate as-is without touching Linear.
+
+### Spec schema
+
+```yaml
+issue_type: Story          # Epic | Story | Task | Bug | Spike | Sub-task | Improvement
+team_key: ENG
+summary: "[CU-1.2] Upload contract PDF from settings"
+priority: 3                # Linear native: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low
+parent_project_id: <uuid>  # Required for Story/Task/Improvement when in Epic context
+parent_issue_id: <uuid>    # Required for Sub-task (the Story Issue)
+description: |             # Full description text — every required section
+  ## Context / Business Value
+  ...
+
+  ## Technical Approach
+  ...
+
+  ## Acceptance Criteria
+  1. Given <precondition>
+     When <action>
+     Then <observable outcome>
+
+  ## Out of Scope
+  ...
+
+  ## Target Backend Environment
+  dev
+
+  ## Sign-in Required
+  Account: ...
+
+  ## Repository
+  backend-api
+
+  ## Validation Journey
+  ...
+
+# Behavioral flags — caller asserts these so the validator picks the right gates
+runtime_behavior_change: true     # → requires Target Backend Environment + Validation Journey
+authenticated_surface: true       # → requires Sign-in Required
+artifacts_attached: true          # → requires Source Precedence section
+relations: [{ id: "ENG-99", type: "blocked_by" }]   # known issue relations (may be empty)
+remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
+```
+
+If the caller passes only an identifier, fetch the item via `mcp__linear-server__get_issue` (Issue) or `mcp__linear-server__get_project` (Project), derive the same fields from the fetched data, then run gates.
+
+## Gates
+
+Gates are grouped into **Specification** (spec-only checks, no Linear lookups) and **Feasibility** (requires Linear lookups). The dry-run path may opt to run Specification gates only; the write path runs both.
+
+Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Categories drive how downstream callers (notably `lisa:linear-prd-intake`) translate failures into product-facing comments; `product_relevant=false` failures indicate internal data-quality problems the agent should fix itself rather than ask product to clarify.
+
+| Gate | Category | Product-relevant |
+|------|----------|------------------|
+| S1 Required core fields | `structural` | false |
+| S2 Summary format | `structural` | false |
+| S3 Description three audiences | `product-clarity` | true |
+| S4 Acceptance criteria in Gherkin | `acceptance-criteria` | true |
+| S5 Bug-specific content | `product-clarity` | true |
+| S6 Spike-specific content | `scope` | true |
+| S7 Project parent declared | `structural` | false |
+| S8 Target Backend Environment | `technical` | false |
+| S9 Sign-in Required | `technical` | false |
+| S10 Single-repo scope | `scope` | true |
+| S11 Validation Journey | `acceptance-criteria` | true |
+| S12 Source Precedence | `design-ux` | true |
+| S13 Relationship Search | `dependency` | true |
+| F1 Issue type valid in team | `structural` | false |
+| F2 Project parent exists and is in same team | `structural` | false |
+| F3 Linked items exist | `structural` | false |
+| F4 Required labels exist (or can be created) | `structural` | false |
+
+Category values are the same fixed set as `lisa:jira-validate-ticket`:
+
+- `product-clarity` — feature behavior or user intent unclear in the PRD
+- `acceptance-criteria` — pass/fail conditions missing or ambiguous
+- `design-ux` — visual or interaction spec missing
+- `scope` — boundary unclear, items overlap, split needed
+- `dependency` — blocked by another team / system / decision
+- `data` — data source / shape / volume unspecified
+- `technical` — engineering decision required
+- `structural` — internal data-quality problem the agent must fix itself, not surface to product
+
+### Specification Gates
+
+#### S1 — Required core fields
+
+`team_key`, `issue_type`, `summary`, `priority`, `description` must all be present and non-empty.
+
+#### S2 — Summary format
+
+- Single line, ≤ 100 characters
+- Imperative voice ("Add X", "Fix Y", not "Adding X" or "X is broken")
+- Bug / Task / Sub-task summaries SHOULD start with a `[repo-name]` prefix when the project convention uses one
+
+#### S3 — Description has all three audiences
+
+Description text must include all of these sections (case-insensitive `##` markdown headings):
+- `Context / Business Value` — stakeholder-facing
+- `Technical Approach` — developer-facing
+- `Acceptance Criteria` — coding-assistant-facing
+- `Out of Scope` — explicit non-coverage list
+
+Missing any → FAIL with name of missing section.
+
+#### S4 — Acceptance criteria in Gherkin
+
+Applies when `issue_type ∈ {Story, Task, Bug, Sub-task, Improvement}`.
+
+The `Acceptance Criteria` section must contain at least one criterion in `Given / When / Then` form. Reject prose-only criteria, "should work" language, or numbered lists without Given/When/Then verbs.
+
+#### S5 — Bug-specific content
+
+When `issue_type = Bug`, description must additionally include:
+- Reproduction steps
+- Expected vs. actual behavior
+- Environment where reproduced
+
+#### S6 — Spike-specific content
+
+When `issue_type = Spike`, description must include:
+- The question being answered
+- Definition of done (decision doc / prototype / findings deliverable)
+
+#### S7 — Project parent declared
+
+When `issue_type ∈ {Story, Task, Improvement}` AND the item is part of an Epic context, `parent_project_id` must be set. When `issue_type = Sub-task`, `parent_issue_id` must be set. (Validity of the IDs is checked in feasibility gates.)
+
+For top-level Bug / Spike not under an Epic, this gate is N/A.
+
+#### S8 — Target Backend Environment
+
+When `runtime_behavior_change = true`, description must contain `## Target Backend Environment` with one of `dev`, `staging`, `prod`. Skipped for doc-only / config-only / type-only / Epic.
+
+#### S9 — Sign-in Required
+
+When `authenticated_surface = true`, description must contain `## Sign-in Required` naming the account/role and credential source.
+
+If the spec doesn't set `authenticated_surface`, infer it: scan the description and AC for sign-in / login / "as a {role} user" / authenticated route signals. If signals present and no `Sign-in Required` section: FAIL.
+
+#### S10 — Repository section, single-repo scope
+
+When `issue_type ∈ {Bug, Task, Sub-task}`, description must contain `## Repository` naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation to split.
+
+Story / Epic / Spike / Improvement: skipped (may span repos).
+
+#### S11 — Validation Journey present
+
+When `runtime_behavior_change = true`, description must contain `## Validation Journey`. Skipped for doc-only / config-only / type-only / Epic.
+
+The caller controls strictness via `journey_followup: "auto"` or `"none"`:
+- `auto` (default): missing section returns `FAIL` with remediation `"Invoke lisa:linear-add-journey to append the section after create"`. The write path auto-fixes; dry-run path leaves it as a FAIL the caller must address.
+- `none`: missing section is a `FAIL` the caller will not auto-fix.
+
+#### S12 — Source Precedence (when artifacts attached)
+
+When `artifacts_attached = true`, description must include source-precedence guidance covering: business rules → PRD body, visual treatment → mocks, flow → prototypes, API/data → data artifacts. Cross-axis conflicts surfaced under `## Open Questions`.
+
+Accept either placement:
+- A dedicated `## Source Precedence` subsection, OR
+- A "Source Precedence" / "authoritative source" paragraph under `Technical Approach` covering the four axes.
+
+Detect by scanning for the phrase `Source Precedence` (case-insensitive) anywhere in the description AND verifying the four axes are each named. Missing the phrase OR any axis: FAIL with remediation naming the missing axes.
+
+#### S13 — Relationship Search documented
+
+The item must EITHER have at least one entry in `relations`, OR the description / a comment must contain a `## Relationship Search` block listing the git history queries and Linear MCP queries that were run with their outcomes.
+
+An item with zero relations and no documented search: FAIL.
+
+### Feasibility Gates (require Linear lookups; skip in dry-run if requested)
+
+#### F1 — Issue type valid in team
+
+For Issue types: confirm the team supports the issue type via `mcp__linear-server__get_team`. Linear issue types are typically per-team; check that the requested type exists.
+
+For Epic (Project): confirm the team allows projects.
+
+#### F2 — Project parent exists and is in same team
+
+When `parent_project_id` is set: fetch via `mcp__linear-server__get_project`, confirm it exists and belongs to the configured team.
+
+When `parent_issue_id` is set (Sub-task case): fetch via `mcp__linear-server__get_issue`, confirm the issue is non-Sub-task and in the same team / project.
+
+#### F3 — Linked items exist
+
+For each entry in `relations`, call `mcp__linear-server__get_issue` to confirm the identifier resolves. Flag broken identifiers.
+
+#### F4 — Required labels exist (or can be created)
+
+For each label referenced (`status:*`, `component:<name>`, `prd-*`), confirm via `mcp__linear-server__list_issue_labels` (or `list_project_labels` for Project labels) that it exists OR is creatable. Linear labels are team-scoped or workspace-scoped; flag if the requested scope is wrong.
+
+## Execution
+
+1. Parse `$ARGUMENTS`. If it's an identifier, fetch the item and derive the spec from the fetched fields. Otherwise parse the YAML spec.
+2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})` if any feasibility gate will run.
+3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
+4. Unless the caller passed `--spec-only` (dry-run), run every Feasibility gate. Collect results.
+5. Emit the report below.
+
+## Output
+
+Output is a single fenced text block. Callers parse it; do not add free-form prose around it.
+
+```text
+## linear-validate-issue: <IDENTIFIER-or-SUMMARY>
+
+### Specification Gates
+- [PASS|FAIL|N/A] S1 Required core fields — <one-line reason>
+- [PASS|FAIL|N/A] S2 Summary format — <one-line reason>
+- [PASS|FAIL|N/A] S3 Description three audiences — <one-line reason>
+- [PASS|FAIL|N/A] S4 Acceptance criteria in Gherkin — <one-line reason>
+- [PASS|FAIL|N/A] S5 Bug-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S6 Spike-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S7 Project parent declared — <one-line reason>
+- [PASS|FAIL|N/A] S8 Target Backend Environment — <one-line reason>
+- [PASS|FAIL|N/A] S9 Sign-in Required — <one-line reason>
+- [PASS|FAIL|N/A] S10 Single-repo scope — <one-line reason>
+- [PASS|FAIL|N/A] S11 Validation Journey — <one-line reason>
+- [PASS|FAIL|N/A] S12 Source Precedence — <one-line reason>
+- [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
+
+### Feasibility Gates  (omit when --spec-only)
+- [PASS|FAIL|N/A] F1 Issue type valid in team — <one-line reason>
+- [PASS|FAIL|N/A] F2 Project parent exists and is in same team — <one-line reason>
+- [PASS|FAIL|N/A] F3 Linked items exist — <one-line reason>
+- [PASS|FAIL|N/A] F4 Required labels exist (or can be created) — <one-line reason>
+
+### Verdict: PASS | FAIL
+### Failures: <count>
+### Failure details
+- gate: <gate-id>
+  category: <category>
+  product_relevant: <true|false>
+  what: <plain-language description, no gate-IDs, no Linear jargon>
+  recommendation: <1–3 concrete options>
+- gate: ...
+```
+
+The verdict is `PASS` if and only if every applicable gate is `PASS`. Any `FAIL` makes the verdict `FAIL`. `N/A` does not affect the verdict.
+
+## Rules
+
+- Never write to Linear. The `allowed-tools` list intentionally excludes any `save_*` tool.
+- Never auto-fix the spec. This skill reports gaps; callers decide what to do.
+- Never silently skip a gate. If a gate genuinely doesn't apply, return `N/A` with the reason.
+- The `what` and `recommendation` fields must be concrete and product-readable — the dry-run path turns each failure into a Linear comment. Vague guidance is useless; always give 1–3 candidate resolutions.
+- Never emit a category outside the fixed set.
+- `product_relevant` is determined by the gate, not by the failure context.

package/plugins/src/base/skills/linear-verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: linear-verify
+description: "Verifies a Linear work item meets organizational standards by fetching the live item and running it through lisa:linear-validate-issue. Catches anything dropped or reformatted on write — same gates as the pre-write check, but applied to what Linear actually stored. Read-only."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__get_project", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+---
+
+# Verify Linear Work Item: $ARGUMENTS
+
+Fetch the live Linear work item and run it through `lisa:linear-validate-issue`. This catches any field that was dropped or reformatted between the pre-write spec and what Linear stored.
+
+This skill is the destination of the `lisa:tracker-verify` shim when `tracker = "linear"`. Read-only — never writes.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Input
+
+`$ARGUMENTS` is a Linear identifier:
+- An Issue identifier (e.g. `ENG-123`)
+- A Project URL or slug (e.g. `https://linear.app/<workspace>/project/<slug>-<id>`)
+
+If `$ARGUMENTS` is not parseable, stop and report.
+
+## Phase 1 — Resolve Context
+
+1. Read `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
+3. Determine entity type from the identifier shape:
+   - `<TEAM>-<n>` → Issue
+   - URL containing `/project/<slug>-<id>` → Project
+
+## Phase 2 — Fetch Live State
+
+Call `mcp__linear-server__get_issue` (for Issues) or `mcp__linear-server__get_project` (for Projects). Capture every field, label, relation, comment, milestone, and project membership.
+
+## Phase 3 — Delegate to Validator
+
+Pass the fetched item to `lisa:linear-validate-issue` (in identifier mode — let it derive the spec from the live state). The validator runs both Specification AND Feasibility gates against what Linear actually stored.
+
+## Phase 4 — Report
+
+Return the validator's report verbatim — same structured format as `lisa:linear-validate-issue`. Callers (especially `lisa:linear-write-issue` Phase 7) parse the verdict to decide whether to declare success.
+
+If the verdict is `FAIL`, the caller should fix the item and re-run verify. Never declare success on a `FAIL` verdict.
+
+## Rules
+
+- Never write to Linear. Read-only.
+- Never short-circuit the validator. Always run the full gate set.
+- If `get_issue` / `get_project` returns an access error, surface it and exit — don't pretend the item is fine.

package/plugins/src/base/skills/linear-write-issue/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: linear-write-issue
+description: "Creates or updates a Linear work item — Project (Epic), Issue (Story), or sub-Issue (Sub-task) — following organizational best practices. Polymorphic: dispatches internally on issue_type to save_project (Epic) or save_issue (Story / Sub-task). Enforces description quality (three audiences), Gherkin acceptance criteria, project-as-parent for Stories, parentId for Sub-tasks, explicit relationship discovery (blocks / is blocked by / relates to / duplicates), labels, components-as-labels, project milestones for fix versions, native priority and estimate fields, and Validation Journey. Rejects thin items — use this skill any time a Linear work item is created or significantly edited."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_team", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment"]
+---
+
+# Write Linear Work Item: $ARGUMENTS
+
+Create or update a Linear work item — Project (for Epics), Issue (for Stories), or sub-Issue (for Sub-tasks) — with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin items are rejected.
+
+Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
+
+## Configuration
+
+This skill reads configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key). Required keys:
+
+- `linear.workspace` — Linear workspace slug
+- `linear.teamKey` — Linear team key (e.g. `ENG`); the team owns the destination items
+
+If either is missing, stop and report — never invent values.
+
+## Polymorphic dispatch
+
+Linear's data model maps Epic / Story / Sub-task to **different entity types**. This skill dispatches on `issue_type`:
+
+| `issue_type` | Linear entity | MCP write tool | Parent field |
+|--------------|---------------|----------------|--------------|
+| `Epic` | **Project** | `mcp__linear-server__save_project` | (none — Projects are top-level within a team) |
+| `Story` / `Task` / `Improvement` | **Issue** | `mcp__linear-server__save_issue` | `projectId` (the Epic Project) |
+| `Sub-task` | **sub-Issue** | `mcp__linear-server__save_issue` | `parentId` (the Story Issue) |
+| `Bug` | **Issue** | `mcp__linear-server__save_issue` | `projectId` if part of an Epic; else top-level |
+| `Spike` | **Issue** | `mcp__linear-server__save_issue` | `projectId` if part of an Epic; else top-level |
+
+Status workflow uses **labels** (`status:ready`, `status:in-progress`, `status:on-dev`, `status:done`) for portability across teams — Linear's per-team workflow state names vary, but labels are workspace-scoped and stable. Native Linear `state` is set to the team's default `Todo` state on create.
+
+## Phase 1 — Resolve Intent
+
+Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE:
+
+- **CREATE**: no existing identifier provided.
+- **UPDATE**: identifier provided (`<TEAM>-<n>` for Issue, project slug + short-id for Project) — call `/linear-read-issue <ref>` first to load the full current state. Never overwrite without reading.
+
+Resolve the team ID for `linear.teamKey` via `mcp__linear-server__list_teams({query: <teamKey>})`. Cache it.
+
+## Phase 2 — Gather Required Inputs
+
+Required fields (stop and ask if missing — never invent values):
+
+| Field | Required For | Notes |
+|-------|--------------|-------|
+| `team_key` | CREATE | From `linear.teamKey` config; required for both Project and Issue creation |
+| `issue_type` | CREATE | One of: Epic, Story, Task, Bug, Spike, Sub-task, Improvement |
+| Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
+| Description | CREATE, UPDATE | Multi-section markdown — see Phase 3 |
+| Project parent (for Story / Task / Bug / Spike / Improvement when part of an Epic) | non-Epic, non-Sub-task in Epic context | Linear Project ID — the Epic |
+| Sub-task parent | Sub-task | Linear Issue ID — the Story |
+| Priority | CREATE | Native Linear priority: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 |
+| Validation Journey | Runtime-behavior changes | Delegate to `/linear-add-journey` |
+| Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only items. |
+| Sign-in account / credentials | Items that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description. Omit when sign-in is not required. |
+| Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
+
+Optional but recommended: assignee, estimate (story points), labels, project milestone (fix-version equivalent), cycle.
+
+## Phase 3 — Description Quality
+
+Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, use `##` instead). The description MUST address three audiences. Reject and rewrite if any are missing.
+
+```markdown
+## Context / Business Value
+[Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
+ Link to the originating Slack thread, Notion doc, incident, or customer report.]
+
+## Technical Approach
+[Developer-facing. Integration points, impacted modules, data model implications,
+ relevant tradeoffs. Not a full design doc — a pointer for someone picking it up.]
+
+## Acceptance Criteria
+1. Given <precondition>
+   When <action>
+   Then <observable outcome>
+2. Given <precondition>
+   When <action>
+   Then <observable outcome>
+
+## Out of Scope
+[Explicit list of what this item does NOT cover. Forces scope discipline.]
+
+## Target Backend Environment
+[Required when the item changes runtime behavior. One of: dev / staging / prod.
+ Skip section entirely for doc-only, config-only, or type-only items.]
+
+## Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role to sign in as, where to get the credentials
+ (1Password item name, env var, seeded fixture), and any MFA/SSO notes.
+ Omit the section entirely when sign-in is not required.]
+
+## Repository
+[Required for Bug / Task / Sub-task. Name the single repo this item covers.
+ If the work spans repos, this issue type is wrong — split into per-repo
+ Tasks/Sub-tasks under a parent Story or Epic.]
+
+## Validation Journey
+[Delegate to /linear-add-journey if the item changes runtime behavior.
+ Skip only for doc-only, config-only, or type-only items.]
+```
+
+Rules:
+- Every acceptance criterion uses Given/When/Then. No vague "should work" language.
+- Every criterion is independently verifiable (UI, API, data, or performance check).
+- If the item is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
+- If the item is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings).
+- If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials.
+
+## Phase 4 — Relationship Discovery (Mandatory)
+
+Before creating or updating, find candidate relationships. Do NOT skip — this is the step agents most often omit.
+
+### 4a. Project Parent (Epic-equivalent)
+
+If the item is **not an Epic** and **not a top-level Bug/Spike**, it MUST have a parent context:
+
+- **Story / Task / Improvement** → must have a `projectId` (the Epic Project) set.
+- **Sub-task** → must have a `parentId` (the Story Issue) set.
+
+If the parent is explicitly provided, use it. Otherwise:
+
+1. Search active Projects in the team:
+   ```text
+   mcp__linear-server__list_projects({team: <teamKey>, state: ["backlog", "planned", "started"]})
+   ```
+   Match on keywords from the summary and description.
+2. If no matching Project exists, stop and ask the human to create or pick one. Do NOT orphan the item.
+
+### 4b. Related Items
+
+Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the item.
+
+**Search 1: local git history** (catches PRs / commits that touched the same area but were never linked):
+
+```bash
+git log --all --oneline --grep="<keyword>"
+git log --all --oneline -- <path-or-glob>
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling item worth linking.
+
+**Search 2: Linear MCP** (catches open and recently-closed items):
+
+```text
+# Open items in the same Project
+mcp__linear-server__list_issues({project: <projectId>, state_type: ["unstarted", "started"]})
+
+# Open items with overlapping keywords (workspace-wide)
+mcp__linear-server__list_issues({query: "<keyword>", state_type: ["unstarted", "started"]})
+
+# Items with shared labels
+mcp__linear-server__list_issues({label: "<label>", updatedAt: ">-30d"})
+
+# Recently closed items in the same Project
+mcp__linear-server__list_issues({project: <projectId>, state_type: ["completed", "canceled"], updatedAt: ">-30d"})
+```
+
+**Record the outcome.** Add a `## Relationship Search` subsection (or a comment if updating) listing the queries you ran and what they returned. If the searches yielded nothing, write that explicitly — "Searched git history for `<keywords>` and Linear for project=`X`, label=`Y`; no related work found." An item with zero relations and no documented search is rejected.
+
+For each candidate, classify the relationship:
+
+| Relation Type | When to Use |
+|---------------|-------------|
+| `blocks` | This item must ship before the linked item can proceed |
+| `blocked_by` | The linked item must ship before this one can proceed |
+| `relates_to` | Shared context, no ordering constraint |
+| `duplicates` | This item already exists — close one as duplicate |
+
+Linear native relations are set on the Issue via `save_issue`'s `relations` field (or via a paired `save_issue_relation` call if available in the MCP). For Project-level (Epic) relationships, capture them in the description under `## Related Projects` since Linear doesn't model relations between Projects natively.
+
+### 4c. Remote Links
+
+Identify and attach (Linear stores attachments / links on the Issue or in description body):
+
+- GitHub PRs, branches, or commits related to this work
+- Confluence pages (design docs, RFCs, runbooks)
+- Dashboards (Grafana, Datadog, Sentry issue)
+- Incident items (PagerDuty, Statuspage)
+- **Source artifacts from the originating PRD / parent Project**: classify and inherit per the rules in `lisa:tracker-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). Enumerate the parent Project's links and inherit the ones whose domain matches this item's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`). Never assume a developer will walk up to the Project to find design context — attach it here.
+
+If the item was generated from a PRD (by `lisa:notion-to-tracker` or similar) and the parent Project has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
+
+### 4d. Source Precedence (must appear on the item)
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-source-artifacts` §3 and §4. When an item carries both design artifacts and a description, record the precedence explicitly in the description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts. Cross-axis conflicts go under `## Open Questions` as BLOCKER items.
+
+For UI-touching items, include the existing-component reuse expectation per `lisa:tracker-source-artifacts` §7.
+
+### 4e. Live Product Walkthrough Findings (UI-touching items)
+
+If the item modifies an existing user-facing surface, a `lisa:product-walkthrough` should already have been run upstream. Inherit its findings under a `## Current Product` subsection in the description so the implementer sees what's shipped today before changing it. If the upstream skill skipped the walkthrough but this item clearly modifies an existing surface, invoke `lisa:product-walkthrough` here before proceeding.
+
+## Phase 5 — Set Metadata
+
+Before create/update, verify each field is populated where applicable:
+
+- **Labels**: include `status:ready` for new items; component labels (`component:<name>`); status / priority labels are NOT redundant with native fields — labels exist for portability and downstream queries.
+- **Native priority field**: 0–4 per Linear's scale; explicit, not "unset".
+- **Native estimate**: per Linear's team-configured estimate scale (often 0–8 Fibonacci); skip for Epic / Spike.
+- **ProjectMilestone**: when the team uses dated milestones, set the milestone on the Project (Epic) or on the Issue (when an Issue belongs to a milestone).
+- **Cycle**: only if actively in a cycle.
+- **Assignee**: leave unset if unknown rather than auto-assigning.
+
+For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
+
+## Phase 5.5 — Validate (Pre-write Gate)
+
+Before any write, invoke `lisa:linear-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa:linear-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
+
+The validator is the **single source of truth** for what makes a valid Linear work item. The same gates are used by `lisa:linear-to-tracker` dry-run, by `lisa:linear-verify` post-write, and here. Do not re-implement gate logic in this skill.
+
+If the validator reports `FAIL`:
+- Surface the failure list and the per-gate remediation to the user.
+- Do NOT proceed to Phase 6. Fix the spec (or stop and ask the human) and re-run validation.
+- Never call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` while the validator's verdict is FAIL.
+
+If the validator reports `PASS`, continue to Phase 6.
+
+## Phase 6 — Create or Update
+
+### CREATE — Epic (Project)
+
+1. Resolve any required Project labels (`prd-ticketed`, etc.) via `mcp__linear-server__list_project_labels` (create via `create_project_label` if missing).
+2. Call `mcp__linear-server__save_project` with: `name` (summary), `description` (markdown), `teamIds: [<teamId>]`, `labelIds`, `priority` (Linear Project priority is also 0–4), `state` (default `backlog`), milestones if dated.
+3. Capture the returned Project ID and slug — Phase 4 children need these.
+4. If the Project is the parent for downstream Stories, record the ID for `lisa:linear-to-tracker` Phase 4 to use.
+
+### CREATE — Story / Task / Bug / Spike / Improvement (Issue with projectId)
+
+1. Resolve any required Issue labels (`status:ready`, `component:<name>`, `prd-intake-feedback` only if this is a sentinel issue, etc.) via `mcp__linear-server__list_issue_labels` (create via `create_issue_label` if missing).
+2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (summary), `description` (markdown), `projectId` (the Epic Project), `priority` (0–4), `estimate`, `labelIds`, `assignee` if known.
+3. Capture the returned identifier (e.g. `ENG-123`) — Phase 4 sub-tasks need it as `parentId`.
+4. Add relationships from Phase 4b via `save_issue` (relations field) or paired relation calls.
+5. If the item changes runtime behavior, invoke `lisa:linear-add-journey` to append the Validation Journey section.
+
+### CREATE — Sub-task (Issue with parentId)
+
+1. Resolve labels as above.
+2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (`[<repo>] <summary>` prefix is mandatory), `description` (markdown), `parentId` (the Story Issue ID), `projectId` (inherit from parent), `priority`, `estimate`, `labelIds`.
+3. Capture identifier.
+4. Add relationships via Phase 4b.
+
+### UPDATE
+
+1. Call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` with **only the fields being changed**. Do NOT resend fields that weren't in the change set — Linear treats the call as a full overwrite of the listed fields.
+2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first.
+
+## Phase 7 — Verify
+
+Call the `lisa:linear-verify` skill on the resulting item. `lisa:linear-verify` fetches the live item and runs `lisa:linear-validate-issue` against it — same gates as Phase 5.5, but applied to what Linear actually stored. If it reports failures, fix them before returning. Do not report success on an item that fails verify.
+
+## Phase 8 — Announce
+
+Post a creation comment via `mcp__linear-server__save_comment` (on the Issue, or on a sentinel issue under the Project for Epic-level announcements) with:
+
+- `[<repo>]` prefix if the item is repo-scoped
+- Who the item is assigned to (if known)
+- The relationships that were set (`blocks`, `blocked_by`, `relates_to`) with Linear identifiers
+- Any remote PRs attached
+
+Skip this step only on UPDATE when no material change was made.
+
+## Rules
+
+- Never create a non-Epic, non-top-level item without a parent context (Project for Stories, parentId for Sub-tasks).
+- Never skip relationship discovery — both the git history search AND the Linear MCP search must run, and their outcomes must be recorded on the item. "None found" is acceptable only when it's documented.
+- Never create a Bug, Task, or Sub-task that spans multiple repos. Split it before creating.
+- Never include a runtime-behavior item without a target backend environment, and never include an authenticated-surface item without sign-in credentials in the description.
+- Never invent custom field values. If the team requires a field you don't have, stop and ask.
+- Never overwrite a description without reading the current version first.
+- All Linear writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:linear-create`) should delegate here rather than calling the MCP write tools directly.
+- The gate logic (what makes a valid item) lives in `lisa:linear-validate-issue`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:linear-verify` post-write). When a gate needs to change, change it in `lisa:linear-validate-issue` — every caller picks it up automatically.
+- This skill is the destination of the `lisa:tracker-write` shim when `tracker = "linear"`. Vendor-neutral callers (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST go through `lisa:tracker-write`, not call this skill directly.

package/plugins/src/base/skills/notion-prd-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion-prd-intake
-description: "Scans a Notion PRD database for pages with Status=Ready and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and Status=Ticketed; PRDs that fail get clarifying-question comments and Status=Blocked. The skill is the runtime for the Ready → In Review → Blocked|Ticketed lifecycle. Composes existing skills (notion-to-tracker, tracker-validate, jira-source-artifacts, product-walkthrough); does not reimplement their logic."
+description: "Scans a Notion PRD database for pages with Status=Ready and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and Status=Ticketed; PRDs that fail get clarifying-question comments and Status=Blocked. The skill is the runtime for the Ready → In Review → Blocked|Ticketed lifecycle. Composes existing skills (notion-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough); does not reimplement their logic."
 allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-search", "mcp__claude_ai_Notion__notion-update-page", "mcp__claude_ai_Notion__notion-create-comment", "mcp__atlassian__getAccessibleAtlassianResources"]
 ---
 
@@ -27,7 +27,7 @@ Specifically forbidden:
 
 The only legitimate reasons to stop early:
 
-- Missing database URL or required configuration (`JIRA_PROJECT`, `JIRA_SERVER`, `E2E_BASE_URL`, etc.). Surface the missing value and exit.
+- Missing database URL or required configuration (`atlassian.cloudId`, `jira.project` or destination-tracker equivalents in `.lisa.config.json`, `E2E_BASE_URL`, etc.). Surface the missing value and exit.
 - Database misconfigured (Status property missing expected values, data source unreachable). Surface and exit.
 - Empty `Ready` set. Exit cleanly with `"No PRDs with Status=Ready. Nothing to do."`
 
@@ -78,7 +78,7 @@ Invoke the `lisa:notion-to-tracker` skill with `dry_run: true` and the PRD's URL
 - An overall PASS / FAIL verdict
 - A failure count
 
-This call also indirectly invokes `lisa:jira-source-artifacts` (artifact extraction + classification) and `lisa:product-walkthrough` (when the PRD touches existing user-facing surfaces). All gate logic lives in `lisa:tracker-validate`, which `lisa:notion-to-tracker` calls per ticket.
+This call also indirectly invokes `lisa:tracker-source-artifacts` (artifact extraction + classification) and `lisa:product-walkthrough` (when the PRD touches existing user-facing surfaces). All gate logic lives in `lisa:tracker-validate`, which `lisa:notion-to-tracker` calls per ticket.
 
 #### 3c. Branch on the verdict
 
@@ -208,12 +208,18 @@ Print to the agent's output. Do not write this summary to Notion or JIRA — it'
 
 ## Configuration
 
-This skill reads project configuration from environment variables (or `$ARGUMENTS` overrides). If any required value is missing, ask the user before proceeding — never invent values.
+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. Destination tracker config (jira / github / linear) is consumed by `lisa:tracker-write` internally — this skill does NOT read it.
+
+### From `.lisa.config.json`
+
+| Field | Purpose |
+|-------|---------|
+| `notion.prdDatabaseId` | Notion database hosting PRDs (when `$ARGUMENTS` is the literal token `notion`) |
+
+### From environment variables
 
 | Variable | Purpose |
 |----------|---------|
-| `JIRA_PROJECT` | JIRA project key for ticket creation (passed to `lisa:notion-to-tracker`) |
-| `JIRA_SERVER` | Atlassian instance host |
 | `E2E_BASE_URL` | Frontend URL for `lisa:product-walkthrough` |
 | `E2E_TEST_PHONE` / `E2E_TEST_OTP` / `E2E_TEST_ORG` | Test user creds for walkthrough + verification plans |
 | `E2E_GRAPHQL_URL` | API URL for verification plans |