@codyswann/lisa 2.119.1 → 2.121.1

package/plugins/lisa-copilot/skills/product-walkthrough/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: product-walkthrough
+description: "Methodology for evaluating the live product via a real browser (Playwright MCP) when planning work or evaluating a PRD. Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change — this skill grounds the analysis in what actually exists today. Invoke this skill from notion-to-tracker (Phase 2b live-product walkthrough), jira-create, and any PRD intake flow whose work touches existing user-facing surfaces."
+allowed-tools: ["Skill", "Bash", "Read", "mcp__plugin_playwright_playwright__browser_navigate", "mcp__plugin_playwright_playwright__browser_snapshot", "mcp__plugin_playwright_playwright__browser_take_screenshot", "mcp__plugin_playwright_playwright__browser_click", "mcp__plugin_playwright_playwright__browser_type", "mcp__plugin_playwright_playwright__browser_select_option", "mcp__plugin_playwright_playwright__browser_fill_form", "mcp__plugin_playwright_playwright__browser_press_key", "mcp__plugin_playwright_playwright__browser_hover", "mcp__plugin_playwright_playwright__browser_navigate_back", "mcp__plugin_playwright_playwright__browser_resize", "mcp__plugin_playwright_playwright__browser_tabs", "mcp__plugin_playwright_playwright__browser_console_messages", "mcp__plugin_playwright_playwright__browser_network_requests", "mcp__plugin_playwright_playwright__browser_wait_for", "mcp__plugin_playwright_playwright__browser_close"]
+---
+
+# Live Product Walkthrough
+
+Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change. This skill defines how to use a real browser (via Playwright MCP) to evaluate the live product *before* planning tickets, so the work is grounded in what actually exists today.
+
+## When to invoke
+
+Always run a walkthrough when the work touches user-facing surfaces:
+
+- The PRD describes a change to an existing screen, flow, or interaction
+- The PRD adds something *next to* existing functionality (entry points, navigation, related screens)
+- A mock or prototype implies a re-style or re-flow of something currently shipped
+- The change is a "bug" framed as a fix to current behavior — you must see the current behavior before reasoning about the fix
+
+Skip when the work is purely backend with no user-visible surface, type-only, doc-only, or affects a screen that does not yet exist in production / dev.
+
+## Configuration
+
+Required inputs (ask if not set):
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `E2E_BASE_URL` | Frontend base URL to walk through | `https://dev.example.io/` |
+| Sign-in account | Test user to sign in as for the affected flows | from PRD config / 1Password / env |
+| Sign-in credentials | How to obtain (1Password item, env vars) | `E2E_TEST_PHONE`, `E2E_TEST_OTP` |
+
+Walk through `dev` (or the env named in the PRD) — never `prod` for exploratory walkthroughs unless explicitly asked.
+
+## Process
+
+### 1. Plan the walkthrough
+
+Before opening the browser, list the surfaces the change will touch:
+
+- Which screens/routes are involved (current and new)?
+- Which user roles need to be exercised (admin / customer / etc.)?
+- Which states matter (signed-out, signed-in, empty, populated, error, loading)?
+- Which viewports matter (desktop always; mobile when responsive; tablet rarely)?
+
+Write this list down. If you can't, the PRD is too vague — note this as a coverage smell and surface it as an Open Question on the resulting ticket.
+
+### 2. Open the browser and sign in
+
+1. `browser_navigate` to `E2E_BASE_URL`.
+2. `browser_resize` to the primary viewport (default desktop 1512×768).
+3. Sign in via the test account. Use `browser_fill_form` and `browser_click`. Capture the post-login screen with `browser_snapshot` or `browser_take_screenshot`.
+
+### 3. Walk the affected surfaces
+
+For each surface from step 1:
+
+1. Navigate to it. Capture a `browser_snapshot` (accessibility tree — better for reasoning) and a `browser_take_screenshot` (visual evidence).
+2. Exercise the relevant interactions. Capture state transitions.
+3. Capture each state that matters (empty, populated, error, loading) — explicitly trigger them where possible.
+4. For responsive changes, `browser_resize` to the secondary viewport (mobile 375×812) and re-capture.
+5. `browser_console_messages` and `browser_network_requests` after each interaction — surface any errors, 4xx/5xx, or unexpected calls.
+
+### 4. Record findings
+
+For every walkthrough, record:
+
+- **What exists today**: a short prose description of the current flow, the components in use (if you can identify them from the DOM via `browser_snapshot`), and the states observed.
+- **What the PRD changes**: explicit delta — added screens, removed screens, modified components, new states, removed states.
+- **Existing-component reuse candidates**: components in the current product that could absorb the new behavior. The PRD-vs-current-product comparison drives which existing components a developer should reuse instead of building new (see `lisa:tracker-source-artifacts` §7).
+- **Design-vs-current-product divergence**: places where the mock/prototype materially diverges from what's shipped. Each divergence is a discussion item, not an automatic "rebuild from scratch" — see `lisa:tracker-source-artifacts` §3 (mocks define visual intent, not implementation shortcut).
+- **Coverage smells**: states the PRD doesn't address that exist today (e.g., the mock shows the empty state but ignores the populated state that has 90% of users).
+- **Behavioral surprises**: anything that doesn't match the PRD's assumptions about current behavior — these are usually the most valuable findings, because they invalidate parts of the PRD.
+
+### 5. Attach evidence to the originating context
+
+Capture screenshots/snapshots in a way that the originating ticket / Notion comment / PRD review can reference them.
+
+- For **PRD intake**: include a "Current Product" comment on the Notion PRD with the findings prose and inline screenshots of the current state alongside each affected screen mentioned in the PRD.
+- For **ticket creation**: include the findings under `## Current Product` in the ticket description (Story or Epic). Reference the screenshots as remote links if hosted, or inline them as attachments.
+- For **change-impact analysis**: produce a short report; the consuming skill decides where it lands.
+
+### 6. Close the browser
+
+`browser_close` when done. Walkthroughs are short, focused, and one-shot — do not leave a session open across phases.
+
+## Findings format
+
+Use this structure when emitting walkthrough findings, so consuming skills can splice them into tickets / comments unchanged. The `## Current Product` heading matches what `lisa:jira-write-ticket` Phase 4e expects to inherit — keep the heading exact.
+
+```text
+## Current Product
+
+**Environment**: <E2E_BASE_URL> as <account/role>
+**Viewports exercised**: Desktop 1512×768, Mobile 375×812
+
+### Surfaces walked
+1. <route> — <one-line current behavior>
+2. <route> — <one-line current behavior>
+
+### What exists today
+<2-4 sentence prose summary of the current flow and components in use>
+
+### Delta vs. PRD
+- ADDED: <new surface/state from PRD>
+- MODIFIED: <existing surface, with the change>
+- REMOVED: <existing surface PRD removes>
+- UNCHANGED-BUT-IMPACTED: <existing surface PRD doesn't mention but will be affected>
+
+### Existing-component reuse candidates
+- <component or screen> — could absorb <new behavior>
+
+### Design-vs-current-product divergence
+- <mock or prototype reference> diverges from <current screen> in: <specific dimension>
+- Recommendation: <reuse / new build / discussion>
+
+### Coverage smells & behavioral surprises
+- <smell or surprise>
+
+### Evidence
+- <list of screenshots/snapshots, with captions>
+```
+
+## Rules
+
+- Walk before you write. If the work touches existing user-facing surfaces and the walkthrough wasn't done, the resulting ticket is missing context — don't ship it.
+- Never walk `prod` for exploratory analysis. `dev` (or the env named in the PRD) only.
+- Treat console errors and unexpected network calls as findings — they often reveal undocumented behavior the PRD assumes is fine.
+- Findings drive `## Open Questions` on tickets, not silent assumptions. If the current product contradicts the PRD, surface it as a BLOCKER.
+- This skill captures observations; it does not edit JIRA or the PRD. Consuming skills decide where findings land (ticket description, Notion comment, validator input).

