playbooks

home / skills / vadimcomanescu / codex-skills / feature-design-assistant

feature-design-assistant skill

/skills/.experimental/product/feature-design-assistant

This skill helps turn ideas into implementable feature specs with clear scope, risks, and acceptance criteria through guided design collaborations.

npx playbooks add skill vadimcomanescu/codex-skills --skill feature-design-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.3 KB
---
name: feature-design-assistant
description: Turn ideas into fully formed designs and specs through natural collaborative dialogue. Use when planning new features, designing architecture, or making significant changes to the codebase.
---

# Feature Design Assistant

Turn ideas into implementable specs with clear scope, risks, and acceptance criteria.

## Workflow
1) **Context**: skim the repo for patterns, modules, and recent changes.
2) **Discovery**: ask up to 4 questions per round.
3) **Design**: propose a solution with trade-offs.
4) **Spec**: write a short design doc with sections below.

## Discovery Questions (examples)
- Goal and primary users?
- Scope and timeline constraints?
- Which layers are touched (data, API, UI, infra)?
- Quality bar (performance, security, reliability)?
- Non-goals / out-of-scope?

## Design Doc Template
- **Problem**
- **Goals / Non-goals**
- **Proposed solution** (components, data flow)
- **Alternatives** (and why rejected)
- **Risks / Open questions**
- **Testing / rollout plan**
- **Acceptance criteria**

## Guardrails
- Keep scope tight; call out what is explicitly excluded.
- Prefer existing patterns unless the user asks to change architecture.
- If the change is large, propose a phased rollout.

## References
- Extended examples: `references/examples.md`

Overview

This skill turns product ideas into actionable design documents and implementation-ready specs through collaborative natural language dialogue. It guides discovery, proposes trade-off aware designs, and produces concise acceptance criteria and rollout plans to reduce ambiguity and development risk.

How this skill works

It begins by scanning repository structure and recent changes to identify patterns and affected layers, then runs a short discovery phase with up to four focused questions per round. Based on answers it drafts a design with components, data flow, alternatives, risks, testing strategy, and clear acceptance criteria. For large changes it suggests phased rollouts and reuses existing patterns by default.

When to use it

  • Planning a new feature from concept to development-ready spec
  • Designing or changing architecture across data/API/UI/infra layers
  • Preparing scope, timelines, and acceptance criteria for a sprint or roadmap item
  • Evaluating trade-offs between multiple implementation approaches
  • Creating a rollout and testing plan for significant codebase changes

Best practices

  • Keep discovery focused: answer up to four questions per round for faster iteration
  • Define goals and non-goals explicitly to limit scope and reduce churn
  • Favor existing repository patterns unless you intend to change architecture
  • Call out risks and open questions early to prioritize mitigation
  • For large features, request a phased rollout and incremental acceptance criteria

Example use cases

  • Convert a product ticket into a one-page design with components, API contracts, and acceptance tests
  • Design a database schema change and outline migration steps and rollback plan
  • Propose API changes with compatibility strategy and client migration guidance
  • Draft a phased rollout and feature flag strategy for a risky refactor
  • Create testing matrix and monitoring plan for a new service endpoint

FAQ

How many discovery questions will you ask?

I ask up to four focused questions per round to avoid overwhelming stakeholders while surfacing critical unknowns.

Will you rewrite existing architecture?

By default I prefer and reuse existing patterns; I only propose architectural changes when explicitly requested or when benefits outweigh costs.

Can you generate acceptance criteria and tests?

Yes. Each spec includes concrete acceptance criteria and a testing/rollout plan, including suggested test cases and metrics to monitor.