@codyswann/lisa 2.61.1 → 2.62.1

package/plugins/src/base/skills/notion-access/SKILL.md

@@ -12,6 +12,7 @@ Single chokepoint for all Notion operations. Routes each op to a substrate, enfo
 
 ```text
 operation: read-page         id: <uuid>
+operation: create-page       parent_database_id: <uuid> properties: {...} [children: [...]]  # create a new page (e.g. a PRD row) in a database; children is optional — omit to create a page without initial block content
 operation: write-page        payload: {...}        # update page properties
 operation: archive-page      id: <uuid>
 operation: query-database    id: <uuid> filter: {...} sort: {...}
@@ -164,6 +165,7 @@ Substrate columns: try the column matching `$substrate` first. If that column is
 |---|---|---|
 | **Pages** | | |
 | `read-page id:<I>` | `mcp__claude_ai_Notion__notion-fetch` | `GET /v1/pages/<I>` |
+| `create-page parent_database_id:<D> properties:<P> [children:<arr>]` | `mcp__claude_ai_Notion__notion-create-pages` | `POST /v1/pages` body `{ "parent": { "database_id": "<D>" }, "properties": <P>, "children": <arr?> }` (children optional per Notion API) |
 | `write-page payload:<P>` | `mcp__claude_ai_Notion__notion-update-page` | `PATCH /v1/pages/<I>` body `{ "properties": {...}, "archived": true/false }` |
 | `archive-page id:<I>` | `mcp__claude_ai_Notion__notion-update-page` (with `archived: true`) | `PATCH /v1/pages/<I>` body `{ "archived": true }` |
 | `append-blocks page_id:<P> children:<arr>` | (no direct equivalent) | `PATCH /v1/blocks/<P>/children` body `{ "children": <arr> }` |

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

@@ -82,7 +82,7 @@ draft → ready → in_review → blocked | ticketed → shipped → verified
 
 (Default status values: `Draft` / `Ready` / `In Review` / `Blocked` / `Ticketed` / `Shipped` / `Verified`.)
 
-`verified` is the terminal status after `shipped`: it means the shipped product has been empirically checked against the PRD (set by `/lisa:verify-prd`, not by this intake skill). A failed post-ship verification reuses `blocked` rather than introducing a separate `verifying` / `verification-failed` status. Like `draft` and `shipped`, `verified` is **product-owned** — this intake skill never sets, clears, or otherwise touches it. See the "PRD-level verification vs ticket verification" section of the `prd-lifecycle-rollup` rule.
+`verified` is the terminal status after `shipped`: it means the shipped product has been empirically checked against the PRD (set by `/lisa:verify-prd`, not by this intake skill). A failed post-ship verification does **not** use `blocked`; `/lisa:verify-prd` re-opens the PRD `shipped → ticketed` and creates build-ready fix tickets that auto-build and trigger a re-verify (the self-healing loop), introducing no `verifying` / `verification-failed` status. Like `draft` and `shipped`, `verified` is **product-owned** — this intake skill never sets, clears, or otherwise touches it. See the "PRD-level verification vs ticket verification" section of the `prd-lifecycle-rollup` rule.
 
 This skill transitions `ready → in_review`, then `in_review → blocked` or `in_review → ticketed`, then (via the rollup phase 3f) `ticketed → shipped`. It never touches `draft` or `verified` — those statuses are owned by product (`verified` is set by `/lisa:verify-prd` after empirical PRD-level acceptance). The `shipped` status is set by this skill's **rollup phase (3f)** when, and only when, the PRD's generated top-level work is all terminal — per the `prd-lifecycle-rollup` rule; product may also set it by hand. Rollup never advances a PRD to `shipped` on partial completion, and never archives a PRD page unless `notion.rollup.closeOnShipped` is configured `true` (default `false` → set `$SHIPPED`, leave the page active).
 
@@ -298,6 +298,16 @@ The set of **required** children for the all-terminal check is the top-level chi
 
 This phase implements exactly one PRD-lifecycle hop — `$TICKETED → $SHIPPED` — and the optional config-gated archive that follows it. All terminal-state semantics, the generated-top-level-work boundary, and the dedupe-by-child-ref idempotency come from the `prd-lifecycle-rollup` rule; this skill is its Notion implementation, not a second source of truth.
 
+#### 3g. PRD verification dispatch (close the loop on shipped PRDs)
+
+`shipped` and `verified` are distinct facts about a PRD (see the `prd-lifecycle-rollup` rule's "PRD-level verification vs ticket verification" and "Closing the loop" sections). Rollup (3f) only reaches `$SHIPPED`; the `shipped → verified` (pass) / `shipped → ticketed` (fail) hops are owned by `/lisa:verify-prd`. This phase **closes that loop** by dispatching the initiative-level acceptance gate for shipped PRDs. It never performs the verification transition itself — the "never sets the verification outcome" invariant holds: `lisa:verify-prd`, not this skill, sets `verified` (or, on failure, re-opens the PRD to `ticketed`).
+
+Re-query the PRDs currently in the `$SHIPPED` status via `lisa:notion-access` `operation: query-database` filtered on `$STATUS_PROP = $SHIPPED`. Pick the **first** one and invoke `lisa:verify-prd <PRD-page-url>`. Process **one shipped PRD per cycle** — `lisa:verify-prd` is a heavy full flow (spec-conformance + empirical verification + fix-issue creation), so it is bounded exactly like the single-ready-PRD claim in Phase 3; the scheduler drains the rest.
+
+**Per-cycle combined bound:** each scheduler cycle dispatches at most one ready PRD (the Phase 3 single-ready-PRD claim) **and** at most one shipped PRD for verification (this Phase 3g dispatch), for a maximum of two PRD operations per cycle. Ready intake runs first (Phase 3), then shipped verify (Phase 3g).
+
+`lisa:verify-prd` owns the outcome: on a CONFORMS verdict with all empirical checks passing it transitions `$SHIPPED → verified` and posts evidence; on a conformance miss or a failing/unavailable check it **re-opens the PRD `$SHIPPED → ticketed`** (never `blocked`) and creates **build-ready** fix tickets registered as the PRD's generated work, then posts a failure report — the fix tickets auto-build, rollup (3f) re-ships the PRD once they are terminal, and a later cycle re-verifies (the self-healing loop). Either branch moves the PRD out of `$SHIPPED`, so it is not re-picked this cycle; a PRD whose generated work is not actually terminal is guard-stopped by `lisa:verify-prd` (left `$SHIPPED`) — that is verify-prd's gate, not this skill's. A PRD archived on ship (`notion.rollup.closeOnShipped = true`) is out of the open verification queue. This phase, like 3f, is **behaviorally identical across all four intake skills** (`github-prd-intake`, `linear-prd-intake`, `notion-prd-intake`, `confluence-prd-intake`) — only the `$SHIPPED` query surface differs; keep them aligned. Record the dispatched PRD + verify-prd's verdict in the summary.
+
 ### Phase 4 — Summary report
 
 After processing the single selected PRD, emit a summary:

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

@@ -0,0 +1,107 @@
+---
+name: notion-write-prd
+description: "Creates or idempotently updates a PRD as a page in the configured Notion PRD database, setting the lifecycle Status property to the draft value by default (or the ready value when initial_role is ready so lisa:notion-prd-intake auto-claims it). The Notion PRD-source writer behind lisa:prd-source-write. Dedupes by a stable marker embedded in the page (matched by marker, never by title). All Notion access goes through lisa:notion-access — never call the Notion API or MCP directly."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# Write Notion PRD: $ARGUMENTS
+
+Create (or update) a PRD page in the configured Notion PRD database. Invoked by
+`lisa:prd-source-write` when `source = notion`; do not call directly from a vendor-neutral caller.
+**All Notion operations go through `lisa:notion-access`** (the access chokepoint) — never curl the
+Notion API or call a `mcp__*notion*` tool yourself.
+
+`$ARGUMENTS` carries the `lisa:prd-source-write` spec: `title`, `body` (full PRD markdown),
+`initial_role` (`draft` | `ready`, default `draft`), `dedupe_key`, `marker`, optional `source_ref`.
+
+## Phase 1 — Resolve database + Status vocabulary
+
+```bash
+read_g() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv:-$2}}"; }
+PRD_DB=$(read_g '.notion.prdDatabaseId' '')
+[ -z "$PRD_DB" ] && { echo "Error: notion.prdDatabaseId not set in .lisa.config.json."; exit 1; }
+STATUS_PROP=$(read_g '.notion.statusProperty' 'Status')
+# Resolve the FULL PRD Status vocabulary from config (never hard-code) so the past-ready check is
+# correct even when a project renamed any Status value.
+DRAFT=$(read_g '.notion.values.draft' 'Draft')
+READY=$(read_g '.notion.values.ready' 'Ready')
+IN_REVIEW=$(read_g '.notion.values.in_review' 'In Review')
+BLOCKED=$(read_g '.notion.values.blocked' 'Blocked')
+TICKETED=$(read_g '.notion.values.ticketed' 'Ticketed')
+SHIPPED=$(read_g '.notion.values.shipped' 'Shipped')
+VERIFIED=$(read_g '.notion.values.verified' 'Verified')
+# "Progressed past ready" set (never down-rank): the resolved in_review/blocked/ticketed/shipped/verified.
+PROGRESSED=("$IN_REVIEW" "$BLOCKED" "$TICKETED" "$SHIPPED" "$VERIFIED")
+```
+
+Resolve the target Status value from `initial_role`: `ready` → `$READY`, otherwise `$DRAFT`.
+
+## Phase 2 — Dedupe by marker (search before create)
+
+The `marker` is embedded in the page (as the first body block). Find an existing PRD page in the DB
+carrying it — match the marker, **never** the title:
+
+1. `lisa:notion-access` `operation: search query: "<marker>"` (Notion indexes page content).
+2. Filter results to pages whose parent is `$PRD_DB`. If `source_ref` was passed, target that page
+   directly and skip the search.
+3. If a matching page is found, this is an **update** — reuse it. If none is found, **create**.
+   Note: Notion search is eventually consistent; if a just-created page isn't found yet, the marker
+   still lives in the page so a later run will dedupe — surface "dedupe degraded (search lag)" rather
+   than silently creating a duplicate when uncertain.
+
+## Phase 3 — Create or update
+
+**Markdown → Notion blocks (conversion boundary).** Convert the PRD markdown to Notion block objects:
+`#`/`##`/`###` → `heading_1/2/3`, paragraphs → `paragraph`, `-`/`*` → `bulleted_list_item`, `1.` →
+`numbered_list_item`, fenced code → `code`. The Notion API caps a single request at **100 blocks**
+and ~2000 characters of rich text per block: split long paragraphs across blocks, and if the PRD
+exceeds 100 blocks, create the page with the first ≤100 blocks then add the remainder with batched
+`operation: append-blocks` calls (≤100 each). When the MCP substrate is active, `create-page` may
+accept the markdown content directly (it performs this conversion) — prefer that; the explicit block
+conversion is the curl-substrate path.
+
+**Marker normalization (both paths).** The page must always carry **exactly one** marker. On CREATE
+the marker is the first body block; on UPDATE never remove it. Never write a markerless page.
+
+**CREATE:**
+
+1. Build the page body as Notion blocks per the conversion above: the **first block is the marker**
+   (a paragraph/callout containing `<!-- $MARKER -->`), then the converted PRD blocks.
+2. Invoke `lisa:notion-access` `operation: create-page` with:
+   ```json
+   { "parent_database_id": "<PRD_DB>",
+     "properties": { "<title-prop>": { "title": [{ "text": { "content": "<TITLE>" } }] },
+                     "<STATUS_PROP>": { "status": { "name": "<ROLE_VALUE>" } } },
+     "children": [ <marker block>, <PRD body blocks> ] }
+   ```
+   Use the DB's actual title property name (read it via `operation: read-database id: <PRD_DB>` if
+   unknown) and the correct property type for `$STATUS_PROP` (`status` vs `select`).
+3. Capture the returned page id + URL.
+
+**UPDATE** (existing page or `source_ref`):
+
+1. Set the Status to the resolved role via `lisa:notion-access` `operation: write-page payload: { "id": "<page-id>", "properties": { "<STATUS_PROP>": { "status": { "name": "<ROLE_VALUE>" } } } }` — **unless** the page's current Status is in the resolved `${PROGRESSED[@]}` set (already past `ready`), in which case leave the Status and report `reused (already past ready)`.
+2. Refresh the canonical spec, not append-only notes: keep the existing marker block, then make the
+   managed PRD body current — archive the previously generated body blocks below the marker
+   (`operation: archive-page` is page-level, so for blocks delete via the blocks API through
+   `notion-access` or, where block deletion isn't available, replace their text in place) and
+   `operation: append-blocks` the regenerated blocks. Do not duplicate the whole spec as a dated
+   note, and never drop the marker.
+
+## Phase 4 — Return
+
+```yaml
+ref: "<notion-page-id>"
+url: "<page url>"
+role: draft | ready          # (or the page's current Status role when reused past ready)
+marker: "<MARKER>"
+outcome: created | reused
+```
+
+## Rules
+
+- All access via `lisa:notion-access`; never touch the Notion API/MCP directly.
+- Match dedupe by marker, never by title.
+- Never down-rank a PRD whose Status is already past `ready`.
+- Resolve the Status vocabulary from config (`notion.statusProperty`, `notion.values.*`) — never
+  hardcode value names.

package/plugins/src/base/skills/prd-source-write/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: prd-source-write
+description: "Vendor-neutral wrapper for creating (or idempotently updating) a PRD in the configured PRD source. The PRD-side sibling of lisa:tracker-write. Resolves `source` from .lisa.config.local.json first (then .lisa.config.json — local overrides global) and dispatches to lisa:notion-write-prd, lisa:confluence-write-prd, lisa:github-write-prd, or lisa:linear-write-prd. Callers (notably lisa:research) MUST invoke this skill instead of a vendor PRD writer directly — that is what makes the PRD source switchable per project. Accepts an `initial_role` of `draft` (default) or `ready` so a freshly created PRD either waits for human promotion or is immediately picked up by lisa:intake; and a stable dedupe marker so re-runs reference the existing PRD instead of creating a duplicate. The PRD lives in the source — there is no separate document artifact."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# PRD Source Write: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured PRD `source` and delegates to the matching vendor PRD
+writer, which owns the concrete create/update, the lifecycle-role application, and the marker-based
+dedupe. This skill only routes — it never talks to a source API itself.
+
+See the `config-resolution` rule for the full configuration schema and the PRD lifecycle roles.
+
+## Input contract
+
+Callers pass a single structured spec:
+
+```yaml
+operation: create_or_update          # the only operation; create unless the marker already exists
+title: "<PRD title>"
+body: "<full PRD markdown — the entire spec>"
+initial_role: draft | ready          # default: draft. ready = picked up by lisa:intake's PRD scan
+dedupe_key: "<stable-key>"           # e.g. project-ideation's idea key
+marker: "[lisa-project-ideation] idea=<stable-key>"   # embedded in the PRD body for dedupe
+origin: { tool: project-ideation | research | manual }
+source_ref: "<optional existing PRD ref to force an update>"
+```
+
+`initial_role` semantics are uniform across vendors (the role STRINGS resolve per vendor from
+`config-resolution`):
+
+- **`draft`** (default) → the PRD is created in the source's `draft` PRD role. It waits for a human
+  (or a later `ready` promotion) before any intake claims it.
+- **`ready`** → the PRD is created in the source's `ready` PRD role (`prd-ready`), so the PRD-side of
+  `lisa:intake` / the `*-prd-intake` scanner auto-claims it on the next cycle.
+
+There is no "omitted = legacy behavior" mode (unlike the ticket-side `build_ready`): there was no
+prior PRD-source-write behavior to preserve, so omitted means `draft`.
+
+## Workflow
+
+1. **Resolve the source.** Read `.lisa.config.local.json` first (if present), then
+   `.lisa.config.json`. Local overrides global per key. Use `jq` — never hand-parse JSON.
+
+   ```bash
+   local_source=$(jq -r '.source // empty' .lisa.config.local.json 2>/dev/null)
+   global_source=$(jq -r '.source // empty' .lisa.config.json 2>/dev/null)
+   source="${local_source:-${global_source}}"
+   if [ -z "$source" ]; then
+     echo "Error: 'source' is not set in .lisa.config.json. A PRD source (notion / confluence / github / linear) is required to create a PRD. Run /lisa:setup:notion (or :confluence, :github, :linear)." >&2
+     exit 1
+   fi
+   ```
+
+2. **Validate the value and dispatch** (pass the spec verbatim):
+
+   - `notion` → confirm `notion.workspaceId` and `notion.prdDatabaseId` are present, then invoke
+     `lisa:notion-write-prd`.
+   - `confluence` → confirm `atlassian.cloudId` and (`confluence.spaceKey` or
+     `confluence.parents.draft`/`.ready`) are present, then invoke `lisa:confluence-write-prd`.
+   - `github` → confirm `github.org` and `github.repo` are present, then invoke
+     `lisa:github-write-prd`.
+   - `linear` → confirm `linear.workspace` (and team for project placement) is present, then invoke
+     `lisa:linear-write-prd`.
+   - `jira` → **stop and fail loudly**: `"source=jira is not a supported PRD source — config-resolution defines no JIRA PRD lifecycle roles. Use notion / confluence / github / linear, or set source accordingly."` (JIRA is a destination tracker, not a PRD source.)
+   - Any other value (including `file`) → stop and report: `"Unknown PRD source '<value>'. Expected one of: notion, confluence, github, linear."`
+
+3. **Surface the vendor writer's output unchanged.** It returns the created/reused PRD ref + URL,
+   the applied role (`draft`/`ready`), the dedupe marker, and whether it was created or reused.
+   Downstream callers (research, project-ideation) parse this — do not paraphrase.
+
+## Rules
+
+- Never bypass dispatch — a vendor-neutral caller calling a `*-write-prd` skill directly defeats the
+  per-project source switch (exactly the `tracker-write` discipline, mirrored).
+- Never accept a source outside `{notion, confluence, github, linear}`. `jira` and `file` fail loudly.
+- Never mutate the spec between layers. The vendor writers define their own create/dedupe contract.
+- Never invent a PRD lifecycle role string — resolve every role from `config-resolution` per vendor.
+- Idempotency is the vendor writer's job (marker search before create); this shim only routes.

package/plugins/src/base/skills/project-ideation/SKILL.md

@@ -1,131 +1,234 @@
 ---
 name: project-ideation
-description: "Generate practical, verifiable product or workflow ideas for the current host project. Inspects the host project (code, docs, scripts, data sources, current surfaces), optionally compares against external public products, and returns a prioritized idea report. Every build-ready idea must pass a practicality gate (an obtainable data/source path the project can plausibly implement) and an empirical verification gate (a user-observable outcome the agent can verify itself). Ideas that fail either gate are demoted to Discovery Spikes or Rejected / Not Practical Yet. Invoke for prompts like 'generate feature ideas for this project', 'looking at <external product>, what should we add here?', 'suggest practical improvements we can verify ourselves', or 'what should this app do next given the data we can get?'. Vendor- and stack-agnostic: works for web apps, APIs, CLIs, wiki systems, data pipelines, and internal tools. Does not create tickets or mutate the project — it produces a decision-ready report the user can later hand to a Research, Plan, or Implement flow."
+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
 
-Produce a decision-ready idea report for the host project described in `$ARGUMENTS` (or the current working directory if no target is given). The report separates ideas that are **build-ready now** from ideas that need a **discovery spike** and ideas that are **rejected / not practical yet**.
+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 **filtering**, not brainstorming volume. An attractive idea you cannot ground in obtainable data and cannot verify yourself is not a recommendation — it is noise. Demote it honestly.
+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.
 
-## When to use
+## 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`).
+- **`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`.
 
-Trigger this skill on prompts such as:
+## When to use
 
-- "generate feature ideas for this project"
+- "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"
-- "what should this app do next given the data we can get?"
-- "what high-value features could we add to <repo>?"
 
-Do **not** use this skill to create tickets, write a PRD, or change code. It stops at a report. The user can then ask Lisa to turn one or more ideas into a PRD (`/lisa:research`), a plan (`/lisa:plan`), or an implementation (`/lisa:implement`).
+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 appear under **Practical Ideas** if it passes BOTH gates. Otherwise demote it.
+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 are actually available: existing code, an existing data model, a route/command/UI surface, a public or already-integrated API, a scrapeable public page, an existing user input, a local database, or documented integrations. You must be able to name the specific source and how the data is obtained. "We could probably get the data somehow" fails the gate.
-2. **Empirical verification gate.** You can personally confirm the resulting behavior by using the software or workflow — running the CLI, hitting the API, loading the page, querying the database, or inspecting a generated artifact — and capture a concrete evidence artifact. Saying "tests could be written later" does **not** satisfy this gate. Quality gates (tests, lint, typecheck, build) are prerequisites, never proof that an idea works.
+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.
 
-If an idea fails the practicality gate → it goes under **Rejected / Not Practical Yet** (or **Discovery Spikes** if a bounded probe could make it practical), with the missing data/source/access named explicitly.
-
-If an idea fails only the empirical verification gate → it goes under **Discovery Spikes** (define the missing proof) or stays as a strategic note, never as a build-ready recommendation.
+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** — read the manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, etc.) and any `.lisa.config.json`.
-- **Docs and specs** — `README`, `docs/`, `wiki/`, architecture notes, ADRs.
-- **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 already supplies.
-- **Available data sources and ingestion/scraping paths** — integrated APIs, public datasets, scrapeable public pages, local databases, event streams.
-- **Existing verification tooling and empirical paths** — how a human currently observes that the software works (a local dev server, a CLI you can run, a seedable DB, a dry-run mode).
+- **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.
 
