plan-backlog: guided, project-maturity-aware mode (from user feedback)

[atamanvega]

Motivation — user feedback

From an early user (Santi) trying plan-backlog on a real Android app — working well overall.

In short: plan-backlog produces a good plan, but does too much in one shot — it absorbs the product-discovery/definition that should be the PO's, and hands every decision to the agent. It should elaborate progressively (zoom-out → zoom-in) with alternatives and decision points at each level; how much depth is right depends on maturity.

Two sharp observations about plan-backlog specifically:

• It felt overwhelming — too much at once (a full backlog in a single shot). (Fair to note: that may not be the intended usage.)
• It produced a good plan, but absorbed part of the product discovery that should be the PO's definition work. It should move in steps from zoom-out to zoom-in (high-level → detailed), offering alternatives at each level, rather than handing every decision to the agent. The agent should facilitate discovery, not replace the PO's judgement.

The two things this identifies

1. It absorbs product discovery. plan-backlog's "discovery-first" today means discovering the tracker's conventions (issue types, hierarchy) — not product discovery (exploring the problem, scope, options). So it jumps straight to a full solution and eats the definition work that's the PO's job.
2. It's one-shot / all-decisions-to-the-agent. One big draft + a single end gate = all-or-nothing. The ask is progressive elaboration with decisions along the way.

Design — guided mode, decided per invocation

Guided (progressive) mode — zoom-out → zoom-in, alternatives at each level

1. Framing (zoom-out): restate the goal, map the problem space, and help define the project/feature — offer 2–4 framing alternatives (e.g. MVP vs full, different ways to slice it) → PO chooses.
2. Epics/themes: for the chosen framing, propose epics with alternatives → PO adjusts.
3. Stories: per epic, user stories + acceptance criteria, offering scoping alternatives → PO refines.
4. Assemble → approve → create (today's gate + creation).

3 levels; each step offers options (2–4, as needed) and asks for a decision instead of emitting a full backlog at once.

Mode: guided by default, decided per invocation (settled)

• Default = guided. --quick is an explicit opt-in for the one-shot draft. Even on mature projects, still do a light framing check — don't assume framing is unneeded.
• Decided per invocation, never persisted. There are two maturities: the project's and the feature's — a mature project can still have a brand-new feature — so a persisted mode would be wrong. Judge each run.
• Maturity signals (discovery-first, never imposed): repo docs (an empty repo vs. one with a defined stack + conventions), and how much useful context the brief carries. Ask once only when ambiguous.

Guardrails preserved in both modes: approval gate, no fabrication, adapters for Jira/Linear/GitHub/Azure.

Decisions (settled with early feedback)

• Zoom levels: 3 (framing → epics → stories); framing must help define, not just structure.
• Alternatives per step: variable, 2–4.
• Maturity signals: repo docs + brief context.
• Default mode: guided; --quick opts into the one-shot draft; keep a framing check even for mature projects.
• Mode persistence: per invocation only — project maturity ≠ feature maturity.

Out-of-scope spin-offs

• feat: /plan-definition — a guided discovery/definition phase upstream of plan-backlog #73 — /plan-definition: a guided discovery/definition step upstream of plan-backlog (could lean on FigJam/Miro).
• idea: richer artifact format for generated plans (navigable/collapsible/searchable HTML) #74 — richer plan artifacts (navigable/collapsible/searchable HTML) for the review step.

Design settled with early feedback — ready to carve a v1 of the guided mode. Thanks @santielizondo!

[atamanvega]

@santielizondo — this captures your plan-backlog feedback (thanks again!). Would love your take on the direction, and especially the open questions: the right number of zoom levels, how many alternatives per step feels useful vs noisy, and the best signals for judging project maturity. Refine away.

[santielizondo]

Thanks, @atamanvega. The issue covers all the feedback in depth. So far it looks like it's the right direction to handle it.

On the open questions:

• Zoom levels: 3 levels seem good enough. The framing should be able to help user on the definition of the project or feature
• Alternatives per step: number of alternatives should vary depending on what's needed. 2-4 could be reasonable.
• Maturity signals:
  • Repo docs. From an empty one - it was my case when I used the skill - versus an existing one with tech stack defined, conventions, etc)
  • Users brief: There should be useful context on it.
• Quick draft for mature projects: I would also try to find if the framing is needed even for those. I would set up the default mode as guided. Users could add the flag to launch the quick draft.
• Persisted mode: I lean toward a per-invocation only. Maturity could have different levels. Maturity of the project and maturity of the feature.

For sure this is an opinionated feedback coming from a single project created from scratch. All the comments are my personal preference, so it doesn't mean it would cover all people needs.

I will continue using it so you can expect more feedback :)

---

Maybe 2 extra notes that are out of scope for this issue:

• Since the kit already integrates Figma, Linear, etc. Tools like FigJam or Miro could support the discovery/definition side. A guided /plan-definition could be a good starting point for /plan-backlog
• For the plans docs you could try a richer format artifact. Like HTML with navigation, collapsible sections, searchable, filterable, ... @miryamgduque has been creating artifacts on her research and definition tasks and it's been a big improvement

[atamanvega]

Thanks @santielizondo — hugely helpful, and the project-maturity vs feature-maturity distinction is the key one: it's exactly why the mode shouldn't be persisted. Folded your answers into the design above:

• Default = guided, --quick as the opt-in; keep a light framing check even on mature projects.
• 3 zoom levels, framing helps define (not just structure); 2–4 alternatives per step, as needed.
• Maturity from repo docs + brief context, judged per invocation (project maturity ≠ feature maturity).

Your two out-of-scope ideas were too good to lose — captured as follow-ups: #73 (/plan-definition discovery step, incl. FigJam/Miro) and #74 (richer navigable HTML plan artifacts, per @miryamgduque's approach). Keep the feedback coming as you use it 🙏

[atamanvega]

@santielizondo — your feedback is implemented: #75 makes plan-backlog guided by default.

It elaborates progressively over three levels (framing → epics → stories), offering 2–4 alternatives and waiting for your decision at each — the framing step helps define, not just structure. --quick keeps the one-shot draft, and the mode is chosen per invocation from repo docs + brief context (never persisted, since project maturity ≠ feature maturity).

Once it merges you'll get it via auto-update (or claude plugin marketplace update claude-dev-kit). Would love you to try it on your next feature and tell us if the pacing/alternatives feel right — and the two spin-offs from your ideas are tracked in #73 (/plan-definition) and #74 (richer plan artifacts). Thanks again 🙏