dasha-ws/ai-dev-framework/product-spec

product-spec

Purpose

/product-spec creates, or substantially updates, the full Product Specification of a target project: .claude/product/product-spec.md, the canonical product-level intended requirements. It turns the product idea, the user's answers and whatever the project already says into agreed requirements: what problem the product solves, for whom and why, what it must do, what is in and out of scope, which product rules and constraints are agreed, and how to tell at product level that they are met. It answers what and why, never how it is built: no architecture and no technical design.

Two documents, two jobs. product-spec.md is the full specification. .claude/skills/project-context/context/product.md is a short durable digest of it for Claude Code, not a second requirements document. After substantive authoring, /review-spec is mandatory (step 8). What follows is governed by "Next skills".

When to use

• A new project after /init-project, where product-spec.md is still a not-started stub.
• An existing project that has no Product Specification, or one that is not complete enough.
• An existing product whose requirements the user wants to formalise for the first time.
• A substantial change to the overall product idea, when the user explicitly asks to update the Product Specification.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing. Stop, say what is missing and suggest /init-project (step 1).
• A Product Specification already exists and is current enough for the task. Its existence is not a reason to run this skill again.
• The user wants one new feature of an existing product described: /new-feature-spec.
• The user wants architecture or a technical implementation plan: /architecture and /tech-spec.
• The user wants a small bug fixed, code changed, code reviewed, a finished implementation tested, or documentation updated after implementation.

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The user: the product idea and the answers to the product interview.
• The project itself (existing projects): README, product documentation, existing specs, and facts about what the product does today.
• The framework structure in the target project, created by /init-project: .claude/product/product-spec.md, .claude/skills/project-context/SKILL.md and .claude/skills/project-context/context/product.md. All three are required.
• The installed Product Specification template. product-spec.md was created from it.

Files to read

Read before writing anything. All reads are read-only. Always: the root CLAUDE.md, .claude/skills/project-context/SKILL.md (the router), .claude/skills/project-context/context/product.md, .claude/product/product-spec.md and the installed template. For existing projects, only when it actually helps: README* and product documentation, relevant existing specs (.claude/work/, docs/), other context files that carry constraints bearing directly on product requirements, and code only as far as needed to check existing observable behaviour.

Follow the router: do not load the whole project context by default. This is not a technical audit. Never read real .env files, keys or credentials.

Execution steps

1. Confirm the target, the prerequisites and the template

Verify that the working directory is a target project, not the framework repo, and that the three required files from "Inputs" exist. If any is missing: stop, say what is missing and suggest /init-project first. Do not create the structure yourself and do not rebuild it from memory.

The installed Product Specification template is required, and its structure is the structure of product-spec.md. It lives at %USERPROFILE%\.claude\ai-dev-framework\templates\product-spec.md, so do not look for it by other means. If it is unavailable, missing or empty: stop, say that the framework installation or template needs fixing, and do not recreate it from memory, invent your own structure or continue. If product-spec.md exists but is empty, damaged, or so far from the template that continuing safely is impossible: stop and describe the problem. Fixing a broken framework installation is not this skill's job.

2. Read the current state, classify it and take the baseline

Read the files listed above and classify product-spec.md: a not-started stub (the template structure with nothing confirmed in it) or a substantive spec (real, agreed content). Note what product.md already says: confirmed statements or TODO(product-spec) gaps.

The sources keep their roles. product-spec.md holds the agreed intended product behaviour, scope and product-level requirements. Code and current behaviour are evidence of what the product does today: they do not override the spec, and existing behaviour, legacy quirks and bugs are not requirements just because they exist. For an existing project keep three things apart: the intended behaviour, the documented requirements and the current implementation. product.md reflects the spec: if the two disagree after a change, the spec wins and product.md is synced. Specs in .claude/work/ may refine one change and must not quietly rewrite the Product Specification. There is one product truth and no competing versions. No source ledger and no source: tag next to every fact.

