From 495d85f31477ff280988f0a40bc861edff829ae6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Atam=C3=A1n=20Vega?= Date: Wed, 16 Sep 2026 18:10:09 +0100 Subject: [PATCH 1/3] =?UTF-8?q?feat(po):=20plan-definition=20=E2=80=94=20g?= =?UTF-8?q?uided=20discovery=20phase=20upstream=20of=20plan-backlog=20(#73?= =?UTF-8?q?,=20v1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the most upstream step of the PO workflow: define the problem before turning it into a backlog. A guided, Socratic pass frames the problem (users, outcome, why-now, constraints, success metrics, risks, non-goals) with proposed answers to confirm/adjust, explores 2–4 solution directions with trade-offs, and produces an approved product definition — a definition doc, not tickets. Renders as a navigable artifact on hosts that support it (reusing #74's doctrine), Markdown elsewhere. The definition feeds plan-backlog, whose framing step is now lighter when a definition is handed in (confirm, don't re-derive). Ships the same trio as plan-backlog: - skills/plan-definition/SKILL.md — portable playbook (all hosts) - commands/plan-definition.md — Claude Code guided command - agents/plan-definer.md — discovery orchestrator (intake + draft engine) Facilitate-never-decide, approval-gated, no fabrication. v1 for team review (open design questions left to refine in #73). Full flow: define → backlog → ticket → PR → follow-ups. Bundle rebuilt (13 skills), version bumped, README + CHANGELOG updated. Kit → 0.19.13. Co-Authored-By: Claude Opus 4.8 --- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 1 + README.md | 8 +- agents/plan-definer.md | 45 +++++++++++ commands/plan-definition.md | 22 +++++ .../.codex-plugin/plugin.json | 2 +- .../.cursor-plugin/plugin.json | 2 +- plugins/fullstack-dev-kit/plugin.json | 2 +- .../skills/plan-backlog/SKILL.md | 2 + .../skills/plan-definition/SKILL.md | 81 +++++++++++++++++++ skills/plan-backlog/SKILL.md | 2 + skills/plan-definition/SKILL.md | 81 +++++++++++++++++++ 12 files changed, 245 insertions(+), 5 deletions(-) create mode 100644 agents/plan-definer.md create mode 100644 commands/plan-definition.md create mode 100644 plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md create mode 100644 skills/plan-definition/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index dccc252..3e44480 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow kit for any tech stack. Fetch a user story from your tracker (Jira, Linear, GitHub Issues, Azure DevOps) and any linked Figma designs, implement with plan approval, enforce >95% coverage and a security pass, generate e2e tests, open the PR, fix review findings, and move the ticket to review.", "license": "Apache-2.0", "homepage": "https://github.com/theam/claude-dev-kit", diff --git a/CHANGELOG.md b/CHANGELOG.md index 82b83e3..e6d3fdd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ a release is only "live" for users once that is bumped and published. ## [Unreleased] ### Added +- **`plan-definition` — a guided discovery/definition phase upstream of `plan-backlog` (#73).** When an idea is still a rough spark (even a one-liner), this new step *defines the problem* before any backlog exists: a guided, Socratic pass that frames the problem (users, outcome, why-now, constraints, success metrics, risks, non-goals) with proposed answers to confirm/adjust, explores **2–4 solution directions** with trade-offs, and produces an approved **product definition** — a definition doc, **not tickets**. On hosts with artifacts it renders as a navigable artifact (reusing #74's doctrine); Markdown elsewhere. The definition then feeds `plan-backlog`, whose framing step is **lighter** when a definition is handed in (confirm, don't re-derive). Ships as the portable `plan-definition` skill plus a Claude `/plan-definition` command and `plan-definer` agent — same trio shape as `plan-backlog`. Facilitate-never-decide, approval-gated, no fabrication. Full flow: **define → backlog → ticket → PR → follow-ups**. From @santielizondo's idea; v1 for team review. Kit → **0.19.13**. - **Rich review artifact for `plan-backlog` (#74).** On hosts that support artifacts (Claude Code / claude.ai), a non-trivial backlog draft is now presented as a **navigable artifact** at the review step — collapsible epics → stories with acceptance criteria, labels, sizing and dependencies, plus search/filter and a table of contents — so a large backlog is easy to scan and drill into. The in-chat draft + approval question stay the gate (the artifact is a review aid, not a substitute); portable hosts (Codex/Cursor/Copilot) keep Markdown. From @santielizondo's idea. Kit → **0.19.12**. ### Changed diff --git a/README.md b/README.md index dd9013d..e1489df 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,12 @@ Give the `coding-agent` a user story ID from your tracker and it orchestrates th ## From idea to backlog (product owners) -Before there's a ticket, **`plan-backlog`** turns an idea or brief — chat text, a PDF, a Word doc, an artifact — into a well-formed backlog (epics, INVEST user stories with acceptance criteria, sub-tasks, dependencies) and **creates it in your tracker after you approve it**. It's discovery-first (mirrors your team's existing hierarchy and conventions rather than imposing one) and speaks Jira / Linear / GitHub Issues / Azure DevOps via the same adapters. The stories it creates feed straight into `/work-story` — closing the loop **idea → backlog → ticket → PR**. +Before there's a ticket, **`plan-backlog`** turns an idea or brief — chat text, a PDF, a Word doc, an artifact — into a well-formed backlog (epics, INVEST user stories with acceptance criteria, sub-tasks, dependencies) and **creates it in your tracker after you approve it**. It's discovery-first (mirrors your team's existing hierarchy and conventions rather than imposing one) and speaks Jira / Linear / GitHub Issues / Azure DevOps via the same adapters. The stories it creates feed straight into `/work-story` — closing the loop **define → backlog → ticket → PR**. It's **guided by default** — it elaborates progressively (framing → epics → stories), offering alternatives and asking for your decision at each level, so the definition stays yours; add `--quick` for a one-shot draft. On Claude, a non-trivial backlog is shown as a **navigable artifact** for review (approval still happens in the chat). In **Claude Code**, run `/plan-backlog [--quick]`. On **Codex / Cursor / Copilot**, invoke the `plan-backlog` skill directly. +**Even earlier — defining the problem.** When the idea is still a rough spark, **`plan-definition`** runs the discovery phase *before* the backlog: a guided, Socratic pass that frames the problem (users, outcome, why-now, constraints, success metrics, non-goals), explores 2–4 directions with trade-offs, and produces an approved **product definition** — a definition doc, not tickets. That definition then feeds `plan-backlog`, whose framing is lighter because the problem is already defined. Run `/plan-definition ` (or invoke the `plan-definition` skill). It facilitates your thinking; it never decides the product for you. + ## Quality gates **Always apply** (regardless of stack or test setup): @@ -222,6 +224,7 @@ The kit runs `dev-kit-setup`: it detects your tracker, discovers what it can (si | You want to… | Type | |---|---| | Work a story end to end (current window) | `/fullstack-dev-kit:work-story PROJ-1234` | +| Define a problem before there's a backlog | `/fullstack-dev-kit:plan-definition ` | | Draft & create a backlog from an idea/brief | `/fullstack-dev-kit:plan-backlog ` | | Prepare a story worktree + new VS Code window | `/fullstack-dev-kit:launch-story PROJ-1234` | | Unattended run (no plan gate — pipelines only) | append `--auto-approve` | @@ -260,6 +263,7 @@ Full **`/work-story `** flow is ticket-first (it fetches the story and m | Component | Type | Purpose | |---|---|---| | `coding-agent` | agent | Orchestrator: story ID → PR → updated ticket, with plan-approval gate | +| `plan-definer` | agent | Product-owner discovery orchestrator: spark → approved product definition (no tickets) | | `backlog-planner` | agent | Product-owner orchestrator: idea/brief → approved backlog created in the tracker | | `pr-reviewer` | agent | High-signal diff review: correctness, contract drift, security, tests | | `pr-fixer` | agent | Resolves review/CI findings, re-verifies gates, pushes | @@ -269,6 +273,7 @@ Full **`/work-story `** flow is ticket-first (it fetches the story and m | `dev-kit-setup` | skill | First-use bootstrap: detects the tracker, writes `.claude/dev-kit.json` | | `issue-fetch` | skill | Ticket + acceptance criteria + comments (Jira/Linear/GitHub/Azure) | | `issue-update` | skill | Comment PR + evidence on the ticket, transition to review | +| `plan-definition` | skill | Spark → guided discovery → approved product definition (feeds `plan-backlog`) | | `plan-backlog` | skill | Idea/brief → well-formed backlog, created in the tracker after approval | | `follow-ups` | skill | Track a story's loose ends as linked tickets, after approval | | `figma-fetch` | skill | Frame hierarchy + text content from a Figma URL | @@ -279,6 +284,7 @@ Full **`/work-story `** flow is ticket-first (it fetches the story and m | `fix-pr` | skill | Playbook: findings → fixes → re-verified gates → push | | `instructions/` | rules | Always-on, language-agnostic: secure coding, testing standards | | `/work-story` | command | Entry point: `/work-story PROJ-1234` | +| `/plan-definition` | command | Entry point: `/plan-definition ` (define before backlog) | | `/plan-backlog` | command | Entry point: `/plan-backlog ` | | `/launch-story` | command | Creates a story worktree and opens a new VS Code window on it | diff --git a/agents/plan-definer.md b/agents/plan-definer.md new file mode 100644 index 0000000..2645d48 --- /dev/null +++ b/agents/plan-definer.md @@ -0,0 +1,45 @@ +--- +name: plan-definer +description: Product-owner discovery orchestrator. Given a spark (an idea, even a one-liner, in any form), it reads the source, frames the problem through guided questions, explores 2–4 solution directions with trade-offs, and produces an approved product definition that feeds plan-backlog. Facilitates the PO's thinking; never decides for them. Creates no tickets. +model: inherit +skills: + - dev-kit-setup + - figma-fetch + - plan-definition +--- + +You are the discovery/definition orchestrator for the **product-owner** persona. Your input is a spark — an idea, brief, or one-liner; your output is an approved **product definition** that feeds `plan-backlog`. You **create nothing downstream** — no backlog, no tickets. That is `plan-backlog`'s job. + +**Facilitate, discovery-first.** You draw the definition out of the PO with questions and grounded proposals — you never decide the product for them. The **`plan-definition` skill holds the full playbook** — follow it exactly. + +**The guided flow is interactive**, so it is conducted by your caller in the main conversation (the PO decides at each step, and can't see your output mid-run). **You are the engine for intake reading and for assembling the definition draft.** If invoked for a guided run, do the intake/framing groundwork and return the questions, candidate answers, and direction options for the caller to put to the PO — don't try to run the per-step decisions yourself. + +## Workflow (in order — the approval gate is mandatory) + +### 1. Intake +- Read the source spark in whatever form it arrives (chat text, a one-liner, a PDF, a Word doc, an artifact, a Confluence link). A thin spark is expected — you draw the rest out in framing, never invent it. +- If it references Figma/FigJam (`figma.com/(design|file|board)/…`), run `figma-fetch` for context (FigJam is read-only context in v1). + +### 2. Frame the problem — WAIT FOR THE PO +Draw out the definition Socratically (§2 of the skill): users/non-users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals. For each, propose a candidate answer **grounded in the intake** and let the PO confirm or adjust. It's fine to leave items as open questions. + +### 3. Directions & trade-offs +Propose **2–4 solution directions** with trade-offs (cost, risk, time-to-value, reversibility), recommend one with a reason, and wait for the PO to choose or refine. + +### 4. Definition — WAIT FOR APPROVAL +Assemble the definition per the skill's template (problem statement, target users, goals & non-goals, success metrics, chosen direction + alternatives considered, key decisions, open questions; optional sections where warranted). + +**No definition is finalized, and nothing downstream happens, until the PO explicitly approves.** + +**If you are running as a subagent** (your caller relays to the user): return the FULL draft definition (or the framing questions / direction options, depending on the stage) as your result and stop — do not ask for approval yourself and do not create anything. Your caller shows it to the PO and resumes you with the decision. + +**If you are running in the main conversation**: present the definition and wait for explicit approval. On a host with artifacts, you may also render a non-trivial definition as a navigable artifact for review (per the skill), but the in-chat summary + question stay the gate. + +### 5. Handoff +On approval, hand the definition to `plan-backlog` as its input (its framing step is then lighter). If the PO wants it persisted, offer to save it as `docs/definitions/.md`. **Create no tickets.** + +## Guardrails +- Facilitate, never decide: offer alternatives and ask for the PO's decision at each step. +- Never fabricate the problem, users, metrics, or direction — ground everything in the intake plus the PO's answers. +- No backlog and no tickets here — this step stops at an approved definition. +- Watch for secrets/PII in the source material; don't copy them into the definition. diff --git a/commands/plan-definition.md b/commands/plan-definition.md new file mode 100644 index 0000000..280c834 --- /dev/null +++ b/commands/plan-definition.md @@ -0,0 +1,22 @@ +--- +description: Turn a spark (an idea, even a one-liner) into a clear product definition through a guided discovery phase, then hand it to plan-backlog. Facilitate, never decide. Usage - /plan-definition +--- + +Turn the spark given in the arguments into a product definition: $ARGUMENTS + +Follow the `plan-definition` skill. This is the **most upstream** step — it *defines* the problem before `plan-backlog` turns it into a backlog. It produces a **definition doc, never tickets.** + +Rules: + +- If the arguments contain no idea or source, ask for one — but a **one-liner is a valid start** (this step is for vague sparks; you draw the rest out with questions). Accept pasted text, a path to a file (PDF / Word / Markdown), or a URL / artifact / Figma-FigJam link. +- **Facilitate, never decide.** Ask, propose candidate answers grounded in the intake, and let the PO confirm or adjust at each step. + +## Run it in THIS conversation (guided, interactive) + +The definition flow is interactive, so conduct it in the main conversation — the PO makes a decision at each step (do not hand it to a context-isolated subagent, whose output the user can't see mid-run). You may delegate **intake reading** (e.g. a large PDF/Figma fetch) to the `plan-definer` subagent to keep this context clean. + +1. **Intake** — read the spark in whatever form it arrives (§1 of the skill). If it references Figma/FigJam, run `figma-fetch` for context. +2. **Frame the problem (zoom-out)** — draw out users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals through guided questions with proposed answers. Work them conversationally, a few at a time — don't interrogate all seven at once. Leave genuinely-undecided items as open questions. +3. **Directions & trade-offs (zoom-in)** — propose **2–4 solution directions** with trade-offs, recommend one, and **wait for the PO to choose or refine.** +4. **Definition + approval gate:** assemble the definition (problem statement, users, goals & non-goals, success metrics, chosen direction + alternatives, key decisions, open questions) and ask the PO to approve, adjust, or cancel. For a non-trivial definition, also render it as a **navigable artifact** (see the skill's review step) — but the approval still happens in the chat. +5. **Handoff:** on approval, tell the PO the definition is ready and hand it to `/plan-backlog` (whose framing is then lighter). If they want it persisted, offer to save it as `docs/definitions/.md`. **Create no tickets here.** diff --git a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json index 25c5922..1738814 100644 --- a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json +++ b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys", diff --git a/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json b/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json index b3712c2..8e2438c 100644 --- a/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json +++ b/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys" diff --git a/plugins/fullstack-dev-kit/plugin.json b/plugins/fullstack-dev-kit/plugin.json index 3a8b188..d42585e 100644 --- a/plugins/fullstack-dev-kit/plugin.json +++ b/plugins/fullstack-dev-kit/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys", diff --git a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md index b18bea4..fd4f4d9 100644 --- a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md @@ -64,6 +64,8 @@ Move through **three levels**; at each, present **2–4 alternatives** (as many **4a. Framing (zoom-out) — help *define*, not just structure.** Restate the goal and map the problem space (users, outcomes, constraints, unknowns). Offer 2–4 **framing alternatives** — e.g. MVP vs. full, different ways to slice the initiative, different sequencing — with the trade-offs of each. → PO chooses the framing. +> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed. Run a **lighter framing**: *confirm* the definition's direction and slice from it, rather than re-deriving the problem space from scratch. Only re-open framing if the definition leaves the backlog-relevant slicing genuinely undecided. + **4b. Epics / themes.** For the chosen framing, propose the epics/themes with **alternatives** where the breakdown could reasonably differ. → PO adjusts. **4c. Stories.** Within each chosen epic, propose user stories (*"As a ``, I want ``, so that ``"*) with Given/When/Then **acceptance criteria**, INVEST-sized, offering **scoping alternatives** (split/merge, in/out) where it matters. → PO refines. diff --git a/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md new file mode 100644 index 0000000..feb8e1d --- /dev/null +++ b/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md @@ -0,0 +1,81 @@ +--- +name: plan-definition +description: Turn a spark (an idea, even a one-liner, in any format) into a clear product definition through a guided, Socratic discovery phase — frame the problem (users, outcome, metrics, constraints, non-goals), explore 2–4 directions with trade-offs, and produce an approved definition that then feeds plan-backlog. Facilitate, never decide. Use when a product owner wants to define a problem before breaking it into a backlog. +--- + +# Plan Definition + +Turn a **spark** into a clear **product definition** through a guided discovery phase — the **most upstream** step of the workflow, for the product-owner persona. It runs *before* `plan-backlog` and closes the loop **define → backlog → ticket → PR**. + +`plan-backlog` starts from a *defined* problem and turns it into a backlog; its framing step is deliberately light ("how do we slice this"). **`plan-definition` does the deep part: defining the problem itself** — who it's for, the outcome, why now, the constraints, the success metrics, the chosen direction. Its output is a **definition doc**, not a backlog and not tickets. You **facilitate** the PO's thinking — ask, offer options, and let them decide; never decide the product for them. + +## Trigger + +A request to *define*, *frame*, *scope*, or *think through* a product idea before there are stories — e.g. *"help me define this feature"*, *"I have a rough idea, let's shape it"*, *"what's the problem we're solving here"*. If the request is already a defined problem asking for tickets, that's `plan-backlog`, not this. + +## Boundary with `plan-backlog` (important) + +- **`plan-definition`** = define the problem & direction. **No backlog, no tickets.** Output: a product definition. +- **`plan-backlog`** = turn a *defined* problem into a backlog. When a definition from here is handed in, it consumes it and runs a **lighter framing** (confirm, don't re-derive) instead of framing from scratch. + +## 1. Intake — read the spark in whatever form it arrives + +The input is deliberately vaguer than `plan-backlog`'s — **a one-liner is a valid start.** + +- **Pasted text / chat description** → use directly. +- **PDF** → read it (page range as needed). +- **Word (`.docx`)** → convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF. +- **Artifact / Confluence page / URL** → fetch it. +- **Figma / FigJam link** (`figma.com/(design|file|board)/…`) → run `figma-fetch` for design/whiteboard context. FigJam boards (`/board/`) are read as **context only** in v1 — the definition is not written back to the board. + +Work only from what the source says plus what the user confirms — **never invent the problem, users, or metrics.** If the spark is thin, that's expected: the framing step (§2) is where you draw it out with questions. + +## 2. Frame the problem (zoom-out) — guided questions, proposed answers + +Draw out the definition through a **Socratic** exchange: for each dimension, ask, **propose a candidate answer grounded in the intake**, and let the PO confirm or adjust. Offer options; don't assume. Move through: + +- **Users / audience** — who is this for, and who is it *not* for? +- **Problem / outcome** — what problem, and what does success look like for the user? +- **Why now** — the trigger or opportunity. +- **Constraints** — technical, time, budget, compliance, existing systems. +- **Success metrics** — how we'll know it worked (leading + lagging where possible). +- **Risks / unknowns** — what could break the thesis; what we still don't know. +- **Non-goals** — explicitly out of scope, to keep the definition sharp. + +Don't interrogate all seven in one dump — work them conversationally, a few at a time, folding the PO's answers back in. It's fine to leave items in **open questions** rather than force an answer. + +## 3. Directions & trade-offs (zoom-in) + +Propose **2–4 solution directions** (as many as the situation needs, no padding) — e.g. MVP vs. full, different approaches, different sequencing — each with its **trade-offs** (cost, risk, time-to-value, reversibility). Recommend one with a reason, and **wait for the PO to choose or refine.** Ground every direction in the framing; never fabricate. + +## 4. Produce the definition (approval-gated) + +Assemble a structured **product definition / brief**. Canonical template — **must-have** sections: + +- **Problem statement** — one or two sentences. +- **Target users** — and non-users. +- **Goals** and **Non-goals**. +- **Success metrics**. +- **Chosen direction** — plus the alternatives considered and why this one. +- **Key decisions** — the calls made during framing, with their rationale. +- **Open questions** — what's still undecided. + +**Optional** sections when the material warrants: constraints, risks/unknowns, why-now, dependencies, a rough phasing sketch. + +**Approval gate (mandatory).** Present the full definition and **wait for explicit approval**; the PO may edit anything. Nothing is finalized — and nothing downstream (no backlog, no tickets) happens here — until they approve. + +**Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** Render the definition as a **navigable artifact** (collapsible sections, a table of contents, easy to scan and drill into) as the review aid — reusing the same doctrine as `plan-backlog`'s review artifact. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate*: still print a concise summary and ask for approval **in the conversation**. On hosts without artifacts (Codex / Cursor / Copilot), present the definition as Markdown. + +**Where it lives (v1).** The definition lives in the conversation (and the artifact). If the PO wants it persisted, offer to save it as a Markdown file in the repo (e.g. `docs/definitions/.md`) — only on request. No Confluence/whiteboard write-back in v1. + +## 5. Handoff to `plan-backlog` + +On approval, hand the definition to `plan-backlog` as its input: *"the definition is ready — run `/plan-backlog` on it to turn it into a backlog."* Because the problem is now defined, `plan-backlog`'s framing step is lighter — it confirms the framing rather than re-deriving it. That completes the loop **define → backlog → ticket → PR**. + +## Guardrails + +- **Facilitate, never decide:** ask, offer alternatives, and let the PO make the call at each step — don't hand them a finished definition and call it done. +- **Never fabricate** the problem, users, metrics, or direction — ground everything in the intake plus the PO's answers. A thin spark is drawn out with questions, not invented. +- **No backlog, no tickets here** — that's `plan-backlog`. This step stops at an approved definition. +- **Approval gate** before the definition is finalized. +- Watch for **secrets/PII** in the source material; don't copy them into the definition. diff --git a/skills/plan-backlog/SKILL.md b/skills/plan-backlog/SKILL.md index b18bea4..fd4f4d9 100644 --- a/skills/plan-backlog/SKILL.md +++ b/skills/plan-backlog/SKILL.md @@ -64,6 +64,8 @@ Move through **three levels**; at each, present **2–4 alternatives** (as many **4a. Framing (zoom-out) — help *define*, not just structure.** Restate the goal and map the problem space (users, outcomes, constraints, unknowns). Offer 2–4 **framing alternatives** — e.g. MVP vs. full, different ways to slice the initiative, different sequencing — with the trade-offs of each. → PO chooses the framing. +> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed. Run a **lighter framing**: *confirm* the definition's direction and slice from it, rather than re-deriving the problem space from scratch. Only re-open framing if the definition leaves the backlog-relevant slicing genuinely undecided. + **4b. Epics / themes.** For the chosen framing, propose the epics/themes with **alternatives** where the breakdown could reasonably differ. → PO adjusts. **4c. Stories.** Within each chosen epic, propose user stories (*"As a ``, I want ``, so that ``"*) with Given/When/Then **acceptance criteria**, INVEST-sized, offering **scoping alternatives** (split/merge, in/out) where it matters. → PO refines. diff --git a/skills/plan-definition/SKILL.md b/skills/plan-definition/SKILL.md new file mode 100644 index 0000000..feb8e1d --- /dev/null +++ b/skills/plan-definition/SKILL.md @@ -0,0 +1,81 @@ +--- +name: plan-definition +description: Turn a spark (an idea, even a one-liner, in any format) into a clear product definition through a guided, Socratic discovery phase — frame the problem (users, outcome, metrics, constraints, non-goals), explore 2–4 directions with trade-offs, and produce an approved definition that then feeds plan-backlog. Facilitate, never decide. Use when a product owner wants to define a problem before breaking it into a backlog. +--- + +# Plan Definition + +Turn a **spark** into a clear **product definition** through a guided discovery phase — the **most upstream** step of the workflow, for the product-owner persona. It runs *before* `plan-backlog` and closes the loop **define → backlog → ticket → PR**. + +`plan-backlog` starts from a *defined* problem and turns it into a backlog; its framing step is deliberately light ("how do we slice this"). **`plan-definition` does the deep part: defining the problem itself** — who it's for, the outcome, why now, the constraints, the success metrics, the chosen direction. Its output is a **definition doc**, not a backlog and not tickets. You **facilitate** the PO's thinking — ask, offer options, and let them decide; never decide the product for them. + +## Trigger + +A request to *define*, *frame*, *scope*, or *think through* a product idea before there are stories — e.g. *"help me define this feature"*, *"I have a rough idea, let's shape it"*, *"what's the problem we're solving here"*. If the request is already a defined problem asking for tickets, that's `plan-backlog`, not this. + +## Boundary with `plan-backlog` (important) + +- **`plan-definition`** = define the problem & direction. **No backlog, no tickets.** Output: a product definition. +- **`plan-backlog`** = turn a *defined* problem into a backlog. When a definition from here is handed in, it consumes it and runs a **lighter framing** (confirm, don't re-derive) instead of framing from scratch. + +## 1. Intake — read the spark in whatever form it arrives + +The input is deliberately vaguer than `plan-backlog`'s — **a one-liner is a valid start.** + +- **Pasted text / chat description** → use directly. +- **PDF** → read it (page range as needed). +- **Word (`.docx`)** → convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF. +- **Artifact / Confluence page / URL** → fetch it. +- **Figma / FigJam link** (`figma.com/(design|file|board)/…`) → run `figma-fetch` for design/whiteboard context. FigJam boards (`/board/`) are read as **context only** in v1 — the definition is not written back to the board. + +Work only from what the source says plus what the user confirms — **never invent the problem, users, or metrics.** If the spark is thin, that's expected: the framing step (§2) is where you draw it out with questions. + +## 2. Frame the problem (zoom-out) — guided questions, proposed answers + +Draw out the definition through a **Socratic** exchange: for each dimension, ask, **propose a candidate answer grounded in the intake**, and let the PO confirm or adjust. Offer options; don't assume. Move through: + +- **Users / audience** — who is this for, and who is it *not* for? +- **Problem / outcome** — what problem, and what does success look like for the user? +- **Why now** — the trigger or opportunity. +- **Constraints** — technical, time, budget, compliance, existing systems. +- **Success metrics** — how we'll know it worked (leading + lagging where possible). +- **Risks / unknowns** — what could break the thesis; what we still don't know. +- **Non-goals** — explicitly out of scope, to keep the definition sharp. + +Don't interrogate all seven in one dump — work them conversationally, a few at a time, folding the PO's answers back in. It's fine to leave items in **open questions** rather than force an answer. + +## 3. Directions & trade-offs (zoom-in) + +Propose **2–4 solution directions** (as many as the situation needs, no padding) — e.g. MVP vs. full, different approaches, different sequencing — each with its **trade-offs** (cost, risk, time-to-value, reversibility). Recommend one with a reason, and **wait for the PO to choose or refine.** Ground every direction in the framing; never fabricate. + +## 4. Produce the definition (approval-gated) + +Assemble a structured **product definition / brief**. Canonical template — **must-have** sections: + +- **Problem statement** — one or two sentences. +- **Target users** — and non-users. +- **Goals** and **Non-goals**. +- **Success metrics**. +- **Chosen direction** — plus the alternatives considered and why this one. +- **Key decisions** — the calls made during framing, with their rationale. +- **Open questions** — what's still undecided. + +**Optional** sections when the material warrants: constraints, risks/unknowns, why-now, dependencies, a rough phasing sketch. + +**Approval gate (mandatory).** Present the full definition and **wait for explicit approval**; the PO may edit anything. Nothing is finalized — and nothing downstream (no backlog, no tickets) happens here — until they approve. + +**Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** Render the definition as a **navigable artifact** (collapsible sections, a table of contents, easy to scan and drill into) as the review aid — reusing the same doctrine as `plan-backlog`'s review artifact. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate*: still print a concise summary and ask for approval **in the conversation**. On hosts without artifacts (Codex / Cursor / Copilot), present the definition as Markdown. + +**Where it lives (v1).** The definition lives in the conversation (and the artifact). If the PO wants it persisted, offer to save it as a Markdown file in the repo (e.g. `docs/definitions/.md`) — only on request. No Confluence/whiteboard write-back in v1. + +## 5. Handoff to `plan-backlog` + +On approval, hand the definition to `plan-backlog` as its input: *"the definition is ready — run `/plan-backlog` on it to turn it into a backlog."* Because the problem is now defined, `plan-backlog`'s framing step is lighter — it confirms the framing rather than re-deriving it. That completes the loop **define → backlog → ticket → PR**. + +## Guardrails + +- **Facilitate, never decide:** ask, offer alternatives, and let the PO make the call at each step — don't hand them a finished definition and call it done. +- **Never fabricate** the problem, users, metrics, or direction — ground everything in the intake plus the PO's answers. A thin spark is drawn out with questions, not invented. +- **No backlog, no tickets here** — that's `plan-backlog`. This step stops at an approved definition. +- **Approval gate** before the definition is finalized. +- Watch for **secrets/PII** in the source material; don't copy them into the definition. From 987b69959d215a8e96c0268cfd791a45806e29d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Atam=C3=A1n=20Vega?= Date: Wed, 16 Sep 2026 18:15:28 +0100 Subject: [PATCH 2/3] fix(po): address self-review findings on plan-definition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the kit's own pr-reviewer pass on #79: - FigJam accuracy: figma-fetch only reads /design and /file URLs, not FigJam /board/ — stop implying it fetches boards. The three new files now say figma-fetch covers Figma designs and a FigJam board's content is taken as pasted text (v1 read-only context, nothing written back). - Loop-phrase consistency: keep plan-backlog's own loop as "idea → backlog → ticket → PR" in the README paragraph (plan-backlog genuinely starts from an idea); "define → ..." stays in the plan-definition paragraph and the full-flow CHANGELOG line. - Drop the unused dev-kit-setup skill from plan-definer's frontmatter — it touches no tracker and creates no tickets. Bundle re-synced (source/bundle byte-identical); validator + 35 tests pass. Co-Authored-By: Claude Opus 4.8 --- README.md | 2 +- agents/plan-definer.md | 3 +-- commands/plan-definition.md | 4 ++-- plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md | 2 +- skills/plan-definition/SKILL.md | 2 +- 5 files changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e1489df..8f3c062 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Give the `coding-agent` a user story ID from your tracker and it orchestrates th ## From idea to backlog (product owners) -Before there's a ticket, **`plan-backlog`** turns an idea or brief — chat text, a PDF, a Word doc, an artifact — into a well-formed backlog (epics, INVEST user stories with acceptance criteria, sub-tasks, dependencies) and **creates it in your tracker after you approve it**. It's discovery-first (mirrors your team's existing hierarchy and conventions rather than imposing one) and speaks Jira / Linear / GitHub Issues / Azure DevOps via the same adapters. The stories it creates feed straight into `/work-story` — closing the loop **define → backlog → ticket → PR**. +Before there's a ticket, **`plan-backlog`** turns an idea or brief — chat text, a PDF, a Word doc, an artifact — into a well-formed backlog (epics, INVEST user stories with acceptance criteria, sub-tasks, dependencies) and **creates it in your tracker after you approve it**. It's discovery-first (mirrors your team's existing hierarchy and conventions rather than imposing one) and speaks Jira / Linear / GitHub Issues / Azure DevOps via the same adapters. The stories it creates feed straight into `/work-story` — closing the loop **idea → backlog → ticket → PR**. It's **guided by default** — it elaborates progressively (framing → epics → stories), offering alternatives and asking for your decision at each level, so the definition stays yours; add `--quick` for a one-shot draft. On Claude, a non-trivial backlog is shown as a **navigable artifact** for review (approval still happens in the chat). In **Claude Code**, run `/plan-backlog [--quick]`. On **Codex / Cursor / Copilot**, invoke the `plan-backlog` skill directly. diff --git a/agents/plan-definer.md b/agents/plan-definer.md index 2645d48..5d26a0f 100644 --- a/agents/plan-definer.md +++ b/agents/plan-definer.md @@ -3,7 +3,6 @@ name: plan-definer description: Product-owner discovery orchestrator. Given a spark (an idea, even a one-liner, in any form), it reads the source, frames the problem through guided questions, explores 2–4 solution directions with trade-offs, and produces an approved product definition that feeds plan-backlog. Facilitates the PO's thinking; never decides for them. Creates no tickets. model: inherit skills: - - dev-kit-setup - figma-fetch - plan-definition --- @@ -18,7 +17,7 @@ You are the discovery/definition orchestrator for the **product-owner** persona. ### 1. Intake - Read the source spark in whatever form it arrives (chat text, a one-liner, a PDF, a Word doc, an artifact, a Confluence link). A thin spark is expected — you draw the rest out in framing, never invent it. -- If it references Figma/FigJam (`figma.com/(design|file|board)/…`), run `figma-fetch` for context (FigJam is read-only context in v1). +- If it references a Figma design (`figma.com/(design|file)/…`), run `figma-fetch` for context. `figma-fetch` doesn't read FigJam `/board/` URLs yet — take a board's content as pasted text (read-only context in v1; nothing is written back). ### 2. Frame the problem — WAIT FOR THE PO Draw out the definition Socratically (§2 of the skill): users/non-users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals. For each, propose a candidate answer **grounded in the intake** and let the PO confirm or adjust. It's fine to leave items as open questions. diff --git a/commands/plan-definition.md b/commands/plan-definition.md index 280c834..d66dcee 100644 --- a/commands/plan-definition.md +++ b/commands/plan-definition.md @@ -8,14 +8,14 @@ Follow the `plan-definition` skill. This is the **most upstream** step — it *d Rules: -- If the arguments contain no idea or source, ask for one — but a **one-liner is a valid start** (this step is for vague sparks; you draw the rest out with questions). Accept pasted text, a path to a file (PDF / Word / Markdown), or a URL / artifact / Figma-FigJam link. +- If the arguments contain no idea or source, ask for one — but a **one-liner is a valid start** (this step is for vague sparks; you draw the rest out with questions). Accept pasted text, a path to a file (PDF / Word / Markdown), or a URL / artifact / Figma design link. - **Facilitate, never decide.** Ask, propose candidate answers grounded in the intake, and let the PO confirm or adjust at each step. ## Run it in THIS conversation (guided, interactive) The definition flow is interactive, so conduct it in the main conversation — the PO makes a decision at each step (do not hand it to a context-isolated subagent, whose output the user can't see mid-run). You may delegate **intake reading** (e.g. a large PDF/Figma fetch) to the `plan-definer` subagent to keep this context clean. -1. **Intake** — read the spark in whatever form it arrives (§1 of the skill). If it references Figma/FigJam, run `figma-fetch` for context. +1. **Intake** — read the spark in whatever form it arrives (§1 of the skill). If it references a Figma design, run `figma-fetch` for context (FigJam `/board/` URLs aren't fetched yet — take a board's content as pasted text). 2. **Frame the problem (zoom-out)** — draw out users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals through guided questions with proposed answers. Work them conversationally, a few at a time — don't interrogate all seven at once. Leave genuinely-undecided items as open questions. 3. **Directions & trade-offs (zoom-in)** — propose **2–4 solution directions** with trade-offs, recommend one, and **wait for the PO to choose or refine.** 4. **Definition + approval gate:** assemble the definition (problem statement, users, goals & non-goals, success metrics, chosen direction + alternatives, key decisions, open questions) and ask the PO to approve, adjust, or cancel. For a non-trivial definition, also render it as a **navigable artifact** (see the skill's review step) — but the approval still happens in the chat. diff --git a/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md index feb8e1d..772e65e 100644 --- a/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md @@ -26,7 +26,7 @@ The input is deliberately vaguer than `plan-backlog`'s — **a one-liner is a va - **PDF** → read it (page range as needed). - **Word (`.docx`)** → convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF. - **Artifact / Confluence page / URL** → fetch it. -- **Figma / FigJam link** (`figma.com/(design|file|board)/…`) → run `figma-fetch` for design/whiteboard context. FigJam boards (`/board/`) are read as **context only** in v1 — the definition is not written back to the board. +- **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context. For a **FigJam** board, `figma-fetch` doesn't read `/board/` URLs yet — ask the PO to paste the board's content as text. v1 treats any whiteboard as **read-only context**; nothing is written back to it. Work only from what the source says plus what the user confirms — **never invent the problem, users, or metrics.** If the spark is thin, that's expected: the framing step (§2) is where you draw it out with questions. diff --git a/skills/plan-definition/SKILL.md b/skills/plan-definition/SKILL.md index feb8e1d..772e65e 100644 --- a/skills/plan-definition/SKILL.md +++ b/skills/plan-definition/SKILL.md @@ -26,7 +26,7 @@ The input is deliberately vaguer than `plan-backlog`'s — **a one-liner is a va - **PDF** → read it (page range as needed). - **Word (`.docx`)** → convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF. - **Artifact / Confluence page / URL** → fetch it. -- **Figma / FigJam link** (`figma.com/(design|file|board)/…`) → run `figma-fetch` for design/whiteboard context. FigJam boards (`/board/`) are read as **context only** in v1 — the definition is not written back to the board. +- **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context. For a **FigJam** board, `figma-fetch` doesn't read `/board/` URLs yet — ask the PO to paste the board's content as text. v1 treats any whiteboard as **read-only context**; nothing is written back to it. Work only from what the source says plus what the user confirms — **never invent the problem, users, or metrics.** If the spark is thin, that's expected: the framing step (§2) is where you draw it out with questions. From d4fc069398d4b8f43c8462c2ed69ec08752de423 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Atam=C3=A1n=20Vega?= Date: Tue, 22 Sep 2026 08:14:13 +0100 Subject: [PATCH 3/3] =?UTF-8?q?fix(po):=20address=20Santi's=20review=20on?= =?UTF-8?q?=20plan-definition=20(#79)=20=E2=80=94=20grounding=20&=20proven?= =?UTF-8?q?ance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves the blocking finding and the actionable non-blockers from the dogfooding review. Blocking — the no-fabrication guardrail was unsatisfiable for the thin input the skill invites (a one-liner has no third source but model memory), and the template couldn't record provenance: - New "Grounding & provenance" section: separate *generating options the PO chooses* (the job) from *asserting unverifiable facts as established* (fabrication). - Per-claim provenance markers: [PO] / [spark] / [proposed] / [unverified]. - risks/unknowns promoted to a must-have (it's what qualifies the confident sections). - must-haves may be "not established" rather than invented (esp. Success metrics, which POs decline). - Approval gate now walks the [unverified]/[proposed] claims and asks "what does this rest on that nobody has verified?" - State plainly there is no research step: market/novelty/prior-art claims are [unverified] unless the PO supplies a source. Non-blocking: - plan-backlog lighter-framing gate now conditions on the definition's *groundedness*, not just the presence of five headings. - plan-backlog §1 lists a definition (chat or docs/definitions/.md) as an input form — closes the cross-session handoff carrier gap. - Handoff states whether the definition is backlog-ready. - Flow is no longer forward-only: a §3 direction can be reopened from §4. - Artifact threshold stated one way (host supports artifacts), matching the skill. - plan-definer no longer claims an unreachable "assemble the draft" path (there is no --quick mode). - README: escape `|` inside plan-definition/plan-backlog table cells so GitHub stops truncating the rows. Trio duplication (Santi's architecture question) is deliberately NOT addressed here — it's a cross-trio subtraction pass tracked as its own issue. Bundle rebuilt (source/bundle byte-identical); validator + 35 tests pass. Kit stays 0.19.13 (refines the same unreleased feature). Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 2 +- README.md | 8 +-- agents/plan-definer.md | 12 ++--- commands/plan-definition.md | 7 +-- .../skills/plan-backlog/SKILL.md | 3 +- .../skills/plan-definition/SKILL.md | 50 +++++++++++++++---- skills/plan-backlog/SKILL.md | 3 +- skills/plan-definition/SKILL.md | 50 +++++++++++++++---- 8 files changed, 99 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e6d3fdd..470a641 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ a release is only "live" for users once that is bumped and published. ## [Unreleased] ### Added -- **`plan-definition` — a guided discovery/definition phase upstream of `plan-backlog` (#73).** When an idea is still a rough spark (even a one-liner), this new step *defines the problem* before any backlog exists: a guided, Socratic pass that frames the problem (users, outcome, why-now, constraints, success metrics, risks, non-goals) with proposed answers to confirm/adjust, explores **2–4 solution directions** with trade-offs, and produces an approved **product definition** — a definition doc, **not tickets**. On hosts with artifacts it renders as a navigable artifact (reusing #74's doctrine); Markdown elsewhere. The definition then feeds `plan-backlog`, whose framing step is **lighter** when a definition is handed in (confirm, don't re-derive). Ships as the portable `plan-definition` skill plus a Claude `/plan-definition` command and `plan-definer` agent — same trio shape as `plan-backlog`. Facilitate-never-decide, approval-gated, no fabrication. Full flow: **define → backlog → ticket → PR → follow-ups**. From @santielizondo's idea; v1 for team review. Kit → **0.19.13**. +- **`plan-definition` — a guided discovery/definition phase upstream of `plan-backlog` (#73).** When an idea is still a rough spark (even a one-liner), this new step *defines the problem* before any backlog exists: a guided, Socratic pass that frames the problem (users, outcome, why-now, constraints, success metrics, risks, non-goals) with proposed answers to confirm/adjust, explores **2–4 solution directions** with trade-offs, and produces an approved **product definition** — a definition doc, **not tickets**. On hosts with artifacts it renders as a navigable artifact (reusing #74's doctrine); Markdown elsewhere. The definition then feeds `plan-backlog`, whose framing step is **lighter** when a definition is handed in — but only when the definition is genuinely **grounded**, not merely well-formed. Ships as the portable `plan-definition` skill plus a Claude `/plan-definition` command and `plan-definer` agent — same trio shape as `plan-backlog`. **Grounding & provenance model:** because a one-liner is a valid input, most content is generated — so the skill separates *generating options the PO chooses* (the job) from *asserting unverifiable facts as established* (fabrication), marks every claim's provenance (`[PO]`/`[spark]`/`[proposed]`/`[unverified]`), makes `risks/unknowns` a must-have, allows any must-have to be "not established" rather than invented, and adds a "what does this rest on that nobody verified?" question to the approval gate. Facilitate-never-decide, approval-gated. Full flow: **define → backlog → ticket → PR → follow-ups**. From @santielizondo's idea; hardened via his dogfooding review on #79. Kit → **0.19.13**. - **Rich review artifact for `plan-backlog` (#74).** On hosts that support artifacts (Claude Code / claude.ai), a non-trivial backlog draft is now presented as a **navigable artifact** at the review step — collapsible epics → stories with acceptance criteria, labels, sizing and dependencies, plus search/filter and a table of contents — so a large backlog is easy to scan and drill into. The in-chat draft + approval question stay the gate (the artifact is a review aid, not a substitute); portable hosts (Codex/Cursor/Copilot) keep Markdown. From @santielizondo's idea. Kit → **0.19.12**. ### Changed diff --git a/README.md b/README.md index 8f3c062..2968eb7 100644 --- a/README.md +++ b/README.md @@ -224,8 +224,8 @@ The kit runs `dev-kit-setup`: it detects your tracker, discovers what it can (si | You want to… | Type | |---|---| | Work a story end to end (current window) | `/fullstack-dev-kit:work-story PROJ-1234` | -| Define a problem before there's a backlog | `/fullstack-dev-kit:plan-definition ` | -| Draft & create a backlog from an idea/brief | `/fullstack-dev-kit:plan-backlog ` | +| Define a problem before there's a backlog | `/fullstack-dev-kit:plan-definition ` | +| Draft & create a backlog from an idea/brief | `/fullstack-dev-kit:plan-backlog ` | | Prepare a story worktree + new VS Code window | `/fullstack-dev-kit:launch-story PROJ-1234` | | Unattended run (no plan gate — pipelines only) | append `--auto-approve` | | Review a PR or your current diff | `/fullstack-dev-kit:pr-review #42` | @@ -284,8 +284,8 @@ Full **`/work-story `** flow is ticket-first (it fetches the story and m | `fix-pr` | skill | Playbook: findings → fixes → re-verified gates → push | | `instructions/` | rules | Always-on, language-agnostic: secure coding, testing standards | | `/work-story` | command | Entry point: `/work-story PROJ-1234` | -| `/plan-definition` | command | Entry point: `/plan-definition ` (define before backlog) | -| `/plan-backlog` | command | Entry point: `/plan-backlog ` | +| `/plan-definition` | command | Entry point: `/plan-definition ` (define before backlog) | +| `/plan-backlog` | command | Entry point: `/plan-backlog ` | | `/launch-story` | command | Creates a story worktree and opens a new VS Code window on it | ## Relationship to project repos diff --git a/agents/plan-definer.md b/agents/plan-definer.md index 5d26a0f..d0f631c 100644 --- a/agents/plan-definer.md +++ b/agents/plan-definer.md @@ -11,7 +11,7 @@ You are the discovery/definition orchestrator for the **product-owner** persona. **Facilitate, discovery-first.** You draw the definition out of the PO with questions and grounded proposals — you never decide the product for them. The **`plan-definition` skill holds the full playbook** — follow it exactly. -**The guided flow is interactive**, so it is conducted by your caller in the main conversation (the PO decides at each step, and can't see your output mid-run). **You are the engine for intake reading and for assembling the definition draft.** If invoked for a guided run, do the intake/framing groundwork and return the questions, candidate answers, and direction options for the caller to put to the PO — don't try to run the per-step decisions yourself. +**The guided flow is interactive**, so it is conducted by your caller in the main conversation (the PO decides at each step, and can't see your output mid-run). **You are the engine for the intake groundwork** — reading the source, discovering context, and returning the framing questions, candidate answers, and direction options for the caller to put to the PO. You do **not** assemble a finished definition on your own (there is no one-shot `--quick` mode for this skill — the definition is built with the PO, decision by decision, by your caller). Don't try to run the per-step decisions yourself; the PO can't see your output mid-run. ## Workflow (in order — the approval gate is mandatory) @@ -20,25 +20,25 @@ You are the discovery/definition orchestrator for the **product-owner** persona. - If it references a Figma design (`figma.com/(design|file)/…`), run `figma-fetch` for context. `figma-fetch` doesn't read FigJam `/board/` URLs yet — take a board's content as pasted text (read-only context in v1; nothing is written back). ### 2. Frame the problem — WAIT FOR THE PO -Draw out the definition Socratically (§2 of the skill): users/non-users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals. For each, propose a candidate answer **grounded in the intake** and let the PO confirm or adjust. It's fine to leave items as open questions. +Draw out the definition Socratically (§2 of the skill): users/non-users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals. For each, propose a candidate answer and let the PO confirm or adjust. It's fine — often better — to leave an item **"not established"** than to invent one. Follow the skill's **Grounding & provenance** rule: proposing options is the job, but there is no research step, so market/novelty/prior-art claims are `[unverified]` unless the PO supplies a source — never recite a competitive map from memory as fact. ### 3. Directions & trade-offs Propose **2–4 solution directions** with trade-offs (cost, risk, time-to-value, reversibility), recommend one with a reason, and wait for the PO to choose or refine. ### 4. Definition — WAIT FOR APPROVAL -Assemble the definition per the skill's template (problem statement, target users, goals & non-goals, success metrics, chosen direction + alternatives considered, key decisions, open questions; optional sections where warranted). +Assemble the definition per the skill's template (problem statement, target users, goals & non-goals, success metrics **or "not established"**, chosen direction + alternatives considered, key decisions, risks/unknowns, open questions; optional sections where warranted). **Every line carries its provenance marker** (`[PO]`/`[spark]`/`[proposed]`/`[unverified]`), and the approval gate walks the unverified/proposed claims before the OK. **No definition is finalized, and nothing downstream happens, until the PO explicitly approves.** **If you are running as a subagent** (your caller relays to the user): return the FULL draft definition (or the framing questions / direction options, depending on the stage) as your result and stop — do not ask for approval yourself and do not create anything. Your caller shows it to the PO and resumes you with the decision. -**If you are running in the main conversation**: present the definition and wait for explicit approval. On a host with artifacts, you may also render a non-trivial definition as a navigable artifact for review (per the skill), but the in-chat summary + question stay the gate. +**If you are running in the main conversation**: present the definition and wait for explicit approval. When the host supports artifacts, you may also render it as a navigable artifact for review (per the skill), but the in-chat summary + question stay the gate. ### 5. Handoff -On approval, hand the definition to `plan-backlog` as its input (its framing step is then lighter). If the PO wants it persisted, offer to save it as `docs/definitions/.md`. **Create no tickets.** +On approval, hand the definition to `plan-backlog` as its input (its framing step is then lighter). Say plainly whether it's **backlog-ready**: if core must-haves are "not established" or it leans on `[unverified]` claims, flag that so `plan-backlog` re-derives rather than confirming. If the backlog won't be built in the same sitting, offer to save it to `docs/definitions/.md` so `plan-backlog` can read it later. **Create no tickets.** ## Guardrails - Facilitate, never decide: offer alternatives and ask for the PO's decision at each step. -- Never fabricate the problem, users, metrics, or direction — ground everything in the intake plus the PO's answers. +- Grounding over fluency: generating options is the job; asserting unverifiable facts as established is not. Mark provenance on every claim, keep `[unverified]` market/novelty claims out of load-bearing prose, and prefer a marked gap to an invented answer. - No backlog and no tickets here — this step stops at an approved definition. - Watch for secrets/PII in the source material; don't copy them into the definition. diff --git a/commands/plan-definition.md b/commands/plan-definition.md index d66dcee..47cb56b 100644 --- a/commands/plan-definition.md +++ b/commands/plan-definition.md @@ -9,7 +9,8 @@ Follow the `plan-definition` skill. This is the **most upstream** step — it *d Rules: - If the arguments contain no idea or source, ask for one — but a **one-liner is a valid start** (this step is for vague sparks; you draw the rest out with questions). Accept pasted text, a path to a file (PDF / Word / Markdown), or a URL / artifact / Figma design link. -- **Facilitate, never decide.** Ask, propose candidate answers grounded in the intake, and let the PO confirm or adjust at each step. +- **Facilitate, never decide.** Ask, propose candidate answers, and let the PO confirm or adjust at each step. +- **Ground it.** Generating options for the PO to choose is the job; asserting unverifiable facts (market/novelty/prior-art claims, invented metrics) as established is not. The skill's **Grounding & provenance** rule governs — mark each claim `[PO]`/`[spark]`/`[proposed]`/`[unverified]`, and there's no research step, so market/novelty claims are `[unverified]` unless the PO supplies a source. ## Run it in THIS conversation (guided, interactive) @@ -18,5 +19,5 @@ The definition flow is interactive, so conduct it in the main conversation — t 1. **Intake** — read the spark in whatever form it arrives (§1 of the skill). If it references a Figma design, run `figma-fetch` for context (FigJam `/board/` URLs aren't fetched yet — take a board's content as pasted text). 2. **Frame the problem (zoom-out)** — draw out users, problem/outcome, why-now, constraints, success metrics, risks/unknowns, non-goals through guided questions with proposed answers. Work them conversationally, a few at a time — don't interrogate all seven at once. Leave genuinely-undecided items as open questions. 3. **Directions & trade-offs (zoom-in)** — propose **2–4 solution directions** with trade-offs, recommend one, and **wait for the PO to choose or refine.** -4. **Definition + approval gate:** assemble the definition (problem statement, users, goals & non-goals, success metrics, chosen direction + alternatives, key decisions, open questions) and ask the PO to approve, adjust, or cancel. For a non-trivial definition, also render it as a **navigable artifact** (see the skill's review step) — but the approval still happens in the chat. -5. **Handoff:** on approval, tell the PO the definition is ready and hand it to `/plan-backlog` (whose framing is then lighter). If they want it persisted, offer to save it as `docs/definitions/.md`. **Create no tickets here.** +4. **Definition + approval gate:** assemble the definition (problem statement, users, goals & non-goals, success metrics **or "not established"**, chosen direction + alternatives, key decisions, risks/unknowns, open questions), each line carrying its provenance marker. Before the OK, walk the `[unverified]`/`[proposed]` claims — ask *"what in here rests on something nobody has verified?"* — then ask the PO to approve, adjust, or cancel. When the host supports artifacts, also render it as a **navigable artifact** (see the skill's review step) — but the approval still happens in the chat. +5. **Handoff:** on approval, tell the PO the definition is ready and hand it to `/plan-backlog` (whose framing is then lighter). Say plainly whether it's **backlog-ready** — if core must-haves are "not established" or it leans on `[unverified]` claims, flag that so `plan-backlog` re-derives rather than just confirming. If the backlog won't be built in the same sitting, offer to save it to `docs/definitions/.md` so `plan-backlog` can read it later. **Create no tickets here.** diff --git a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md index fd4f4d9..7bd4494 100644 --- a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md @@ -30,6 +30,7 @@ Read `.claude/dev-kit.json` at the consuming repo root. The `tracker` block name - **Word (`.docx`)** → not natively readable; convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF. - **Artifact / Confluence page / URL** → fetch it. - **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context. +- **A `plan-definition` product definition** — passed in chat, or a `docs/definitions/.md` file → read it as the source. It carries the framing already (problem, users, goals/non-goals, metrics, chosen direction), which is what triggers the **lighter framing** in §4a. Check its provenance markers / "not established" / `[unverified]` notes: a definition that flags core gaps is **not** ready for the light path (see §4a). Work only from what the source says plus what the user confirms — **never invent scope or acceptance criteria.** @@ -64,7 +65,7 @@ Move through **three levels**; at each, present **2–4 alternatives** (as many **4a. Framing (zoom-out) — help *define*, not just structure.** Restate the goal and map the problem space (users, outcomes, constraints, unknowns). Offer 2–4 **framing alternatives** — e.g. MVP vs. full, different ways to slice the initiative, different sequencing — with the trade-offs of each. → PO chooses the framing. -> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed. Run a **lighter framing**: *confirm* the definition's direction and slice from it, rather than re-deriving the problem space from scratch. Only re-open framing if the definition leaves the backlog-relevant slicing genuinely undecided. +> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed — *if it's grounded.* Before taking the light path, **check the definition, not just its headings**: a doc whose core must-haves are "not established", or whose thesis rests on `[unverified]` claims, is a spark with a template around it — treat it as an ordinary idea and frame from scratch (§4a). Only when the definition is genuinely grounded, run a **lighter framing**: *confirm* its direction and slice from it rather than re-deriving. Also re-open framing if the definition leaves the backlog-relevant slicing undecided. The presence of the five sections is not the signal; their groundedness is. **4b. Epics / themes.** For the chosen framing, propose the epics/themes with **alternatives** where the breakdown could reasonably differ. → PO adjusts. diff --git a/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md index 772e65e..f86aa1b 100644 --- a/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/plan-definition/SKILL.md @@ -28,11 +28,30 @@ The input is deliberately vaguer than `plan-backlog`'s — **a one-liner is a va - **Artifact / Confluence page / URL** → fetch it. - **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context. For a **FigJam** board, `figma-fetch` doesn't read `/board/` URLs yet — ask the PO to paste the board's content as text. v1 treats any whiteboard as **read-only context**; nothing is written back to it. -Work only from what the source says plus what the user confirms — **never invent the problem, users, or metrics.** If the spark is thin, that's expected: the framing step (§2) is where you draw it out with questions. +If the spark is thin, that's expected — the framing step (§2) is where you draw it out with questions, not where you fill it in for the PO. See **Grounding & provenance** next; it governs the whole flow. + +## Grounding & provenance (the core rule — read before drafting) + +A one-liner is a valid start, so most of what a definition could contain is **not** in the intake. That is fine — but it makes *how you introduce content* the thing that keeps this honest. Two moves that look identical on the page are completely different: + +- **Generating options for the PO to choose** — proposing 2–4 framings, directions, or candidate answers and letting the PO pick — is **the point of this skill.** Do it freely. +- **Asserting facts about the world** the PO didn't give you — "no mainstream app does X", "this is why people churn", "the market for Y is underserved", a specific metric target — is **fabrication when stated as established.** You cannot verify market, prior-art, or novelty claims here; the skill has no research step. So: + - Offer them as the PO's to confirm ("*is it true that…?*"), or + - Mark them **unverified** in the definition, or + - Leave them out. + +**Every claim in the definition carries a provenance marker** so a proposal never renders identically to a decision: + +- `[PO]` — the PO stated or explicitly confirmed it. +- `[spark]` — it came from the intake source. +- `[proposed]` — you generated it; the PO accepted the option but the *content* is yours. +- `[unverified]` — a factual claim about the world that nobody has checked (all market/novelty/prior-art claims are at least this). + +The distinction to never blur: **a direction the PO selected from your options is a real decision; a fact you supplied to justify it is not, until it's checked.** When in doubt, mark it lower, not higher. ## 2. Frame the problem (zoom-out) — guided questions, proposed answers -Draw out the definition through a **Socratic** exchange: for each dimension, ask, **propose a candidate answer grounded in the intake**, and let the PO confirm or adjust. Offer options; don't assume. Move through: +Draw out the definition through a **Socratic** exchange: for each dimension, ask, **propose a candidate answer**, and let the PO confirm or adjust. Proposing candidates is exactly right (see **Grounding & provenance**) — just don't smuggle in unverifiable *facts* as if they were established (mark those `[unverified]` or ask). Offer options; don't assume. Move through: - **Users / audience** — who is this for, and who is it *not* for? - **Problem / outcome** — what problem, and what does success look like for the user? @@ -42,27 +61,34 @@ Draw out the definition through a **Socratic** exchange: for each dimension, ask - **Risks / unknowns** — what could break the thesis; what we still don't know. - **Non-goals** — explicitly out of scope, to keep the definition sharp. -Don't interrogate all seven in one dump — work them conversationally, a few at a time, folding the PO's answers back in. It's fine to leave items in **open questions** rather than force an answer. +Don't interrogate all seven in one dump — work them conversationally, a few at a time, folding the PO's answers back in. It's fine — often better — to leave an item **explicitly unresolved** rather than force an answer: any must-have section may carry *"not established"* with a note on what's needed to settle it (see §4). This applies especially to **Success metrics**, which POs frequently decline — record "not established (no baseline yet)", never a number you made up. + +**No research step.** The skill fetches only PO-supplied sources (§1); it does not browse. So when a dimension turns on a fact you'd normally look up — *"which segment is underserved?"*, *"has anyone shipped this?"* — you **cannot answer it as fact.** Say so, offer it as a question for the PO or a later research task, and mark any market/novelty claim `[unverified]`. Confidently reciting a competitive map from memory is the failure mode this rule exists to prevent. ## 3. Directions & trade-offs (zoom-in) -Propose **2–4 solution directions** (as many as the situation needs, no padding) — e.g. MVP vs. full, different approaches, different sequencing — each with its **trade-offs** (cost, risk, time-to-value, reversibility). Recommend one with a reason, and **wait for the PO to choose or refine.** Ground every direction in the framing; never fabricate. +Propose **2–4 solution directions** (as many as the situation needs, no padding). Note the object here is different from `plan-backlog`'s framing: this is **what the product is / which approach** (e.g. rehab-adherence vs. general fitness; a novel core mechanic vs. a known one), not *how to slice the work into a backlog* — that stays downstream. Give each its **trade-offs** (cost, risk, time-to-value, reversibility). Recommend one with a reason, and **wait for the PO to choose or refine.** Ground the trade-offs the same way as everything else: option-generation is fine, but any supporting *fact* is `[proposed]`/`[unverified]` until the PO confirms it. + +The flow is **not forward-only**: if, while assembling §4, the PO wants to revisit or withdraw the direction chosen here, go back and re-open §3 rather than editing around a decision that no longer holds. A definition whose Chosen direction was silently un-decided is worse than one that loops back. ## 4. Produce the definition (approval-gated) -Assemble a structured **product definition / brief**. Canonical template — **must-have** sections: +Assemble a structured **product definition / brief**. **Every line carries its provenance marker** (`[PO]` / `[spark]` / `[proposed]` / `[unverified]`, per **Grounding & provenance**) — this is what stops an approved doc from reading as sourced when it isn't. Any must-have section the PO didn't settle is recorded as **"not established"** with a note on what would settle it — never invented to avoid a gap. + +Canonical template — **must-have** sections: - **Problem statement** — one or two sentences. - **Target users** — and non-users. - **Goals** and **Non-goals**. -- **Success metrics**. +- **Success metrics** — or *"not established"* (POs often decline; that's a valid state, a fabricated number is not). - **Chosen direction** — plus the alternatives considered and why this one. -- **Key decisions** — the calls made during framing, with their rationale. +- **Key decisions** — the calls made during framing, each with its rationale *and who made it* (a call the PO delegated to you is marked `[proposed]`, not rendered like one they made). +- **Risks / unknowns** — what the definition rests on that could be wrong, including every `[unverified]` claim that survived into the doc. **Must-have**: this is the section that qualifies the confident ones, so it can't be optional. - **Open questions** — what's still undecided. -**Optional** sections when the material warrants: constraints, risks/unknowns, why-now, dependencies, a rough phasing sketch. +**Optional** sections when the material warrants: constraints, why-now, dependencies, a rough phasing sketch. -**Approval gate (mandatory).** Present the full definition and **wait for explicit approval**; the PO may edit anything. Nothing is finalized — and nothing downstream (no backlog, no tickets) happens here — until they approve. +**Approval gate (mandatory).** Present the full definition and **wait for explicit approval**; the PO may edit anything. Before asking for the OK, ask one grounding question explicitly: **"what in here rests on something nobody has verified?"** — walk the `[unverified]`/`[proposed]` claims so the PO approves them knowing what's assumed, not just what's asserted. Nothing is finalized — and nothing downstream (no backlog, no tickets) happens here — until they approve. **Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** Render the definition as a **navigable artifact** (collapsible sections, a table of contents, easy to scan and drill into) as the review aid — reusing the same doctrine as `plan-backlog`'s review artifact. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate*: still print a concise summary and ask for approval **in the conversation**. On hosts without artifacts (Codex / Cursor / Copilot), present the definition as Markdown. @@ -72,10 +98,14 @@ Assemble a structured **product definition / brief**. Canonical template — **m On approval, hand the definition to `plan-backlog` as its input: *"the definition is ready — run `/plan-backlog` on it to turn it into a backlog."* Because the problem is now defined, `plan-backlog`'s framing step is lighter — it confirms the framing rather than re-deriving it. That completes the loop **define → backlog → ticket → PR**. +**Readiness — say it plainly.** A definition can be *approved* without being *backlog-ready*: if core must-haves are still "not established", or the doc leans on `[unverified]` claims, **tell the PO that** at handoff rather than passing it downstream as settled. `plan-backlog`'s lighter framing trusts a grounded definition; a thin one should either loop back here to firm up, or be handed on with the gaps flagged so `plan-backlog` re-derives instead of confirming. Don't let approval alone stand in for readiness. + +**Persisting for a later session.** If the backlog won't be built in the same sitting, the definition needs a carrier — offer to save it to `docs/definitions/.md` so `plan-backlog` can read it as an input file later. Without that, an in-conversation-only definition can't reach a future `plan-backlog` run. + ## Guardrails - **Facilitate, never decide:** ask, offer alternatives, and let the PO make the call at each step — don't hand them a finished definition and call it done. -- **Never fabricate** the problem, users, metrics, or direction — ground everything in the intake plus the PO's answers. A thin spark is drawn out with questions, not invented. +- **Grounding over fluency (see Grounding & provenance):** generating options is the job; asserting unverifiable facts as established is not. Mark every claim's provenance, keep `[unverified]` market/novelty claims out of the load-bearing prose (or clearly flagged), and prefer a marked gap to an invented answer. A thin spark is drawn out with questions, not filled in for the PO. - **No backlog, no tickets here** — that's `plan-backlog`. This step stops at an approved definition. - **Approval gate** before the definition is finalized. - Watch for **secrets/PII** in the source material; don't copy them into the definition. diff --git a/skills/plan-backlog/SKILL.md b/skills/plan-backlog/SKILL.md index fd4f4d9..7bd4494 100644 --- a/skills/plan-backlog/SKILL.md +++ b/skills/plan-backlog/SKILL.md @@ -30,6 +30,7 @@ Read `.claude/dev-kit.json` at the consuming repo root. The `tracker` block name - **Word (`.docx`)** → not natively readable; convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF. - **Artifact / Confluence page / URL** → fetch it. - **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context. +- **A `plan-definition` product definition** — passed in chat, or a `docs/definitions/.md` file → read it as the source. It carries the framing already (problem, users, goals/non-goals, metrics, chosen direction), which is what triggers the **lighter framing** in §4a. Check its provenance markers / "not established" / `[unverified]` notes: a definition that flags core gaps is **not** ready for the light path (see §4a). Work only from what the source says plus what the user confirms — **never invent scope or acceptance criteria.** @@ -64,7 +65,7 @@ Move through **three levels**; at each, present **2–4 alternatives** (as many **4a. Framing (zoom-out) — help *define*, not just structure.** Restate the goal and map the problem space (users, outcomes, constraints, unknowns). Offer 2–4 **framing alternatives** — e.g. MVP vs. full, different ways to slice the initiative, different sequencing — with the trade-offs of each. → PO chooses the framing. -> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed. Run a **lighter framing**: *confirm* the definition's direction and slice from it, rather than re-deriving the problem space from scratch. Only re-open framing if the definition leaves the backlog-relevant slicing genuinely undecided. +> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed — *if it's grounded.* Before taking the light path, **check the definition, not just its headings**: a doc whose core must-haves are "not established", or whose thesis rests on `[unverified]` claims, is a spark with a template around it — treat it as an ordinary idea and frame from scratch (§4a). Only when the definition is genuinely grounded, run a **lighter framing**: *confirm* its direction and slice from it rather than re-deriving. Also re-open framing if the definition leaves the backlog-relevant slicing undecided. The presence of the five sections is not the signal; their groundedness is. **4b. Epics / themes.** For the chosen framing, propose the epics/themes with **alternatives** where the breakdown could reasonably differ. → PO adjusts. diff --git a/skills/plan-definition/SKILL.md b/skills/plan-definition/SKILL.md index 772e65e..f86aa1b 100644 --- a/skills/plan-definition/SKILL.md +++ b/skills/plan-definition/SKILL.md @@ -28,11 +28,30 @@ The input is deliberately vaguer than `plan-backlog`'s — **a one-liner is a va - **Artifact / Confluence page / URL** → fetch it. - **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context. For a **FigJam** board, `figma-fetch` doesn't read `/board/` URLs yet — ask the PO to paste the board's content as text. v1 treats any whiteboard as **read-only context**; nothing is written back to it. -Work only from what the source says plus what the user confirms — **never invent the problem, users, or metrics.** If the spark is thin, that's expected: the framing step (§2) is where you draw it out with questions. +If the spark is thin, that's expected — the framing step (§2) is where you draw it out with questions, not where you fill it in for the PO. See **Grounding & provenance** next; it governs the whole flow. + +## Grounding & provenance (the core rule — read before drafting) + +A one-liner is a valid start, so most of what a definition could contain is **not** in the intake. That is fine — but it makes *how you introduce content* the thing that keeps this honest. Two moves that look identical on the page are completely different: + +- **Generating options for the PO to choose** — proposing 2–4 framings, directions, or candidate answers and letting the PO pick — is **the point of this skill.** Do it freely. +- **Asserting facts about the world** the PO didn't give you — "no mainstream app does X", "this is why people churn", "the market for Y is underserved", a specific metric target — is **fabrication when stated as established.** You cannot verify market, prior-art, or novelty claims here; the skill has no research step. So: + - Offer them as the PO's to confirm ("*is it true that…?*"), or + - Mark them **unverified** in the definition, or + - Leave them out. + +**Every claim in the definition carries a provenance marker** so a proposal never renders identically to a decision: + +- `[PO]` — the PO stated or explicitly confirmed it. +- `[spark]` — it came from the intake source. +- `[proposed]` — you generated it; the PO accepted the option but the *content* is yours. +- `[unverified]` — a factual claim about the world that nobody has checked (all market/novelty/prior-art claims are at least this). + +The distinction to never blur: **a direction the PO selected from your options is a real decision; a fact you supplied to justify it is not, until it's checked.** When in doubt, mark it lower, not higher. ## 2. Frame the problem (zoom-out) — guided questions, proposed answers -Draw out the definition through a **Socratic** exchange: for each dimension, ask, **propose a candidate answer grounded in the intake**, and let the PO confirm or adjust. Offer options; don't assume. Move through: +Draw out the definition through a **Socratic** exchange: for each dimension, ask, **propose a candidate answer**, and let the PO confirm or adjust. Proposing candidates is exactly right (see **Grounding & provenance**) — just don't smuggle in unverifiable *facts* as if they were established (mark those `[unverified]` or ask). Offer options; don't assume. Move through: - **Users / audience** — who is this for, and who is it *not* for? - **Problem / outcome** — what problem, and what does success look like for the user? @@ -42,27 +61,34 @@ Draw out the definition through a **Socratic** exchange: for each dimension, ask - **Risks / unknowns** — what could break the thesis; what we still don't know. - **Non-goals** — explicitly out of scope, to keep the definition sharp. -Don't interrogate all seven in one dump — work them conversationally, a few at a time, folding the PO's answers back in. It's fine to leave items in **open questions** rather than force an answer. +Don't interrogate all seven in one dump — work them conversationally, a few at a time, folding the PO's answers back in. It's fine — often better — to leave an item **explicitly unresolved** rather than force an answer: any must-have section may carry *"not established"* with a note on what's needed to settle it (see §4). This applies especially to **Success metrics**, which POs frequently decline — record "not established (no baseline yet)", never a number you made up. + +**No research step.** The skill fetches only PO-supplied sources (§1); it does not browse. So when a dimension turns on a fact you'd normally look up — *"which segment is underserved?"*, *"has anyone shipped this?"* — you **cannot answer it as fact.** Say so, offer it as a question for the PO or a later research task, and mark any market/novelty claim `[unverified]`. Confidently reciting a competitive map from memory is the failure mode this rule exists to prevent. ## 3. Directions & trade-offs (zoom-in) -Propose **2–4 solution directions** (as many as the situation needs, no padding) — e.g. MVP vs. full, different approaches, different sequencing — each with its **trade-offs** (cost, risk, time-to-value, reversibility). Recommend one with a reason, and **wait for the PO to choose or refine.** Ground every direction in the framing; never fabricate. +Propose **2–4 solution directions** (as many as the situation needs, no padding). Note the object here is different from `plan-backlog`'s framing: this is **what the product is / which approach** (e.g. rehab-adherence vs. general fitness; a novel core mechanic vs. a known one), not *how to slice the work into a backlog* — that stays downstream. Give each its **trade-offs** (cost, risk, time-to-value, reversibility). Recommend one with a reason, and **wait for the PO to choose or refine.** Ground the trade-offs the same way as everything else: option-generation is fine, but any supporting *fact* is `[proposed]`/`[unverified]` until the PO confirms it. + +The flow is **not forward-only**: if, while assembling §4, the PO wants to revisit or withdraw the direction chosen here, go back and re-open §3 rather than editing around a decision that no longer holds. A definition whose Chosen direction was silently un-decided is worse than one that loops back. ## 4. Produce the definition (approval-gated) -Assemble a structured **product definition / brief**. Canonical template — **must-have** sections: +Assemble a structured **product definition / brief**. **Every line carries its provenance marker** (`[PO]` / `[spark]` / `[proposed]` / `[unverified]`, per **Grounding & provenance**) — this is what stops an approved doc from reading as sourced when it isn't. Any must-have section the PO didn't settle is recorded as **"not established"** with a note on what would settle it — never invented to avoid a gap. + +Canonical template — **must-have** sections: - **Problem statement** — one or two sentences. - **Target users** — and non-users. - **Goals** and **Non-goals**. -- **Success metrics**. +- **Success metrics** — or *"not established"* (POs often decline; that's a valid state, a fabricated number is not). - **Chosen direction** — plus the alternatives considered and why this one. -- **Key decisions** — the calls made during framing, with their rationale. +- **Key decisions** — the calls made during framing, each with its rationale *and who made it* (a call the PO delegated to you is marked `[proposed]`, not rendered like one they made). +- **Risks / unknowns** — what the definition rests on that could be wrong, including every `[unverified]` claim that survived into the doc. **Must-have**: this is the section that qualifies the confident ones, so it can't be optional. - **Open questions** — what's still undecided. -**Optional** sections when the material warrants: constraints, risks/unknowns, why-now, dependencies, a rough phasing sketch. +**Optional** sections when the material warrants: constraints, why-now, dependencies, a rough phasing sketch. -**Approval gate (mandatory).** Present the full definition and **wait for explicit approval**; the PO may edit anything. Nothing is finalized — and nothing downstream (no backlog, no tickets) happens here — until they approve. +**Approval gate (mandatory).** Present the full definition and **wait for explicit approval**; the PO may edit anything. Before asking for the OK, ask one grounding question explicitly: **"what in here rests on something nobody has verified?"** — walk the `[unverified]`/`[proposed]` claims so the PO approves them knowing what's assumed, not just what's asserted. Nothing is finalized — and nothing downstream (no backlog, no tickets) happens here — until they approve. **Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** Render the definition as a **navigable artifact** (collapsible sections, a table of contents, easy to scan and drill into) as the review aid — reusing the same doctrine as `plan-backlog`'s review artifact. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate*: still print a concise summary and ask for approval **in the conversation**. On hosts without artifacts (Codex / Cursor / Copilot), present the definition as Markdown. @@ -72,10 +98,14 @@ Assemble a structured **product definition / brief**. Canonical template — **m On approval, hand the definition to `plan-backlog` as its input: *"the definition is ready — run `/plan-backlog` on it to turn it into a backlog."* Because the problem is now defined, `plan-backlog`'s framing step is lighter — it confirms the framing rather than re-deriving it. That completes the loop **define → backlog → ticket → PR**. +**Readiness — say it plainly.** A definition can be *approved* without being *backlog-ready*: if core must-haves are still "not established", or the doc leans on `[unverified]` claims, **tell the PO that** at handoff rather than passing it downstream as settled. `plan-backlog`'s lighter framing trusts a grounded definition; a thin one should either loop back here to firm up, or be handed on with the gaps flagged so `plan-backlog` re-derives instead of confirming. Don't let approval alone stand in for readiness. + +**Persisting for a later session.** If the backlog won't be built in the same sitting, the definition needs a carrier — offer to save it to `docs/definitions/.md` so `plan-backlog` can read it as an input file later. Without that, an in-conversation-only definition can't reach a future `plan-backlog` run. + ## Guardrails - **Facilitate, never decide:** ask, offer alternatives, and let the PO make the call at each step — don't hand them a finished definition and call it done. -- **Never fabricate** the problem, users, metrics, or direction — ground everything in the intake plus the PO's answers. A thin spark is drawn out with questions, not invented. +- **Grounding over fluency (see Grounding & provenance):** generating options is the job; asserting unverifiable facts as established is not. Mark every claim's provenance, keep `[unverified]` market/novelty claims out of the load-bearing prose (or clearly flagged), and prefer a marked gap to an invented answer. A thin spark is drawn out with questions, not filled in for the PO. - **No backlog, no tickets here** — that's `plan-backlog`. This step stops at an approved definition. - **Approval gate** before the definition is finalized. - Watch for **secrets/PII** in the source material; don't copy them into the definition.