/feature-refinement

Summary

An interactive senior product thinker that guides you from a rough feature idea to a well-scoped Feature Brief saved to the project, ready for /plan-maker. It assumes you may be a product owner or end user with no knowledge of the codebase or the technology — everything is written in plain language, and when a decision hinges on a technology, it explains that technology in one plain sentence first.

When to use

Use /feature-refinement when you have a feature idea but not yet a clear scope, user flow, or decision log. The command investigates your codebase, challenges your assumptions, and asks targeted questions until the feature is well-defined — then produces a structured Feature Brief file.

It is also described in the agentic workflow pipeline (agentic-workflow-en.html) as the upstream step before planning and implementation.

Typical trigger situations:

• You have a rough feature idea and need to scope it before writing a plan.
• You want an adversarial product thinker to challenge your assumptions before you commit to a direction.
• You need a Feature Brief file (Documentation/Backlog/…-brief.md) as input for /plan-maker.
• You want to surface conflicts, risks, or prior decisions from the codebase before designing a solution.
• You are a product owner or non-technical stakeholder — the command requires no codebase or technology knowledge, so you can use it directly.

Invocation

Pass your feature idea as the argument. The command starts by investigating the codebase, then enters an iterative clarification loop.

/feature-refinement [feature idea or description]

Parameters:

• [feature idea or description] — (required) A short description of the feature you want to refine. Can be a sentence, a rough user story, or a few bullet points.

Output: A Feature Brief Markdown file saved to Documentation/Backlog/[feature-name-kebab-case]-brief.md (or project root if that directory does not exist). The brief covers: Problem, Goal, Users & Context, Core Flow, In Scope, Out of Scope, Key Decisions, Edge Cases & Constraints, Open Questions, Future Iterations, and a Recommendation. The brief is written in plain language, except the Open Questions section, which stays technical — it is addressed to /plan-maker and engineers.

Process phases:

1. Phase 1 — Investigate: Spawns two parallel Explore agents — one for documentation (READMEs, ADRs, specs), one for source code — then flags any place where docs contradict code. Large projects split into up to ~4 agents by area.
2. Phase 2 — Clarify, Challenge & Ideate: Iterative rounds — each round challenges assumptions and asks ≤3 framed questions — each phrased as a choice about what you see or do, never about implementation — until scope, flow, and edge cases are resolved. Challenges and questions share one global number sequence (#1, #2, ...) that never resets between rounds, so you can answer tersely ("#2: yes, #4: skip").
3. Phase 3 — Feature Brief: Produces and saves the structured brief, then suggests running /plan-maker [path].

Example 1 — Refine a new notification feature (illustrative example)

/feature-refinement Add email notifications when a task is assigned to a user

Investigating the codebase before we start...

Docs agent: no ADRs on notifications; README lists email as a roadmap item.
Code agent: existing User model, Task model with assignee_id FK, no email infrastructure yet,
a TODO comment in task_service.py referencing future notifications.

**#1 (challenge) [Scope]**
- Option A: Email only — simple, ships fast. Con: will need rework when push notifications arrive.
- Option B: Generic notification system with email as first channel — more upfront work, extensible.
- Recommendation: Option A for now; design the interface to be swappable. Agree?

#2 (question): Should the assignee receive an email immediately on assignment, or in a daily digest?
  A) Immediate — users get context faster. Con: noisy for high-volume projects.
  B) Configurable per-user — best UX. Con: adds a settings screen to scope.
  C) Immediate for now, configurable later — pragmatic. Recommendation: C.

[After user responds...]

Saved: Documentation/Backlog/task-assignment-notifications-brief.md
Run `/plan-maker Documentation/Backlog/task-assignment-notifications-brief.md` to create an implementation plan.

Example 2 — Scope a search feature with conflicting constraints (illustrative example)

/feature-refinement Full-text search across all project documents

Investigating the codebase before we start...

Docs agent: prior ADR-007 deferred search to "Phase 2".
Code agent: PostgreSQL 15, 3 document types (notes, tasks, files), existing ILIKE queries in search_service.py,
no full-text index, ~50k rows in production.
Contradiction flagged: ADR-007 defers search, but search_service.py already ships ILIKE queries.

**#1 (challenge) [Risk]**
- ADR-007 deferred this — do you know why? Options:
  A) Performance concern — full-text on 50k rows is fine for pg_trgm; address it.
  B) Scope concern — previous team wanted to ship faster; now it's time.
  Recommendation: Clarify before scoping to avoid repeating the same decision.

#2 (question): Which document types must be searched in v1?
  A) All three (notes, tasks, files) — complete but more complex.
  B) Notes and tasks only, files deferred — ships faster, covers 90% of use cases.
  Recommendation: B.

[After 2 rounds...]

Saved: Documentation/Backlog/full-text-search-brief.md
Run `/plan-maker Documentation/Backlog/full-text-search-brief.md` to create an implementation plan.

Related tools

• /plan-maker — Turns the Feature Brief produced by /feature-refinement into a phased implementation plan with tasks, acceptance criteria, and TDD sub-items.
• /plain-language — The shared writing convention /feature-refinement loads at the start: plain consequence first, technical specifics in parentheses.