package/plugins/lisa-copilot/skills/project-ideation/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: project-ideation
+description: "Generate practical, verifiable product ideas for the current host project FROM EVIDENCE-DERIVED PERSONAS, then turn the selected build-ready ideas into real PRDs via lisa:research. First derives the personas the project actually serves by mining its docs, code, data model, and releases (never invented — each persona cites its evidence), then ideates per persona. Every build-ready idea must pass a practicality gate (an obtainable data/source path) and an empirical verification gate (a user-observable outcome the agent can verify). Selected ideas are handed to lisa:research, which creates each PRD in the configured source (Notion / Confluence / GitHub / Linear) — in the draft state by default, or prd-ready (auto-picked-up by lisa:intake) when prd_ready=true. Defaults to creating one PRD (the top-ranked idea); max_prds widens the batch. Invoke for 'generate feature ideas for this project', 'what should we build next for <persona>?', 'looking at <external product>, what should we add here?'. Vendor- and stack-agnostic."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep", "WebFetch", "WebSearch"]
+---
+
+# Project Ideation
+
+Generate persona-grounded, verifiable ideas for the host project in `$ARGUMENTS` (or the current
+working directory), then create PRDs for the selected build-ready ideas via `lisa:research`.
+
+The value of this skill is **grounding + filtering**, not brainstorm volume. Ideas come from
+personas the project demonstrably serves, and an idea you cannot ground in obtainable data and
+cannot verify yourself is noise — demote it honestly.
+
+## Parameters
+
+- **`target`** (first positional, optional) — a target project path, or an external product/site to
+  draw inspiration from. Defaults to the current working directory.
+- **`prd_ready=true|false`** (default **false**) — the PRD-lifecycle state for the PRDs this run
+  creates. `false` → created in the source's **draft** state for human review. `true` → created
+  **prd-ready** so the PRD side of `lisa:intake` auto-claims them. Passed straight through to
+  `lisa:research` (which maps it to `lisa:prd-source-write`'s `initial_role`) only after the PRD queue
+  pressure gate allows auto-ready writes.
+- **`max_prds=<n>|all`** (default **1**) — how many build-ready ideas become PRDs this run. Default
+  creates **one** PRD (the single top-ranked idea), because `lisa:research` is a heavy full flow.
+  `max_prds=3` creates the top three; `max_prds=all` creates one per build-ready idea. Discovery
+  Spikes and Rejected ideas are never turned into PRDs regardless of `max_prds`.
+- **`fixture=<path>`** (optional, verification-only) — a deterministic host-project fixture used
+  for idempotency verification. When present, read the fixture before ranking and honor its declared
+  single persona, single idea, existing-fit anchor, and expected dedupe marker. Do not use this
+  parameter for normal ideation runs.
+
+## When to use
+
+- "generate feature ideas for this project" / "what should this app do next?"
+- "what should we build next for <persona / user type>?"
+- "looking at <external product / website>, what should we add here?"
+- "suggest practical improvements we can verify ourselves"
+
+This skill **does** create PRDs (via `lisa:research`) for the selected ideas. It does **not** create
+tracker tickets (that is `lisa:plan`) and does **not** change code (that is `lisa:implement`).
+
+## Two gates every build-ready idea must pass
+
+An idea may only become a **Practical Idea** (and thus a PRD candidate) if it passes BOTH gates.
+Otherwise demote it.
+
+1. **Practicality gate.** The project can plausibly implement the idea from sources that actually
+   exist: existing code, a data model, a route/command/UI surface, a public or integrated API, a
+   scrapeable public page, an existing user input, a local database, or documented integrations. Name
+   the specific source and how the data is obtained. "We could probably get the data somehow" fails.
+2. **Empirical verification gate.** You can personally confirm the resulting behavior by using the
+   software (running the CLI, hitting the API, loading the page, querying the DB, inspecting an
+   artifact) and capture a concrete evidence artifact. "Tests could be written later" does NOT
+   satisfy this gate — quality gates are prerequisites, never proof an idea works.
+
+Failing the practicality gate → **Rejected / Not Practical Yet** (or **Discovery Spike** if a bounded
+probe could make it practical), naming the missing data/source/access. Failing only the verification
+gate → **Discovery Spike** (define the missing proof), never a build-ready recommendation.
+
+## Step 1 — Establish host-project context (always first)
+
+Never propose ideas before you understand what exists. Inspect the host project and record:
+
+- **Project type and package manager** — manifests (`package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, `Gemfile`, …) and any `.lisa.config.json`.
+- **Docs and specs** — `README`, `docs/`, `wiki/`, architecture notes, ADRs, marketing/landing copy.
+- **Current product surfaces or commands** — routes, screens, CLI subcommands, API endpoints,
+  scheduled jobs, generated artifacts.
+- **Data model and existing user inputs** — schemas, migrations, forms, config the user supplies.
+- **Available data sources and ingestion/scraping paths** — integrated APIs, public datasets,
+  scrapeable pages, local databases, event streams.
+- **Existing verification tooling** — how a human currently observes the software works.
+
+Use Lisa's existing methodology rather than inventing a parallel flow. Route each evidence source
+through the matching established practice before any idea is promoted to **Practical Ideas**:
+
+- **Host-code inspection** uses `/lisa:codebase-research` concepts: trace data flow from entry point
+  to output, identify modification points, map dependencies, and find reusable code or patterns.
+- **Public, no-login comparison** uses web/browser research when those tools are available: inspect
+  the public surface, preserve source URLs, and separate observed behavior from inference.
+- **UI-facing recommendations** use `/lisa:product-walkthrough` methodology first: inspect the
+  current product surface, note existing-component reuse candidates, capture coverage smells or
+  behavioral surprises, and only then list a UI idea as build-ready.
+
+## Step 2 — Derive the personas (evidence-gated, never invented)
+
+Ideation is **persona-driven**, and the personas must be gleaned from the project itself — not
+assumed. Mine the Step 1 evidence for who the project actually serves:
+
+- **Docs / README / release notes / CHANGELOG** — stated audiences, "for <role>" framing, who each
+  shipped feature was for.
+- **Code** — auth roles / RBAC / permission checks, account-type or user-type enums, route guards,
+  feature flags scoped to a cohort, role-specific UI branches.
+- **Data model** — user / role / tenant / org tables, profile fields, subscription tiers.
+- **Tests & product walkthrough** — the real user journeys exercised.
+- **External inspiration** (Step 3, if used) — comparable products' user segments, as inspiration
+  only.
+
+Anti-fabrication rule (mechanical): **no evidence citation → no persona.** Generic roles
+("admin", "analyst", "end user", "power user") are **banned unless the project has specific evidence
+for them**. Each persona requires at least **two grounded signals** from different source classes
+where available; if only one strong signal exists, emit a single **low-confidence "Primary
+documented user"** persona named as such — never fabricate a full set from thin evidence.
+
+Cap the set at **3–6 personas** (merge adjacent personas by goal/workflow; more than six is taxonomy
+noise). Each persona records:
+
+- `name` — concrete and project-specific.
+- `goals` — what this persona is trying to accomplish.
+- `pains` — current friction for this persona, grounded in observed behavior/gaps.
+- `evidence` — the specific files / doc sections / tables / releases that justify the persona.
+- `confidence` — high | medium | low, with the reason.
+
+Always emit a **Personas Derived From Evidence** section, even when no PRDs are created. Spikes and
+rejected ideas are still tagged with the persona they would serve (or `cross-persona`).
+
+## Step 3 — Optional external / public-source inspection
+
+Only when the user references an external product, website, public dataset, or competitor:
+
+- Inspect **public, no-login** surfaces only. Preserve every **source URL** so informed ideas cite
+  it. The external source is **inspiration, not a domain you bake in** — keep the workflow reusable.
+- If the runtime has no browser/web capability, mark that source **unavailable** and proceed with
+  host-project-only ideas (document the fallback rather than fabricating findings).
+
+## Step 4 — Ideate per persona, then filter through the gates
+
+For each derived persona, brainstorm ideas that serve that persona's goals/pains, **tag each idea
+with the persona(s) it serves**, then run every idea through BOTH gates. For each surviving idea,
+build a **feasibility card**:
+
+- **Persona(s) served** — which derived persona(s), and why this matters to them.
+- **Existing fit** — the current route / API / CLI / model / doc / surface it builds on (this is also
+  the idea's stable "existing-fit anchor" used in the dedupe key).
+- **Data/source required** + **how it is obtained** — the concrete accessible path.
+- **Known source limitations** — rate limits, robots/ToS, staleness, missing fields.
+- **Smallest practical slice** — the minimal useful version.
+- **Empirical verification steps** — what you (the agent) will do against the running software.
+- **Evidence artifact** — the screenshot, curl/CLI output, DB row, or generated file the verifier
+  captures.
+- **Confidence** — high | medium | low, with the reason.
+
+## Step 5 — Rank and select the PRD creation set
+
+Rank Practical Ideas by **persona value, feasibility, verification clarity, and project fit**. Then
+select the creation set by `max_prds` (default **1** → the single top-ranked idea; `<n>` → top n;
+`all` → every Practical Idea). Spikes and Rejected ideas are reported but never selected.
+
+## Step 5.5 — Block auto-ready writes when the PRD queue has pressure
+
+This step runs **only** when `prd_ready=true`. A draft run (`prd_ready=false`) skips this gate and
+continues to Step 6, because draft PRDs do not create immediate PRD-intake pickup pressure.
+
+Before invoking `lisa:research` for any selected idea, inspect the configured PRD source queue with
+the same PRD reader contract used by `/lisa:queue-status` and evaluate it with
+`evaluatePrdQueuePressure` from `plugins/lisa/scripts/queue-status-prd-readers.mjs` (source:
+`plugins/src/base/scripts/queue-status-prd-readers.mjs`). Resolve the queue from `.lisa.config.json`
+the same way `lisa:intake` resolves the PRD side, and pass the matching queue argument in the
+blocked outcome (for example, `github intake_mode=prd`).
+
+Queue pressure is any unresolved PRD lifecycle work that would make another auto-ready PRD compete
+with existing intake work. Treat at least these roles as pressure when the helper reports them:
+`prd-ready`, `prd-in-review`, `prd-blocked`, unresolved `prd-ticketed`, and source-reader failures or
+misconfiguration snapshots. `prd-shipped` / `prd-verified` terminal history is not pressure unless the
+reader helper explicitly reports it as unresolved.
+
+If the helper returns `allowed: false`, stop before any `lisa:research`, `lisa:prd-source-write`, or
+vendor PRD writer invocation. Emit **PRDs Created** as a blocked outcome, not as an empty success or a
+silent idle run. The blocked outcome must include:
+
+- `source` and `tracker` from `.lisa.config.json`;
+- the decisive PRD lifecycle `role`;
+- the blocking PRD item `ref` and `url`, when the snapshot supplies them;
+- the smallest next action, preferring the helper's `nextStep` and otherwise using
+  `/lisa:intake <PRD queue>`;
+- a clear statement that no research or PRD source write was invoked.
+
+Use this output shape so recurring automations can surface a useful next step without digging through
+debug logs:
+
+```text
+## PRDs Created
+
+Blocked: PRD queue pressure prevents auto-ready creation.
+- source: <source>
+- tracker: <tracker>
+- role: <decisive role>
+- item: <ref or "unavailable"> <url when available>
+- next action: <helper nextStep or /lisa:intake <PRD queue>>
+- write invoked: no
+```
+
+If the helper returns `allowed: true`, continue to Step 6 normally and keep the existing draft/ready
+creation behavior unchanged.
+
+## Step 6 — Create a PRD per selected idea (via lisa:research)
+
+For each idea in the creation set, invoke `/lisa:research` with:
+
+- the feasibility card and persona evidence as the problem statement (so the PRD inherits the
+  grounding and the empirical verification plan),
+- `prd_ready` (this run's flag — `lisa:research` maps it to draft vs prd-ready),
+- a stable **dedupe marker** (see below) so a re-run references the existing PRD instead of creating
+  a duplicate,
+- a structured `ideation_ledger_payload` handoff containing the selected marker, automation id and
+  memory path when available, persona names, persona evidence references, rejected overlap
+  candidates, repo identity, `prd_ready`, selected idea title/key, and the expected empirical
+  verification artifact. This payload is the only ideation-run metadata channel between
+  `project-ideation`, `research`, `prd-source-write`, and the vendor writer; keep GitHub-specific
+  rendering out of this skill.
+
+`lisa:research` synthesizes the PRD and creates it in the configured source via
+`lisa:prd-source-write`. `project-ideation` never writes to the source directly — it delegates, so
+the PRD source stays switchable per project. Capture each returned PRD ref / URL / role / outcome.
+
+### Optional Codex automation memory
+
+When the run has a Codex automation id or memory path, maintain a concise local advisory ledger after
+the PRD source write returns. Resolve the memory path in this order:
+
+1. explicit `memory_file=<path>` or `automation_memory=<path>` argument, when supplied;
+2. `$CODEX_AUTOMATION_MEMORY`, when set;
+3. `$CODEX_HOME/automations/<automation_id>/memory.md`, when `automation_id=<id>` or
+   `$CODEX_AUTOMATION_ID` is available.
+
+Create the parent directory and `memory.md` if missing. Write one concise run entry keyed by the
+dedupe marker and run timestamp. The entry must include the marker, PRD URL/ref, outcome
+(`created | reused | updated | blocked`), lifecycle role (`draft | ready | blocked` or the returned
+source role), and `source_agreement` (`github-source-wins`, `memory-created`, `memory-updated`, or
+`memory-missing-runtime`). If memory says one thing but the PRD source search finds a matching open
+PRD, GitHub/source truth wins: reuse the source PRD and update memory rather than creating a
+duplicate. Keep memory advisory only; never use it to override lifecycle labels, source marker
+matches, or the PRD source writer's returned role. Do not store secrets, tokens, full PRD bodies, or
+private source excerpts in memory.
+
+### Dedupe marker (stable, never title-based)
+
+Each created PRD carries the marker `[lisa-project-ideation] idea=<stable-key>`. Compute
+`<stable-key>` deterministically from: repo identity (configured repo or git remote + repo-root
+basename) + a normalized slug of the idea name + the normalized persona key(s) + the existing-fit
+anchor. **Do not** include rank, date, confidence, or the generated PRD title (they change across
+runs). `lisa:prd-source-write` searches the source for an open PRD carrying this marker before
+creating — matching by marker, never by title — so re-running ideation updates/references the
+existing PRD rather than duplicating it.
+
+## Step 7 — Output (no report file)
+
+Emit two distinct in-session sections (do not write a report file):
+
+1. **Idea report** (the audit trail):
+   ```markdown
+   ## Personas Derived From Evidence
+   - <name> — goals; pains; evidence (files/docs/tables/releases); confidence
+
+   ## What Already Exists
+   - <current surfaces, data, commands, workflows — so duplicates aren't re-proposed>
+
+   ## Practical Ideas
+   ### 1. <Idea name>  (persona: <persona(s)>)
+   - Persona value · Existing fit · Data/source path · Practical slice · Empirical verification ·
+     Evidence · Confidence
+
+   ## Discovery Spikes
+   - <ideas needing proof of data/access/verification — name the missing proof — tagged by persona>
+
+   ## Rejected / Not Practical Yet
+   - <attractive ideas rejected for missing data/access/legality/verification — name what's missing>
+   ```
+2. **PRDs Created** (the creation summary): for each selected idea — the created/reused PRD ref +
+   URL, its lifecycle role (`draft` or `ready`), its dedupe marker, and `created | reused`. List the
+   Practical Ideas that were **not** created this run and why (e.g. "below the `max_prds=1` cut").
+
+Always include the **Personas**, **What Already Exists**, **Discovery Spikes**, and **Rejected**
+sections (even if empty) so the user sees what was considered and filtered out.
+
+## Out of scope (hard rules)
+
+- **No fabricated personas.** No evidence citation → no persona; generic roles banned without
+  evidence (Step 2).
+- **No sign-in-only ideas** unless the host project already supports sign-in *and* credentials are
+  available. **No private-data assumptions.** **No manual-data-only** requirements unless the user
+  accepts manual curation. **No paid-API / non-scrapeable-source ideas** in the build-ready list —
+  demote with the blocker named.
+- **Tests, lint, typecheck, and build are not the empirical verification plan** — they are
+  prerequisites; verification must observe user-facing behavior.
+- **Do not create tracker tickets or mutate the host project's code.** PRD creation (via
+  `lisa:research`) is the only write this skill performs; ticket planning (`lisa:plan`) and
+  implementation (`lisa:implement`) are separate, user-invoked flows.
+- **Do not write PRDs to the source directly** — always go through `lisa:research` →
+  `lisa:prd-source-write` so the source stays switchable.
+- **Do not add a new verification/browser-automation framework** when one already exists — reuse it.
+- **Do not overfit to a source example.** Keep the workflow project-agnostic.
+
+## Handing off
+
+The created PRDs flow straight into the lifecycle:
+
+- A `draft` PRD → a human reviews it, then promotes it to `ready` (or re-run with `prd_ready=true`).
+- A `prd-ready` PRD → `/lisa:intake` (PRD side) auto-claims it → `/lisa:plan` decomposes it →
+  `/lisa:implement` builds each item → `/lisa:codify-verification` locks in the verification.
+
+## Example outputs
+
+Use the markdown examples in `examples/` as shape references for the idea report:
+
+- `host-project-only.md` — ideas grounded only in the current repository.
+- `public-external-inspiration.md` — public, no-login external sources as inspiration, not hidden
+  requirements.
+- `unavailable-data-rejection.md` — naming missing private/paid/unavailable sources when demoting.
+- `evidence-card-format.md` — the required evidence fields every Practical Idea card must carry.
+- `idempotency-verification-harness.md` — deterministic fixture and script procedure proving that
+  repeated `prd_ready=true` ideation keeps the open GitHub marker count at one, including the
+  missing-memory rerun variant.

package/plugins/lisa-copilot/skills/project-ideation/examples/evidence-card-format.md

@@ -0,0 +1,21 @@
+# Evidence Card Formatting Example Output
+
+## What Already Exists
+- Lisa work items already use Validation Journey evidence markers.
+- Skill reports can be saved as markdown artifacts and reviewed by humans.
+
+## Practical Ideas
+### 1. Evidence-First Idea Cards
+- User value: A reviewer can decide whether an idea is ready without asking how it will be proven.
+- Existing fit: Uses the project-ideation report shape and Lisa's evidence-first verification rules.
+- Data/source path: Existing local project files plus any public URLs cited in the report.
+- Practical slice: Require each practical idea to include `Empirical verification` and `Evidence` lines before it can remain in the practical list.
+- Empirical verification: Render this example and confirm every practical idea card includes the two evidence fields.
+- Evidence: Text output showing all practical cards pass the field check.
+- Confidence: high because the check is structural and does not require external services.
+
+## Discovery Spikes
+- Evidence attachments inside generated reports: needs a storage and retention decision for binary artifacts.
+
+## Rejected / Not Practical Yet
+- Treating lint, typecheck, or unit tests as the only proof for a user-facing idea: rejected because quality gates are prerequisites, not empirical evidence artifacts.

package/plugins/lisa-copilot/skills/project-ideation/examples/host-project-only.md

@@ -0,0 +1,22 @@
+# Host Project Only Example Output
+
+## What Already Exists
+- CLI command registration is documented in the repository README.
+- Skill sources live under `plugins/src/base/skills/` and are copied into the generated Lisa plugin.
+- The project already has unit tests that verify generated plugin artifacts.
+
+## Practical Ideas
+### 1. Plugin Surface Drift Report
+- User value: Maintainers can see which source skills are not represented in the generated plugin before publishing.
+- Existing fit: Builds on the existing plugin source tree and generated plugin artifact tests.
+- Data/source path: Local files under `plugins/src/base/skills/` and `plugins/lisa/skills/`.
+- Practical slice: Emit a markdown report listing source-only, generated-only, and mismatched skill directories.
+- Empirical verification: Run the report command in a clean checkout after intentionally adding one fixture-only source skill.
+- Evidence: CLI output showing the mismatched skill and the generated markdown report path.
+- Confidence: high because the required data is already local and deterministic.
+
+## Discovery Spikes
+- Skill usage frequency ranking: needs a bounded source of invocation telemetry before it can be recommended.
+
+## Rejected / Not Practical Yet
+- Personalized skill suggestions from private user history: rejected because the repository does not have access to private Codex usage history.

package/plugins/lisa-copilot/skills/project-ideation/examples/idempotency-verification-harness.md

@@ -0,0 +1,57 @@
+# Project Ideation Idempotency Verification Harness
+
+Use this documented harness when validating that `project-ideation prd_ready=true` reuses an
+existing GitHub PRD by stable marker instead of creating duplicates.
+
+## Deterministic fixture
+
+Create an isolated fixture project with only one evidence-backed persona and one build-ready idea.
+The fixture should make the selected marker predictable:
+
+- Repo identity: `CodySwannGT/lisa`
+- Persona key: `queue-automation-operators`
+- Idea name: `Exploratory PRD run ledger`
+- Existing-fit anchor: `plugins/src/base/skills/project-ideation/SKILL.md`
+- Expected marker: `[lisa-project-ideation] idea=codyswanngt-lisa-exploratory-prd-run-ledger-queue-automation-operators-plugins-lisa-skills-project-ideation-skill-md`
+
+The fixture may be a tiny directory with:
+
+- `README.md` naming queue automation operators and their goals.
+- `.lisa.config.json` pointing `source` and `tracker` to GitHub.
+- `PROJECT_IDEATION_FIXTURE.md` listing the single persona, the single idea, and the expected
+  marker above.
+
+Invoke project ideation against that fixture with `prd_ready=true max_prds=1`. The fixture is valid
+only if the idea report selects the single expected idea and the PRD summary reports the expected
+marker.
+
+## Scripted verification
+
+Run the shipped harness after choosing the deterministic command for your runtime:
+
+```bash
+node plugins/lisa/scripts/project-ideation-idempotency-harness.mjs \
+  --repo CodySwannGT/lisa \
+  --marker "[lisa-project-ideation] idea=codyswanngt-lisa-exploratory-prd-run-ledger-queue-automation-operators-plugins-lisa-skills-project-ideation-skill-md" \
+  --command "codex exec '/lisa:project-ideation ./fixtures/project-ideation-idempotency prd_ready=true max_prds=1'" \
+  --memory-file "$CODEX_HOME/automations/<automation_id>/memory.md"
+```
+
+The harness performs the acceptance check in three phases:
+
+1. Run the deterministic ideation command once, then query open GitHub issues for the marker and
+   require exactly one match.
+2. Run the same command again, then require the open marker count to remain one.
+3. Move the automation memory file aside, run the command again, require the marker count to remain
+   one, and require the memory file to be recreated with marker, PRD URL, outcome, lifecycle role,
+   and source agreement fields. The original memory file is restored at the end.
+
+## Expected evidence
+
+Capture the harness JSON output as:
+
+- `[EVIDENCE: marker-count-one]` from the first and second marker-count checks.
+- `[EVIDENCE: memory-recreated-after-rerun]` from the missing-memory variant.
+
+The run passes only when all reported counts are `1`, the issue URL is the same across phases, and
+`memoryRecreated` and `memoryFieldsRecorded` are `true` when `--memory-file` is supplied.

package/plugins/lisa-copilot/skills/project-ideation/examples/public-external-inspiration.md

@@ -0,0 +1,22 @@
+# Public External Inspiration Example Output
+
+## What Already Exists
+- The host project already has a command catalog and source-authored skill files.
+- The host project can inspect public documentation pages without sign-in.
+- Existing verification can run through CLI commands and generated markdown artifacts.
+
+## Practical Ideas
+### 1. Public Pattern Checklist Import
+- User value: Maintainers can compare their command guidance against public best-practice pages without copying private or paid content.
+- Existing fit: Builds on the current docs and skill authoring workflow.
+- Data/source path: A public, no-login documentation URL supplied by the user, plus local `README.md` and skill files.
+- Practical slice: Generate a checklist of public patterns found in the external page and mark whether each is already represented locally.
+- Empirical verification: Run the ideation workflow against a fixed public URL and inspect the generated checklist.
+- Evidence: Generated markdown containing source URLs, matched local file paths, and unmatched public patterns.
+- Confidence: medium because public pages can change, but the source path is accessible and citeable.
+
+## Discovery Spikes
+- Automated freshness checks for public pages: needs a policy for when external pages may be re-fetched and cached.
+
+## Rejected / Not Practical Yet
+- Importing examples from a sign-in-only competitor workspace: rejected because the data source is not publicly obtainable.

package/plugins/lisa-copilot/skills/project-ideation/examples/unavailable-data-rejection.md

@@ -0,0 +1,22 @@
+# Unavailable Data Rejection Example Output
+
+## What Already Exists
+- The host project can read local source files, docs, scripts, and generated artifacts.
+- The host project does not expose customer analytics, private support tickets, or paid market datasets.
+
+## Practical Ideas
+### 1. Local Verification Gap Finder
+- User value: Maintainers can identify skills that describe empirical verification but do not name an evidence artifact.
+- Existing fit: Builds on local skill markdown files and existing unit tests.
+- Data/source path: Local `SKILL.md` files under the plugin source tree.
+- Practical slice: Scan skill files for verification sections and report entries that mention tests but no observable artifact.
+- Empirical verification: Run the scanner against a fixture skill with one missing evidence line.
+- Evidence: CLI output naming the fixture skill and the missing evidence field.
+- Confidence: high because the input is local and fully inspectable.
+
+## Discovery Spikes
+- Prioritize gaps by real-world usage: needs an obtainable telemetry source or a manually approved usage export before it can rank by frequency.
+
+## Rejected / Not Practical Yet
+- Recommend ideas from private customer support pain points: rejected because the missing source is a legitimate support-ticket export or configured support integration.
+- Recommend ideas from paid analyst reports: rejected because the missing source is a licensed data feed available to the agent at runtime.