-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**:
+## Step 5 — Rank and select the PRD creation set
 
-- **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.
+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 2 — Optional external / public-source inspection
+## Step 6 — Create a PRD per selected idea (via lisa:research)
 
-Only when the user references an external product, website, public dataset, competitor, or example:
+For each idea in the creation set, invoke `/lisa:research` with:
 
-- Inspect **public, no-login** surfaces only. Do not assume sign-in, credentials, or paid access.
-- Preserve every **source URL** you used so each informed idea can cite it.
-- If the runtime has no browser or web capability, mark that research source as **unavailable** and proceed with host-project-only ideas (document the fallback rather than fabricating findings).
+- 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.
 
-The external source is **inspiration, not a domain you bake in**. Keep the workflow reusable across any Lisa-managed repository.
+`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.
 
-## Step 3 — Generate ideas, then filter through the gates
+### Dedupe marker (stable, never title-based)
 
-Brainstorm broadly, then run every idea through both gates from the top of this skill. For each surviving idea, build a **feasibility card** containing at least:
+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.
 
-- **User/persona value** — why the host project's user would care.
-- **Existing fit** — the current route / API / CLI / model / doc / surface it builds on.
-- **Data/source required** — the specific data the idea consumes.
-- **How the data can be obtained or scraped** — the concrete accessible path (endpoint, query, public page, existing input).
-- **Known source limitations or terms constraints** — rate limits, robots/ToS, staleness, missing fields.
-- **Smallest practical implementation slice** — the minimal useful version.
-- **Empirical verification steps** — what you (the agent) will do against the running app / API / CLI / DB / artifact to confirm it works.
-- **Evidence artifact** — the screenshot, curl output, CLI output, DB row, or generated file the verifier captures.
-- **Confidence** — high | medium | low, with the reason.
+## Step 7 — Output (no report file)
 
-## Step 4 — Rank and assemble the report
+Emit two distinct in-session sections (do not write a report file):
 
-Rank build-ready ideas by **user value, feasibility, verification clarity, and project fit**. Emit the report in this shape:
+1. **Idea report** (the audit trail):
+   ```markdown
+   ## Personas Derived From Evidence
+   - <name> — goals; pains; evidence (files/docs/tables/releases); confidence
 
