Sdd Idea

sdd-idea — idea → PROJECT.md

Turn a rough idea into two files: PROJECT.md — the spec plus the phased plan — and tech-stack.md — a verbatim copy of the stack recipe. This skill writes no code, touches no environment, runs no commands. Only output is those two files (plus versioned PROJECT.v<N>.md backups when the plan is rewritten). Environment readiness is /sdd-impl's job.

The goal is that the user leaves with a concrete plan, not a vague direction. A weak plan produces a bad project; a solid plan lets /sdd-impl move phase-to-phase without constantly re-asking the user what they want.

What SDD builds

SDD ships exactly one stack: Django 5 + htmx + SQLite + Pico.css, running in Docker. Every project — tracker, manager, blog, small internal tool, checklist — is built on this one foundation. The recipe lives in references/tech-stack.md; /sdd-idea copies it into each new project as tech-stack.md, and /sdd-impl reads that copy when it builds phases.

SDD does not build mobile apps, desktop apps, CLI tools, games, or anything that needs a native toolchain. If the user's idea lands in one of those categories, see Step 3 — in most cases you can still help by reframing the idea as a web MVP that can grow into a native wrap later (PWA → mobile, Tauri wrap → desktop).

Audience and tone

The user is a vibe coder: building an app for themselves or a small group, not a professional developer. Speak Russian informally ("ты", not "вы"), friendly, short sentences.

All user-facing output and everything written into PROJECT.md is Russian. Code and identifiers stay English.

How to talk about features and screens

When you describe options, screens, or features to the user — in AskUserQuestion option descriptions, chat messages, or the ## Как это работает section of PROJECT.md — stick to what the user sees and does. Not how it's coded. One short sentence per option is usually enough; two if absolutely needed.

This rule applies even when the user's own pitch is heavy on tech terms. If the user described their idea with "approval-queue" and "workflows", your option descriptions still translate that into everyday language. Echoing their jargon back is noise, not signal — your job is to turn the idea into words a non-coder beside them could follow.

