feat: /plan-definition — a guided discovery/definition phase upstream of plan-backlog
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 14
- Forks
- 2
- Avg merge
- 9h 52m
- Merged PRs (30d)
- 16
Description
Spin-off from #72 (idea from @santielizondo).
The gap
plan-backlog starts from a defined problem and turns it into a backlog. But the hardest, most valuable part often comes before that: defining the problem — the discovery/definition thinking. plan-backlog's guided framing step is deliberately light ("how do we slice this into a backlog"); it is not deep product definition. /plan-definition fills that: a guided discovery/definition phase that produces a clear problem definition, which then feeds plan-backlog.
Full flow becomes: /plan-definition (define the problem) → /plan-backlog (turn it into a backlog) → ticket → PR → follow-ups.
What it does (proposed)
A guided, Socratic phase — facilitate, don't decide — moving zoom-out → zoom-in:
- Intake — a spark in any form (even a one-liner; vaguer than
plan-backlog's input). Reuse the multi-format intake (text / PDF / Word / artifact / Confluence / Figma). - Frame the problem — guided questions + proposed answers to confirm/adjust: users, the problem/outcome, why now, constraints, success metrics, risks/unknowns, non-goals. Offer options, don't assume.
- Directions & trade-offs — propose 2–4 solution directions (e.g. MVP vs full, different approaches/sequencing) with trade-offs → PO chooses/refines.
- Produce a definition — a structured product definition / brief (problem statement, users, goals & non-goals, success metrics, chosen direction, key decisions, open questions). Rendered as a rich navigable artifact on Claude (reuses #74), Markdown elsewhere. Approval-gated.
- Handoff — the definition becomes the input to
/plan-backlog, whose framing step is then lighter because the problem is already defined.
Boundary with plan-backlog (important)
/plan-definition= define the problem & direction — no backlog, no tickets./plan-backlog= turn a defined problem into a backlog (and, when a definition exists, consume it instead of re-framing from scratch).
Discovery surfaces (Santi's idea)
Collaborative whiteboards fit discovery well:
- FigJam — via the existing Figma connector, could be a context source (read a board) and/or a place the definition maps to. (Figma MCP is already in the kit.)
- Miro — no first-party connector today; treat as out-of-scope for v1 unless one exists.
v1 could be text + rich artifact, with FigJam as an optional context input; deeper whiteboard integration is a follow-up.
Guardrails (same doctrine)
- Facilitate, never decide for the PO. Offer alternatives, ask for decisions.
- Never fabricate — ground everything in the intake + the PO's answers.
- Approval gate before the definition is finalized; nothing downstream (no tickets) until
plan-backlog. - Portable across hosts (skill + a Claude command/agent, like
plan-backlog).
Open questions (to refine)
- Separate command/skill (
/plan-definition) vs a "deep-definition" mode ofplan-backlog? (Leaning separate — different output: a definition doc, not a backlog.) - The canonical definition template — which sections are must-have vs optional?
- Where the definition lives: an artifact only, a committed file, or a Confluence page?
- FigJam in v1: read-only context, or also produce/seed a board? Worth it now?
- How much of
plan-backlog's framing should collapse when a definition is handed in?
Design-only for now — capturing so it can be refined before any build. Relates to #72 / #74.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the related issues #72 and #74, then review the existing plan-backlog flow and Claude command/agent pattern referenced here. This issue is design-only: done means resolving the open questions and agreeing the definition scope, template, handoff, approval gate, and FigJam boundary before implementation begins.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- ai, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100