-```markdown
-## What Already Exists
-- <current surfaces, data, commands, or workflows discovered — so duplicates are not re-proposed>
+   ## What Already Exists
+   - <current surfaces, data, commands, workflows — so duplicates aren't re-proposed>
 
-## Practical Ideas
-### 1. <Idea name>
-- User value: <why the host project's user would care>
-- Existing fit: <current route/API/CLI/model/doc/surface it builds on>
-- Data/source path: <specific accessible source or scrape/API path>
-- Practical slice: <smallest useful version>
-- Empirical verification: <steps the agent can perform against the running software>
-- Evidence: <screenshot, curl output, CLI output, DB row, generated file, etc.>
-- Confidence: high|medium|low with reason
+   ## Practical Ideas
+   ### 1. <Idea name>  (persona: <persona(s)>)
+   - Persona value · Existing fit · Data/source path · Practical slice · Empirical verification ·
+     Evidence · Confidence
 
-## Discovery Spikes
-- <ideas that need proof of data, access, or verification before they can be build-ready — name the missing proof>
+   ## Discovery Spikes
+   - <ideas needing proof of data/access/verification — name the missing proof — tagged by persona>
 
-## Rejected / Not Practical Yet
-- <attractive ideas rejected because data, access, legality, or verification is not available — name what is missing>
-```
+   ## 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 **What Already Exists** section so the user can tell genuinely new ideas from duplicates, and so the report records existing capabilities. Always include both the **Discovery Spikes** and **Rejected / Not Practical Yet** sections (even if empty) so the user can see what was deliberately filtered out and why.
+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 sign-in-only ideas** unless the host project already supports sign-in *and* credentials are available.
-- **No private-data assumptions** — do not premise an idea on data the project cannot legitimately obtain.
-- **No manual-data-only requirements** unless the user explicitly accepts manual curation.
-- **No paid-API or non-scrapeable-source ideas** in the build-ready list — demote them with the blocker named.
-- **Tests, lint, typecheck, and build are not the empirical verification plan.** They are prerequisites; the verification plan must observe user-facing behavior.
-- **Do not auto-create tracker tickets or mutate the host project.** Produce the report only; planning and implementation are separate, user-invoked flows.
-- **Do not add a new verification or browser-automation framework** when the host project already has one — reuse it.
-- **Do not overfit to a source example.** Keep the workflow project-agnostic and reusable.
+- **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
 
-When the user wants to act on an idea, preserve its feasibility and verification card as the source artifact so downstream flows inherit the evidence:
+The created PRDs flow straight into the lifecycle:
 
-- Turn an idea into a PRD → `/lisa:research`
-- Turn a PRD into tickets → `/lisa:plan`
-- Build a ticket end-to-end → `/lisa:implement`
-- Lock in the verification so it never regresses → `/lisa:codify-verification`
+- 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 when composing reports:
+Use the markdown examples in `examples/` as shape references for the idea report:
 
-- `host-project-only.md` shows ideas grounded only in the current repository.
-- `public-external-inspiration.md` shows how public, no-login external sources can inspire ideas without becoming hidden requirements.
-- `unavailable-data-rejection.md` shows how to name missing private, paid, or unavailable data sources when demoting ideas.
-- `evidence-card-format.md` shows the required evidence fields every Practical Idea card must carry.
+- `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.