Before the first write, in a git repository, take a read-only baseline with git status --short -uall, git diff and git diff --cached, so that staged changes and individual untracked files are visible. Do not require a clean working tree, and leave any changes the user already has untouched: they are not a violation of this skill's boundaries. The baseline exists so that step 7 can tell your changes from the earlier ones. Never stage, reset, checkout, stash, commit or run any other command that changes git state. If the project is not a git repository, do not invent a filesystem snapshot, hashes or any other baseline mechanism.

3. Establish what is changing and resolve conflicts

If the user's request already makes clear that they want to update the overall Product Specification, do not ask again. Ask only when it is unclear whether the change concerns the overall product intent or just one feature. If it is one feature, point to /new-feature-spec and stop. If it is an update of the Product Specification, work out which parts change and leave the rest alone.

If the README, the Product Specification, the project context, other documents or the observed behaviour contradict each other on product requirements: do not pick the convenient version and do not fix it silently. Show the user what exactly diverges, explain the variants in a few lines, and wait for the decision before recording anything. A contradiction in substance is resolved by the user, not by this skill.

4. Run the product interview

A conversation, not a form. Study what is known first, then ask.

• Do not ask what is reliably known from the project or was already confirmed by the user, and never repeat a question the user has answered.
• Ask only what the Product Specification really needs, in small logical blocks, never the whole survey in one message.
• If an answer opens a real new uncertainty, follow up.
• The user owns product decisions. If they have not decided something, do not decide for them. If it is unknown and they cannot or do not want to settle it now, leave it as an explicit open question: a plausible-sounding guess is worse than an honest gap.
• Tell three things apart: a confirmed fact, a decision the user has made and an unresolved question. Do not invent users, needs, goals, features, constraints, business rules or metrics.
• Do not drift into technical design.

Cover the aspects that actually apply: the problem or need, target users or actors, the product goal, key user scenarios, functional scope and what is explicitly out of scope, important business rules, product-level acceptance criteria, known constraints, external dependencies that affect product behaviour, terminology where the requirements are ambiguous without it, and open questions. The concrete structure is whatever the installed template says.

User data and privacy (conditional). Once the interview shows that the product receives, stores, transmits or otherwise processes data about its users (accounts, contact details, messenger or device identifiers, user content, usage data and the like), raise the privacy and data-processing questions yourself. Do not wait for the user to mention them, and do not skip them because they were not asked about. If it is unclear whether the product handles such data, ask that one question first. A product that does not process user data gets none of this: do not run the block, and do not ask "just in case".

Ask in small blocks, only what is not yet known, and cover:

• which user data is processed, why, and which of it the product really needs;
• whether a Privacy Policy is needed and how the user reaches it;
• whether explicit consent is required, what happens on refusal, and whether the product can be used without consent;
• whether the user can request access, correction or deletion of their data, and what happens to the data and the user's account after deletion;
• known retention requirements;
• the known lawful basis for processing, if any;
• known data-subject rights requirements, data residency or localization requirements, and registration, notification or similar operator obligations;
• known jurisdiction or compliance constraints;
• which of these must be closed before public launch.

This skill is not a lawyer. It does not decide which law applies, which basis is valid, whether consent, registration or a policy is legally required, or what a compliant product looks like. Keep the three kinds apart. A requirement or fact the user states as known (for example a jurisdiction, a data-localization requirement or a retention period) is a confirmed fact or external constraint: record it as such, as stated, and do not present it as a product decision. A product choice the user makes (for example what is collected, or how consent refusal behaves) is a decision: record it as a decision. What is unknown or not yet decided, record as an open question and do not fill it with a plausible answer or a legal conclusion. Where it is already known that a privacy or compliance requirement must be satisfied before public launch, record it under Constraints and dependencies marked [before public launch], and record a related unknown part as an open question marked [before public launch] too. If only the uncertainty is known to need resolving before public launch and the requirement itself is not established, record just the marked open question, never an invented constraint or a legal conclusion. The product-level decisions (what is collected and why, consent and refusal behaviour, access, correction and deletion behaviour, the Privacy Policy being available to users) go into the template's existing sections as business rules, acceptance criteria and constraints. How they are built, stored or secured is not decided here.