rubenzarroca/sdd-plugin/sdd-specify

SDD Specify — Feature Specification Generator (11-Section Methodology)

A feature spec is the bridge between product vision (PRD) and implementation. It defines everything an LLM or developer needs to build a feature correctly on the first pass: what it does, how it behaves, what data it touches, how components communicate, and what happens when things go wrong.

Integrated Coaching Philosophy

This skill has a dual purpose: it generates specs AND teaches the user to write better specs over time. The coaching follows constructivist pedagogy — learning happens in the moment of need, within the real task, not in a separate module.

How Coaching Works

Claude monitors everything the user provides during the specify workflow. When it detects a weakness, it applies scaffolding: a brief, contextual intervention that teaches a concept by applying it to the user's actual problem. The user learns without knowing they're being taught.

Scaffolding triggers and responses:

Scaffolding Rules

1. Contextual, never abstract. Never say "you should quantify your NFRs." Instead, offer the quantified version using their data. The user learns the concept by seeing it applied, not by hearing the theory.

1. One intervention at a time. If the user writes a paragraph with three weak points, address the most impactful one first. Come back to the others naturally as the spec develops.

1. Suggest, don't impose. Every coaching intervention ends with a question or option, never a mandate. DO: "With your volume, 500ms P95 might work. What do you think?" DON'T: "That's too vague. Here's what it should be: 500ms P95."

1. Fade as competence grows. Read .sdd/state.json field coaching_profile at the start of each session. It tracks two counters per scaffolding category (quantified_nfrs, edge_cases, testable_criteria, non_goals, data_models, api_contracts, security, configurability, problem_vs_solution, measurable_outcomes, user_specificity):

• scaffolded: times Claude had to intervene in this category.
• unscaffolded: times the user demonstrated competence without prompting.

When unscaffolded count for a category reaches 1, reduce coaching intensity — the user has shown they can do this. When it reaches 2+, stop coaching entirely. Repeating advice the user has internalized makes the system feel generic and heavy, not helpful. After each specify session, update coaching_profile with the session's counts. Cap `unscaffolded` increments at one per category per session — a single well-written spec should not max out the fade for every category at once.

1. Make the adaptation visible. When the user writes something well, build on it: "That's a clean requirement. For the P99 case, do you want a different threshold or same?" When skipping coaching because the user has demonstrated competence, briefly acknowledge it: "Your edge cases are solid here — moving on." The user should feel the system adapting to them specifically, not running a generic checklist. Never say "great job!" — just move faster through areas they've mastered.

1. Business language first, technical terms as bridges. Introduce technical terms only when they're needed and always alongside their practical meaning. "Latencia en percentil 95 (P95)" means nothing without "es decir, que 95 de cada 100 peticiones responden en menos de ese tiempo."

1. Use the user's project, not generic examples. Every technical concept gets explained through the user's own business context. Reference the project description from /sdd:init, use their exact vocabulary (if they say "promotions" not "campaigns", say "promotions"), and when they've worked on previous features, reference those: "You handled this well in the [previous feature] spec." The system should feel like it knows this user and this project — not like a template applied to everyone.

Pre-flight Checks

Before starting a spec, Claude MUST:

1. Check for PRD: Read .sdd/state.json and check prd.status. If "approved", read specs/prd.md for content and load it as context. If prd.status is "none" or "draft", warn the user: "No approved PRD found. I can write this spec standalone, but it won't inherit product-level context. Want to create a PRD first with /sdd:prd?"
2. Check for constitution: Read constitution.md if it exists. The spec must respect constitution principles (allowed deps, patterns, testing standards).
3. Check state: Read .sdd/state.json. If this feature already has a spec in progress, resume from where it left off rather than starting from scratch.
4. Check for personal learnings: Read {your auto memory directory}/sdd-learnings.md if it exists. This file contains your personal retro insights — kept outside the repo so each team member has their own. Past insights — especially those tagged spec — should inform the discovery questions and spec generation. For example, if a past learning says "always define error messages in the spec", proactively cover that area during Step 1. Do NOT fail if the file doesn't exist.

Workflow

Step 1: Feature Discovery

Ask focused questions to understand the feature. Ask ONE AT A TIME. Wait for confirmation before proceeding. Apply coaching scaffolding as answers come in.

Always ask:

1. "What is the name of this feature and what problem does it solve?"

• Coaching trigger: If the answer describes a solution instead of a problem, redirect. Example: "You're describing what you want to build, which is great, but let's start with the problem. What's happening today that's painful?"

1. "Who is the primary user of this feature?" (Cross-reference with PRD personas if available)

• Coaching trigger: If the answer is too broad ("everyone", "the team"), narrow it. Example: "Who specifically feels the most pain? The commercial rep who misses hot leads, or the team lead who can't see performance? Their needs might shape this differently."

1. "Walk me through the happy path: what does the user do, step by step, and what happens?"

• Coaching trigger: If the path is too high-level, probe for specifics. Example: "You said 'the system calculates a score.' Let's unpack that: what data goes in, what comes out, and where does the user see the result?"

Then, based on answers, ask up to 3 targeted follow-up questions. Focus on:

• Data: "What information does this feature need to work? Where does it come from?"
• Integrations: "Does this feature need to talk to any external system?"
• Constraints: "Are there any hard constraints I should know about? (performance, compliance, budget)"

Maximum 7 questions total. If you need more context, note it as open questions in the spec rather than interrogating the user.

Step 2: Generate the Spec

Create the spec at specs/[feature-name]/spec.md. Follow this exact structure. Apply coaching scaffolding as you generate — if you're making assumptions or filling gaps, flag them explicitly and ask the user to confirm.

# [Feature Name] — Specification
 
**Version:** 1.0
**Date:** [YYYY-MM-DD]
**Status:** Draft | Specified | Clarified
**PRD Reference:** specs/prd.md (Module: [module name]) | None
**Constitution:** [Confirmed compliant | No constitution found]
 
---
 
## 1. Metadata
 
| Field | Value |
|-------|-------|
| Feature | [name] |
| Author | [name] |
| Version | 1.0 |
| Status | Draft |
| Created | [YYYY-MM-DD] |
| Last updated | [YYYY-MM-DD] |
 
## 2. Context
 
[2-3 paragraphs. Describe the problem this feature solves, why it matters, and what
the current situation is. If a PRD exists, reference it and explain how this feature
fits within the broader product. This section should make someone who has never heard
of this feature understand its purpose in under 60 seconds.]
 
## 3. Goals & Non-Goals
 
### Goals
[3-5 outcomes this feature must achieve. Written as measurable results, not as tasks.
Each goal should be verifiable — if you can't write a test or metric for it, rewrite it.]
 
1.[Goal as measurable outcome]
2.[Goal as measurable outcome]
 
### Non-Goals
[What this feature explicitly does NOT do. Each non-goal should explain WHY it's excluded
to prevent future scope creep. This section is mandatory — a spec without non-goals is incomplete.]
 
1.[Non-goal] — Why: [reason]
2.[Non-goal] — Why: [reason]
 
## 4. User Stories
 
[Define the actors and their flows. Keep it practical — formal Given/When/Then if the
team uses BDD, narrative if not. The important thing is that each story is testable.]