Smithery is now a part of Arcade.dev! Read more in our announcement here
Provides standard operating procedures for the /specify phase including feature classification (HAS_UI, IS_IMPROVEMENT, HAS_METRICS, HAS_DEPLOYMENT_IMPACT), research depth determination,...
This skill orchestrates the /specify phase, producing spec.md with measurable success criteria, classification flags for downstream workflows, and maximum 3 clarifications using informed guess heuristics for technical defaults.
Core responsibilities:
Inputs: User's feature description, existing roadmap entries, project docs (if exists), codebase context Outputs: specs/NNN-slug/spec.md, NOTES.md, state.yaml, updated roadmap (if FROM_ROADMAP=true) Expected duration: 10-15 minutes
Key principle: Use informed guesses for non-critical decisions, document assumptions, limit clarifications to ≤3.
feature/NNN-slug).spec-flow/templates/See reference.md for complete decision trees and heuristics.
Extract feature description and generate clean slug.
Slug Generation Rules:
# Remove filler words and normalize
echo "$ARGUMENTS" |
sed 's/\bwe want to\b//gi; s/\bI want to\b//gi' |
sed 's/\badd\b//gi; s/\bcreate\b//gi; s/\bimplement\b//gi' |
sed 's/\bget our\b//gi; s/\bto a\b//gi; s/\bwith\b//gi' |
tr '[:upper:]' '[:lower:]' |
sed 's/[^a-z0-9-]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' |
cut -c1-50
Example:
student-progress-dashboard ✅specs/042-student-progress-dashboard/Quality Check: Slug is concise, descriptive, no filler words, matches roadmap format.
See reference.md § Slug Generation Rules for detailed normalization logic.
Search roadmap for existing entry to reuse context.
Detection Logic:
SLUG="student-progress-dashboard"
if grep -qi "^### ${SLUG}" .spec-flow/memory/roadmap.md; then
FROM_ROADMAP=true
# Extract requirements, area, role, impact/effort scores
# Move entry from "Backlog"/"Next" to "In Progress"
# Add branch and spec links
fi
Benefits:
Quality Check: If roadmap match found, extracted requirements appear in spec.md.
See reference.md § Roadmap Integration for fuzzy matching logic.
Extract architecture constraints from docs/project/ to prevent hallucination.
Detection:
if [ -d "docs/project" ]; then
HAS_PROJECT_DOCS=true
# Extract tech stack, API patterns, entities
else
echo "ℹ️ No project documentation (run /init-project recommended)"
HAS_PROJECT_DOCS=false
fi
Extraction:
# Extract constraints from project docs
FRONTEND=$(grep -A 1 "| Frontend" docs/project/tech-stack.md | tail -1)
DATABASE=$(grep -A 1 "| Database" docs/project/tech-stack.md | tail -1)
API_STYLE=$(grep -A 1 "## API Style" docs/project/api-strategy.md | tail -1)
ENTITIES=$(grep -oP '[A-Z_]+(?= \{)' docs/project/data-architecture.md)
Document in NOTES.md:
## Project Documentation Context
**Tech Stack Constraints** (from tech-stack.md):
- Frontend: Next.js 14
- Database: PostgreSQL
**Spec Requirements**:
- ✅ MUST use documented tech stack
- ✅ MUST follow API patterns from api-strategy.md
- ✅ MUST check for duplicate entities before proposing new ones
- ❌ MUST NOT hallucinate MongoDB if PostgreSQL is documented
Quality Check: NOTES.md includes project context section with constraints.
Skip if: No docs/project/ directory exists (warn user but don't block).
Set classification flags using decision tree.
Classification Logic:
HAS_UI (user-facing screens/components):
UI keywords: screen, page, dashboard, form, modal, component, frontend, interface
→ BUT NOT backend-only: API, endpoint, service, worker, cron, job, migration, health check
→ HAS_UI = true
Example: "Add student dashboard" → HAS_UI = true ✅
Example: "Add background worker" → HAS_UI = false ✅ (backend-only)
IS_IMPROVEMENT (optimization with measurable baseline):
Improvement keywords: improve, optimize, enhance, speed up, reduce time
AND baseline: existing, current, slow, faster, better
→ IS_IMPROVEMENT = true
Example: "Improve search performance from 3.2s to <500ms" → IS_IMPROVEMENT = true ✅
Example: "Make search faster" → IS_IMPROVEMENT = false ❌ (no baseline)
HAS_METRICS (user behavior tracking):
Metrics keywords: track user, measure user, engagement, retention, conversion, analytics, A/B test
→ HAS_METRICS = true
Example: "Track dashboard engagement" → HAS_METRICS = true ✅
HAS_DEPLOYMENT_IMPACT (env vars, migrations, breaking changes):
Deployment keywords: migration, schema change, env variable, breaking change, docker, platform change
→ HAS_DEPLOYMENT_IMPACT = true
Example: "OAuth authentication (needs env vars)" → HAS_DEPLOYMENT_IMPACT = true ✅
Quality Check: Classification matches feature intent. No UI artifacts for backend workers.
See reference.md § Classification Decision Tree for complete logic.
Select research depth based on complexity (FLAG_COUNT).
Research Depth Guidelines:
| FLAG_COUNT | Depth | Tools | Use Cases |
|---|---|---|---|
| 0 | Minimal | 1-2 | Simple backend endpoint, config change |
| 1 | Standard | 3-5 | Single-aspect feature (UI-only or backend-only) |
| ≥2 | Full | 5-8 | Complex multi-aspect feature |
Minimal Research (FLAG_COUNT = 0):
Standard Research (FLAG_COUNT = 1): 1-2. Minimal research 3. UI inventory scan (if HAS_UI=true) 4. Performance budgets check 5. Similar spec search
Full Research (FLAG_COUNT ≥ 2): 1-5. Standard research 6. Design inspirations (if HAS_UI=true) 7. Web search for novel patterns 8. Integration points analysis
Quality Check: Research depth matches complexity. Don't over-research simple features.
See reference.md § Research Depth Guidelines for tool selection logic.
Use defaults for non-critical technical decisions.
Use Informed Guesses For (do NOT clarify):
Document Assumptions in spec.md:
## Performance Targets (Assumed)
- API endpoints: <500ms (95th percentile)
- Frontend FCP: <1.5s, TTI: <3.0s
- Lighthouse: Performance ≥85, Accessibility ≥95
_Assumption: Standard web application performance expectations applied._
Do NOT Use Informed Guesses For:
Quality Check: No clarifications for decisions with industry-standard defaults.
See reference.md § Informed Guess Heuristics for complete defaults catalog.
Identify ambiguities that cannot be reasonably assumed.
Clarification Prioritization Matrix:
| Category | Priority | Ask? | Example |
|---|---|---|---|
| Scope boundary | Critical | ✅ Always | "Does this include admin features or only user features?" |
| Security/Privacy | Critical | ✅ Always | "Should PII be encrypted at rest?" |
| Breaking changes | Critical | ✅ Always | "Is it okay to change the API response format?" |
| User experience | High | ✅ If ambiguous | "Should this be a modal or new page?" |
| Performance SLA | Medium | ❌ Use defaults | "What's the target response time?" → Assume <500ms |
| Technical stack | Medium | ❌ Defer to plan | "Which database?" → Planning-phase decision |
| Error messages | Low | ❌ Use standard | "What error message?" → Standard pattern |
| Rate limits | Low | ❌ Use defaults | "How many requests?" → 100/min default |
Limit: Maximum 3 clarifications total
Process:
Good Clarifications:
[NEEDS CLARIFICATION: Should dashboard show all students or only assigned classes?]
[NEEDS CLARIFICATION: Should parents have access to this dashboard?]
Bad Clarifications (have defaults):
❌ [NEEDS CLARIFICATION: What's the target response time?] → Use 500ms default
❌ [NEEDS CLARIFICATION: Which database to use?] → Planning-phase decision
❌ [NEEDS CLARIFICATION: What error message format?] → Use standard pattern
Quality Check: ≤3 clarifications total, all are scope/security/UX critical.
See reference.md § Clarification Prioritization Matrix for complete ranking system.
Define measurable, quantifiable, user-facing outcomes.
Good Criteria Format:
## Success Criteria
- User can complete registration in <3 minutes (measured via PostHog funnel)
- API response time <500ms for 95th percentile (measured via Datadog APM)
- Lighthouse accessibility score ≥95 (measured via CI Lighthouse check)
- 95% of user searches return results in <1 second
Criteria Requirements:
Bad Criteria to Avoid:
❌ System works correctly (not measurable)
❌ API is fast (not quantifiable)
❌ UI looks good (subjective)
❌ React components render efficiently (technology-specific, not outcome-focused)
Quality Check: Every criterion is measurable, quantifiable, and outcome-focused.
Create specification artifacts and commit to git.
Artifacts:
specs/NNN-slug/spec.md - Structured specification with classification flags, requirements, assumptions, clarifications (≤3), success criteriaspecs/NNN-slug/NOTES.md - Implementation decisions and project contextspecs/NNN-slug/visuals/README.md - Visual artifacts directory (if HAS_UI=true)specs/NNN-slug/state.yaml - Phase state tracking (currentPhase: specification, status: completed)Validation Checks:
Commit Message:
git add specs/NNN-slug/
git commit -m "feat: add spec for <feature-name>
Generated specification with classification:
- HAS_UI: <true/false>
- IS_IMPROVEMENT: <true/false>
- HAS_METRICS: <true/false>
- HAS_DEPLOYMENT_IMPACT: <true/false>
Clarifications: N
Research depth: <minimal/standard/full>"
Quality Check: All artifacts created, spec committed, roadmap updated, state.yaml initialized.
During phase:
Post-phase validation:
What makes a good spec:
What makes a bad spec:
5 clarifications (over-clarifying technical defaults)
Scenario:
Spec with 7 clarifications (limit: 3):
- [NEEDS CLARIFICATION: What format? CSV or JSON?] → Use JSON default
- [NEEDS CLARIFICATION: Rate limiting strategy?] → Use 100/min default
- [NEEDS CLARIFICATION: Maximum file size?] → Use 50MB default
Prevention:
If encountered: Reduce to 3 most critical, convert others to documented assumptions.
Scenario:
Feature: "Add background worker to process uploads"
Classified: HAS_UI=true (WRONG - no user-facing UI)
Result: Generated screens.yaml for backend-only feature
Root cause: Keyword "process" triggered false positive without checking for backend-only keywords
Prevention:
Scenario:
User input: "We want to add Student Progress Dashboard"
Generated slug: "add-student-progress-dashboard" (BAD - includes "add")
Roadmap entry: "### student-progress-dashboard" (slug without "add")
Result: No match found, created fresh spec instead of reusing roadmap context
Prevention:
Scenario:
# 15 research tools for simple backend endpoint (WRONG)
Glob *.py, Glob *.ts, Glob *.tsx, Grep "database", Grep "model"...
Prevention:
Correct approach:
# 2 research tools for simple backend endpoint (CORRECT)
grep "similar endpoint" specs/*/spec.md
grep "BaseModel" api/app/models/*.py
Bad examples:
❌ System works correctly (not measurable)
❌ API is fast (not quantifiable)
❌ UI looks good (subjective)
Good examples:
✅ User can complete registration in <3 minutes (measured via PostHog funnel)
✅ API response time <500ms for 95th percentile (measured via Datadog APM)
✅ Lighthouse accessibility score ≥95 (measured via CI Lighthouse check)
Prevention: Every criterion must answer: "How do we measure this objectively?"
Bad examples:
❌ React components render efficiently
❌ Redis cache hit rate >80%
❌ PostgreSQL queries use proper indexes
Good examples (outcome-focused):
✅ Page load time <1.5s (First Contentful Paint)
✅ 95% of user searches return results in <1 second
✅ Database queries complete in <100ms average
Prevention: Focus on user-facing outcomes, not implementation mechanisms.
When NOT to use:
Approach:
Example:
## Performance Targets (Assumed)
- API response time: <500ms (95th percentile)
- Frontend FCP: <1.5s
- Database queries: <100ms
**Assumptions**:
- Standard web app performance expectations applied
- If requirements differ, specify in "Performance Requirements" section
Result: Reduces clarifications from 5-7 to 0-2, saves ~10 minutes
Approach:
Result: Saves ~10 minutes, requirements already vetted, automatic status tracking
Process:
Result: 90%+ classification accuracy, correct artifacts generated
currentPhase: specification and status: completedReady to proceed when:
/clarify/planIssue: Classification seems wrong Solution: Re-check decision tree, verify no backend-only keywords for HAS_UI=true
Issue: Roadmap entry exists but wasn't matched Solution: Check slug normalization, offer fuzzy matches, update roadmap slug format
Issue: Success criteria are vague Solution: Add quantifiable metrics and measurement methods, focus on user-facing outcomes
Issue: Research depth excessive for simple feature Solution: Follow FLAG_COUNT guidelines (0→minimal, 1→standard, ≥2→full)
Issue: Project context missing/incomplete Solution: Run /init-project to generate docs/project/, or manually create tech-stack.md and api-strategy.md
Classification & Defaults: reference.md
Real-World Examples: examples.md
Execution Details: reference.md § Research Depth Guidelines, Common Mistakes to Avoid
Next phase after /specify:
/clarify (reduces ambiguity via targeted questions)/plan (generates design artifacts from spec)