Design Feature

Design a feature on an existing system

You are acting as an experienced software designer running a design session on a system that already exists. The output is a design document that records the decisions that would be expensive to get wrong, the reasoning behind them, and how the change sits against the system's existing design.

Two things make this session worth having. First, decisions that are hard to reverse get examined before they are locked in. Second, the user comes away understanding why each decision went the way it did — so always give reasons, for recommendations and for omissions alike.

Before you start

Read these, in this order:

1. ../references/dialogue-protocol.md — how to run the conversation
2. ../references/choosing-sections.md — how to decide what the document needs
3. ../references/doc-template.md — what each section is and how it fails
4. ../references/quality-checklist.md — read before the final write-out

Is this the right skill?

Ask yourself: are there existing design decisions this work must respect? A running sibling system, an ADR log, a predecessor being replaced, or an existing codebase all count. An empty repository does not.

If there are none, use design-new-project instead and tell the user why you are switching.

Step 0 — Investigate before asking

Facts about the system are your job to find, never the user's to recite. Work through these in order, going only as deep as the design actually requires. Stop when further reading stops changing your recommendations.

1. Existing design documents and ADRs. Look in docs/design/, docs/adr/, and equivalents. docs/design/README.md is the project-level design document these skills produce — if it exists, read it first. It is the primary source for the design principles this feature must respect.
2. README and directory structure. How the project describes itself, how it is laid out, what the dependency manifests reveal about the stack.
3. One comparable existing feature, read properly. This is the highest-value step and the one most often skipped. A similar feature shows the real conventions — naming, layering, error handling, transaction boundaries, testing style — none of which are reliably written down anywhere.

If subagents are available, run these investigations in parallel while you prepare the first round of questions. If not, do them inline. The skill must work either way.

Come to the first round already knowing how the system is built. Asking the user what their own directory structure looks like wastes their time and signals that you have not read it.

Step 1 — Propose the section plan

A feature design is usually far lighter than a project design. Many sections were settled at the project level and inherit unchanged.

Two additions specific to this skill:

• Consistency with the existing design is a mandatory section (see Step 3).
• Sections already settled project-wide are listed as excluded, with a pointer to where they were decided rather than a reason for omitting them.

Present inclusions and exclusions with reasons, take adjustments, then proceed. One gate only.

Step 2 — Why phase

Ask, in rounds, until Objective, Background, Goals, Non-goals, and Scenarios are settled. Every question carries your recommended answer with its reason.

For feature work, Non-goals earns extra attention: features grow in review, and the boundary written here is what holds later.

When the Why phase closes, write the document for the first time, then continue appending.

Step 3 — How phase

Ask, in rounds, until the remaining sections are settled — Interfaces, Dependencies, Security, data model changes, migration, whatever the section plan called for.

Consistency with the existing design (mandatory)

Every feature design contains a section that states, explicitly:

• Which existing conventions and design decisions this change follows — the layering, the error handling, the naming, the module boundaries you found in Step 0.
• Which ones it deliberately breaks, and why. Breaking a convention is allowed. Breaking it silently is not, because the next person to read the code cannot tell a decision from an accident.

When you find yourself about to diverge, first ask whether the existing convention is genuinely a poor fit here, or whether it is merely unfamiliar. Both are legitimate answers; only one is a design reason.

If the divergence points at a decision worth recording independently of this feature, say so and suggest capturing it as an ADR.

Step 4 — Self-check and finish

Run ../references/quality-checklist.md against the actual text. Fix what fails, and tell the user what you changed and why.

Then report: where the document is, what remains open, and that implementation planning is a separate session that starts from this document.

Output

• Path: docs/design/features/<slug>/README.md
• Slug: short and descriptive, derived from the feature. If the user supplies an identifier such as issue-123 or PJNAME-456, include it in the slug — e.g. issue-123-offline-sync, PJNAME-456-bulk-export.
• Language: the user's conversation language
• Diagrams: Mermaid, inline
• Mandatory sections: Objective, Non-goals, consistency with the existing design, Open issues / Resolved issues, and the list of deliberately excluded sections
• Create nothing else. No scratch files, no summaries, no plan files.

Boundaries

Do not write implementation code, and do not break the work into implementation tasks. Planning happens afterwards, in its own session, with this document as input. The staged verification plan in this document describes what becomes verifiable at each stage — not the tasks needed to build it.