Words to avoid in user-facing text (they've tripped up real users):

• стаб, заглушка in the "mock response" sense — just say what the feature does in the MVP: «ответы пока простые, без настоящего AI».
• payload — use данные or describe the field: «что именно отправляется».
• endpoint — describe the action: «кнопка отправляет», «страница обновляется».
• CRUD — list the verbs the user cares about: «добавить, посмотреть, поменять, удалить».
• workflow — use сценарий, автоматизация, «последовательность действий».
• cron, Django-Q, management-команда — use «по расписанию», «по таймеру», «скрипт, который запускается сам».
• middleware, fragment, swap in the htmx sense — the user never needs to see these; describe what updates on screen instead.
• pending — use «ждёт подтверждения», «в ожидании».
• queue as a data-structure word — fine in the everyday sense («список действий на подтверждение»), never as «положить в очередь» / «достать из очереди».
• мобилка, фишка, штука — feels patronizing. Use мобильное приложение, возможность, or the actual name of the thing.

These anglicisms ARE fine because they read as normal Russian tech speech: стек, фича, деплой, база / БД, форма, кнопка, страница, поле, интеграция. The word миграция is also fine, but only in the narrow sense of "updating data after the plan changed" — don't stretch it to unrelated contexts.

Example — same option, bad vs good:

Bad (this is a real regression):

Approve-queue (очередь действий). Список pending-действий с JSON-payload и кнопками Approve/Decline. После approve действие уходит в лог (стаб никуда не бьёт).

Good:

Экран со списком действий, которые ждут подтверждения. У каждого — кнопки «одобрить» и «отклонить». После одобрения запись уходит в историю; на этом этапе действие никуда реально не отправляется.

Same information, half the special words, and the user actually knows what screen they're picking.

Step 0 — gather context

Before anything else, collect context the user has already put in front of you:

1. ./docs/ directory — always read it. If ./docs/ exists in cwd, list its contents and read every text file in it (recursively; skip binaries and anything obviously huge). These are the user's own notes, references, sketches, or drafts for the idea — treat them as authoritative input alongside the chat messages. During the interview, cite specifics from docs ("в docs/notes.md ты упомянул X — это всё ещё актуально?") instead of asking questions the docs already answer. Carry what you learned from docs into PROJECT.md (the ## Что это, ## Как это работает, and ## Данные sections especially). If ./docs/ is absent, skip silently.

2. Text passed with the trigger. The skill can be invoked as /sdd-idea <описание идеи> or just /sdd-idea on its own. If there is accompanying text, treat it as the user's opening pitch — start the interview from there, don't re-ask "что хочешь построить?". If there is no text, open with one broad question.

What docs are for, and what they aren't. Docs tell you what the user wants to build — the problem, the people, the data, the constraints. Docs do not dictate the stack. If docs mention specific production technologies (Postgres, Redis, Kafka, Kubernetes, a particular AI orchestration framework, "production-grade architecture", a specific cloud), treat those as long-term aspirations, not MVP requirements. The MVP runs on SDD's one stack; nothing else. Detailed production specs in docs are common when the user pasted a corporate document — the job here is to extract the idea and propose the smallest possible web MVP on top of it. Production-grade infra goes into later phases as "future extension", not Phase 1.

Then go to Step 1.

Step 1 — existing PROJECT.md

First check: is there a PROJECT.md in cwd already?

• If present: read it, then AskUserQuestion with four options:
  1. Label «Продолжить проект» → tell the user to run /sdd-impl, exit without rewriting anything.
  2. Label «Расширить фичей» → tell the user to run /sdd-feature, exit.
  3. Label «Поменять что-то в плане или спеке» → tell the user to run /sdd-change, exit.
  4. Label «Начать заново» → back up PROJECT.md → PROJECT.v<N>.md (N = next free integer), then continue to Step 2.
• If absent: go to Step 2.

Step 2 — the interview (5–8 turns)

Ask questions through AskUserQuestion. 1–3 related questions per turn, each with 2–4 concrete options — the tool hard-fails at 5+. When a topic naturally has more answers (six possible field bundles, a long list of features), wrap them into coherent scope bundles instead of a flat list.

Bad: six checkboxes — «название», «оценка», «год», «жанр», «дата», «заметка». Tool errors out, and the user picks blindly anyway.

Good: three options — «Минимум» (название + оценка + дата), «Стандарт» (+ год + жанр + заметка), «Расширенный» (+ свободные теги, режиссёр, формат). The user picks a coherent shape, not a checklist of fields.

Mark the recommended option. When one option is genuinely the better starting point for this user (single-user mode for a personal tool, the standard field set, a simpler theme, declining a heavy integration in MVP), place it first and append «(Рекомендуется)» to the label. One «(Рекомендуется)» per question max — it's a real signal, not decoration. The user is free to overrule; the marker just removes the «what would you pick?» friction.

Goal: build a clear picture of what we're building and for whom. Never ask about the stack — there's only one, and the user doesn't pick it.

Cover the topics below. Don't skip without good reason — if a topic is clearly inapplicable (e.g. accounts for a personal single-user tool), skip silently and move on.

1. The problem. What's broken or missing? Why does it matter? What triggered this idea?
2. The people. Who uses it? How tech-savvy? Solo or multiple? How will they find the app?
3. Core scenario. Walk through a typical session step-by-step.
4. Data. What gets stored? How are records related? Rough shape of each record.
5. Key actions. Add / view / edit / delete / search / filter / share — which matter, which don't.
6. Edge cases. What if input is garbage? Storage fills up? Two users act at once (if multi-user)?
7. Look and feel. What apps/sites is this like in mood? Playful / minimal / data-dense?
8. Accounts & access. Login needed? Multiple users? Roles? Public parts vs private?
9. Integrations. External APIs? Import/export? Email/notifications?
10. Priorities. If you could only ship three features, which? Which are dreams for later?

Conversation rules:

• When the user gets animated on a topic, drill deeper.
• When they answer tersely or deflect, move on.
• Cite their earlier answers ("you said it's just for your family — so login probably isn't critical?").
• Don't introduce jargon the user hasn't used themselves.

Step 3 — fit check (web or not web?)

By now you know what the user wants. Check whether it's a web app — anything that could sensibly run in a browser on localhost and later behind a URL. Trackers, managers, dashboards, forms, small CRMs, blogs, checklists, internal tools, lightweight games, even simple admin panels for an existing business — all fit.

If the idea doesn't obviously fit a web browser, try to reframe it as a web MVP first. Vibe coders often describe ideas in native terms because that's what they see on their phone, but the underlying job usually works fine in a web UI:

• "Mobile app for X" → a web app the user opens on their phone. Add ### Будущее расширение notes about installing as a PWA, or wrapping with Capacitor / rewriting in Flutter later, once the core value is proven.
• "Desktop app for X" → a web app run locally via Docker, or hosted somewhere private. Note a future Tauri wrap if the user really wants a binary.
• "CLI utility" → if the utility is really a data entry + report flow, a web form + a results page covers it. If it's truly a pipeline or a filter that fits cat in | tool | out, SDD isn't the right tool.
• "A game" → only viable if it's simple enough to live in a Django template with a bit of JS/htmx. Anything requiring a game engine (Phaser, Unity, canvas physics) is out of scope.

Reframing rules:

• Always try the reframe before declining. Most "mobile" ideas work as mobile-friendly web.

• Confirm the reframe with the user through AskUserQuestion before proceeding — don't silently pivot their idea. Example phrasing: «Как раз под твою задачу удобно начать с веба — открывается с телефона без установки, данные на сервере, потом можно превратить в полноценное мобильное приложение. Подойдёт такой путь?»

• If the user insists on a native-only build (no web MVP acceptable) or the idea is genuinely beyond SDD's scope (a 3D game, a kernel module, a trading bot with hard latency budgets), tell them plainly:

  Такую идею SDD4beginners не закроет — здесь мы собираем веб-приложения на Django. Поищи другой инструмент под этот стек или вернись, если захочешь веб-версию.

  Then exit.

When the idea fits (directly or after a reframe), log one short Russian sentence telling the user what's next. Example:

Окей, собираем веб-приложение на Django + htmx. С телефона откроется нормально, а если потом захочется, чтобы оно ставилось на телефон как обычное приложение, — добавим PWA-обёртку (это когда сайт ставится в один клик и работает даже без интернета).

Then go to Step 4.

Step 4 — propose the MVP

Formulate the minimum version that still solves the core problem. Not "everything we discussed" — "without which it wouldn't work at all". List included features in 2–4 short lines, plus a separate short list of nice-to-haves you parked.

Confirm via AskUserQuestion with three options:

• «Поехали, как есть (Рекомендуется)» → continue to Step 4.5.
• «Урезать ещё» → user says what to drop; revise and re-confirm.
• «Добавить из отложенных» → at least one nice-to-have moves into MVP.

If the user picks «Добавить из отложенных», immediately ask a follow-up AskUserQuestion (multiSelect: true) listing each parked nice-to-have as its own option, so the user picks explicitly what moves into MVP. Don't guess — guessing is how a clean 5-phase plan quietly turns into 8.

Step 4.5 — pre-write summary

Before writing PROJECT.md, summarise the decisions back to the user. Five to seven Russian bullets covering: что строим, для кого, главные сценарии, состав MVP, что отложено, нестандартные риски (если есть). Then one AskUserQuestion:

• «Всё верно, пиши план (Рекомендуется)» → continue to Step 5.
• «Кое-что не так» → user corrects (one or two things); update the summary and re-confirm.

Why this gate exists: by Step 5 you're holding 5–8 turns of context. A short recap catches drift between «что юзер сказал в первом круге» and «что я собираюсь записать» before it lands on disk. Skip it and you'll write a plan that quietly contradicts the early answers, and the user will only notice when they read PROJECT.md cold.

Step 5 — write PROJECT.md and copy tech-stack.md

Two files land in the project directory: PROJECT.md (spec + phase plan + a short stack summary) and tech-stack.md (the full recipe — scaffolding, tests, «do not bring in» list). Downstream skills read tech-stack.md from the project directory for everything recipe-related; PROJECT.md stays focused on what the user is building.

Structure of PROJECT.md — Russian headings, Russian prose inside each section, language-neutral code blocks verbatim. Include only sections that are relevant; skip a section if it doesn't apply (e.g. ## Аккаунты и доступ for a personal single-user tool).

# <Название проекта>

## Что это
Two short sentences. First — what the app does (the user-facing job, not the tech).
Second — who it's for (audience and rough scale). No feature list here; features
belong in «Как это работает».

## Как это работает
Numbered user flows. Concrete scenes in order: «открываешь главную → видишь … →
кликаешь … → попадаешь …». Don't re-state features already named in «Что это»;
show them happening. If a flow branches, branch the numbering — don't summarise.

## Данные
What gets stored, how it's linked (only if relevant).

## Аккаунты и доступ
(only if login matters)

## Интеграции
(only if external APIs/services exist)

## Граничные случаи
What happens when things go wrong.

## Открытые вопросы
Only questions the user actually deferred during the interview («не знаю», «потом
решим», «если успеем», «опционально»). Don't invent questions to look thorough —
if the user didn't deflect on a topic, it's not open. If nothing was deferred, omit
the section entirely.

## Стек
**name:** django-htmx
**summary:** Django 5 + htmx + SQLite + Pico.css в Docker. Страницы собираются на сервере, есть формы, готовая админка, встроенная база данных.

### Будущее расширение (опционально)
Include this subsection only when one of these concrete triggers fired during the
interview — not just to look thorough:
- Public service / many users → Postgres вместо SQLite, регулярные бэкапы, CDN для статики.
- User mentioned phone use → PWA-обёртка (ставится на телефон в один клик, работает офлайн).
- User mentioned desktop preference → Tauri-обёртка (бинарник, который запускается локально).
- User mentioned imports/exports beyond CSV → API или вебхуки.
- User mentioned scale-out / heavy jobs → фоновые задачи (Django-Q / RQ), Redis-кеш.
- User mentioned community / social → комментарии, подписки между профилями.

Two or three friendly Russian bullets max, each pointing a future need at a likely
later phase or technology. Pick triggers that actually came up.

## Фазы

### Фаза 1 — Настройка проекта
**Цель:** <one Russian sentence>
**Усилие:** Low

- [ ] <tasks pulled from the django-htmx Phase 1 recipe, translated to Russian>
- [ ] ...
- [ ] Проверка: <concrete checkpoint — e.g. «http://localhost:5000 открывается и показывает <Название проекта>»>

**Тесты Фазы 1:** <derived from the reference's test guidance>

### Фаза 2 — <Core scenario title>
**Цель:** ...
**Усилие:** Medium

- [ ] ...

**Проверка:** ...
**Тесты Фазы 2:** ...

(and so on)

### Фаза N — Полировка и деплой
**Цель:** приложение доступно по публичному URL.
**Усилие:** Low

- [ ] <deploy tasks — Render.com or Fly.io>
- [ ] Проверка: приложение открывается по публичной ссылке.

**Тесты Фазы N:** все предыдущие чекпоинты ещё зелёные.

All prose inside PROJECT.md is Russian.

Copy tech-stack.md into the project

After writing PROJECT.md, copy the recipe file into the project directory so downstream skills can find it:

cp "$HOME/.claude/skills/sdd-idea/references/tech-stack.md" ./tech-stack.md

If cp isn't convenient, read the source with Read and write the destination with Write — the content is small. Byte-for-byte copy; no edits, no translation. This is the only file /sdd-idea creates besides PROJECT.md and its backups.

Phase construction rules

• Target size: 4–7 phases for a typical idea. Up to 8 when there are many features.
• Phase 1 is fixed by the stack reference. Translate its "Phase 1 recipe" steps into tasks — this is a boot-the-container phase: Docker up, Django migrate, home page live.
• Phase 2 is the core loop. One end-to-end slice through the most important action. Recipe tracker: "add recipe → see in list". Budget tracker: "enter expense → see balance". Everything else comes later.
• Vertical slices, not horizontal layers. Each phase touches the whole stack (model + view + template + tests) for one feature. Do not do "all models first, then all views".
• Each phase ends in a runnable state. No "half a feature now, half next time".
• Last phase is always polish + deploy. Target: Render.com or Fly.io.
• Checkpoints are observable, not "it works". Not "user sees the list" but "open /recipes, click Add, type 'Borscht', submit — should appear on home page".
• Effort: Low / Medium / High. Not hours — vibe coders can't calibrate hours.
• Tests are mandatory. Every phase has a "Тесты Фазы N" section listing what must be covered by unit tests. 100% coverage on changed files (Django core/*.py, excluding migrations/tests/admin/apps) is enforced by /sdd-impl.

Coverage self-check

After writing PROJECT.md, mentally walk each MVP item and each "add later" item: every one must be a task in at least one phase. If something isn't covered, add a task — don't save a plan with a hole.

Phase count self-check

Target: 4–7 phases. 8 is the upper limit reserved for genuinely many features. After the plan is laid out, count the phases. If you're at 8 or above, look hard for merges — two adjacent CRUD-ish phases often collapse into one «add + edit + delete + list», search and stats often share a list page so they share a phase. If after honest looking the count is still ≥8, surface that to the user before Step 6 with one short message:

Получилось фаз — это много, но не критично. Хочешь, попробую слить две — назови, какие выглядят как кандидаты, или предложу варианты сам.

Don't auto-merge — the user might insist on the granularity. But don't pretend an 8-phase plan has the same shape as a 5-phase one either.

Step 6 — offer next steps

Show a summary: phase titles and one-line checkpoints. Then AskUserQuestion with three options:

1. Label «Продолжим интервью» → return to Step 2, focused on what the user wants to deepen ("the data model", "feature X", "edge cases"). After the follow-up, rewrite PROJECT.md (old version goes to PROJECT.v<N>.md).

2. Label «Поменять план» → no re-interview; user says what to change (split a phase, merge two, reprioritize, move something to "later"), you apply it, rewrite PROJECT.md with backup.

3. Label «Поехали, строим!» → the plan is final. Print:

   Готово. План — в PROJECT.md. Запусти /sdd-impl — построю Фазу 1 и подниму приложение в браузере.

   PROJECT.md — это твой план: спецификация проекта + фазы с чекбоксами. Можешь открыть и перечитать в любой момент, по нему я и работаю дальше.

   Когда понадобится:

   • /sdd-impl — собрать следующую фазу (код + тесты + проверка в браузере).
   • /sdd-feature — добавить новую фичу в план (допишу фазы в конец).
   • /sdd-change — поменять что-то в плане: переписать раздел спеки, поправить ещё не построенную фазу, или переделать уже готовое поведение.
   • /sdd-undo — откатить последнюю построенную фазу, если что-то пошло не так.

Options 1 and 2 can be chosen as many times as the user wants — versioning protects previous drafts. Only «Поехали, строим!» hands off control.

What not to do

• Do not touch the host environment — no installs, no version checks, no toolchain probes. Environment readiness lives in /sdd-impl; planning shouldn't care.
• Do not create any file other than PROJECT.md, its PROJECT.v<N>.md backups, and tech-stack.md.
• Do not try to do Phase 1's tasks — that's /sdd-impl's job.
• Do not discuss framework, library, or hosting choices with the user. SDD ships one stack; the user ships the app.
• Do not silently pivot a non-web idea into a web app — confirm the reframe through AskUserQuestion (see Step 3).
• Do not silently extend the stack with extras the reference doesn't list (no Postgres, no Redis, no Tailwind, no Celery in Phase 1) just because the user's docs mentioned them. Production-grade infra belongs in ### Будущее расширение and later phases.
• Do not write «ТЫ ДОЛЖЕН» / "YOU MUST" in the plan — the tone is bad for vibe coders.
• Do not ask all-or-nothing questions — always give options.
• Do not draw ASCII diagrams or flowcharts in PROJECT.md unless the user explicitly asks.

Example trigger prompts

«Хочу сделать приложение для учёта книг, которые читаю. Чтобы можно было ставить оценку, писать короткие заметки, и видеть статистику по месяцам.»

Flow: interview → Phase 3 fit check says "web, easy" → MVP proposal → PROJECT.md with ~5 phases → user runs /sdd-impl.

«Хочу мобильное приложение, чтобы в зале отмечать подходы и веса.»

Flow: interview → fit check reframes as "веб-трекер, открывается с телефона, позже можно обернуть как PWA" → AskUserQuestion confirms the reframe → MVP proposal → PROJECT.md with ~5 phases and a ### Будущее расширение note about mobile wrapping → user runs /sdd-impl.

«Хочу игру 3D про гонки на Unreal Engine.»

Flow: fit check can't reframe — this isn't a web job. Tell the user SDD4beginners doesn't cover it and exit without writing PROJECT.md.