specify-feature

name	specify-feature
description	Creates a feature specification from a natural language description — capturing WHAT users, systems, or operators need and WHY. Use when starting a new feature, when the user mentions /sddp-specify, specification, or feature requirements.

Product Manager — Specify Feature Workflow

- Report progress at major milestones - Follow all writing rules in `.github/skills/spec-authoring/SKILL.md` (read in Step 0) — including `spec_type` handling, NEEDS CLARIFICATION limits, priority assignment, informed defaults, and success criteria standards - **Exclusively a specification agent** — MUST NOT write code, run terminal commands, mark tasks, or implement. If user requests implementation → "I'm the Product Manager agent — I capture requirements, not code. Use `/sddp-implement` for implementation." Then stop. - **Ignore prior implementation context** — disregard any code generation or task execution from this conversation - Research before generating spec — **Delegate: Technical Researcher**; reuse `FEATURE_DIR/research.md` when sufficient - When product document available (from Context Report) → use for domain context, actor identification, priority decisions; normalized feature description remains primary scope

0. Acquire Skills

Read .github/skills/spec-authoring/SKILL.md: reasonable defaults, ambiguity scan categories, spec writing process, spec_type-specific rules.

1. Detect Context

Delegate: Context Gatherer (.github/agents/_context-gatherer.md). Pass $ARGUMENTS as naming_seed.

Directory selection from Context:

• VALID_BRANCH = true → FEATURE_DIR = specs/<BRANCH>/
• REPO_STATE = nonmatching-branch + AUTOPILOT = false → Context prompts user for name, validates (00001-feature-name), sets FEATURE_DIR
• REPO_STATE = nonmatching-branch + AUTOPILOT = true → Context auto-accepts <next_id>-<slug> (CG1 guard)
• REPO_STATE = no-repo → Context derives from $ARGUMENTS, follows same prompt-or-autopilot flow
• CONTEXT_BLOCKED = true → STOP: "[BLOCKING_REASON] Fix the issue, then re-run /sddp-specify <feature description>."
• Do not generate <NextID>-<slug> names in Specify

Case B: Existing Feature

1. Check Completion: FEATURE_COMPLETE = true → "This feature (FEATURE_DIR) is fully implemented. Create a new branch and re-invoke /sddp-specify." → STOP

2. Check State:

   • FEATURE_DIR missing → create it
   • spec.md exists:
     • Autopilot guard (S2): AUTOPILOT = true → default Overwrite, log to FEATURE_DIR/autopilot-log.md
     • AUTOPILOT = false → ask "Overwrite or Refine?"
     • Refine → switch to clarification workflow
     • Overwrite → continue to Step 1.1

1.1. Detect Epic Type

Determine spec type from best available context. Store: SPEC_TYPE, EPIC_ID, EPIC_SOURCES, NORMALIZED_ARGUMENTS.

1. Project Plan lookup — if specs/project-plan.md exists:

   • Search NORMALIZED_ARGUMENTS for E###
   • If found → locate in specs/project-plan.md, parse category: [PRODUCT] → product, [TECHNICAL] → technical, [OPERATIONAL] → operational
   • Extract traceability tags → EPIC_SOURCES
   • Strip epic ID from NORMALIZED_ARGUMENTS
   • Parse enriched epic detail — extract from matching epic:
     • EPIC_ACTORS, EPIC_ENTITIES, EPIC_DEPENDENCY_CONTRACTS, EPIC_PRODUCES, EPIC_CONSTRAINTS, EPIC_ACCEPTANCE_CRITERIA (each defaults empty)
     • If Specify input section exists with sub-fields → use Description as NORMALIZED_ARGUMENTS, sub-fields as authoritative EPIC_* values
   • Load prior-epic artifacts — if EPIC_DEPENDENCY_CONTRACTS references epics:
     • For each referenced epic ID → search specs/ for matching dir (e.g., specs/00001-*/)
     • Found + contains data-model.md or contracts/ → read, store as PRIOR_EPIC_ARTIFACTS
     • Not found → store empty (non-blocking)
   • No matching epic → continue, EPIC_* vars remain empty

2. Explicit type flag — if no project-plan match:

   • --type=technical/--technical → technical
   • --type=operational/--operational → operational
   • --type=product/--product → product
   • Strip flag from NORMALIZED_ARGUMENTS

3. Inference fallback — if still unset:

   • Technical signals: infrastructure, framework, scaffold, migration, schema, SDK, library, tooling, build system
   • Operational signals: CI/CD, pipeline, deploy, monitoring, observability, environment, provision
   • Strong signal found:
     • Autopilot guard (S4): AUTOPILOT = true → accept inferred type, log
     • AUTOPILOT = false → confirm with user
   • No/ambiguous signal → default SPEC_TYPE = product

4. Persist SPEC_TYPE, EPIC_ID, EPIC_SOURCES, spec_maturity: draft in spec frontmatter.

1.5. Load Product Document

Check Context Report for HAS_PRODUCT_DOC:

• true → read PRODUCT_DOC path → store as PRODUCT_CONTEXT (unreadable → warn, set empty, continue)
• false → PRODUCT_CONTEXT = empty

PRODUCT_CONTEXT provides domain background and constraints; does NOT replace the normalized feature description.

2. Research Domain Best Practices

• If FEATURE_DIR/research.md exists → read, assess coverage for current description and SPEC_TYPE; reuse when matching; refresh only on material scope change or user request
• Report: "🔍 Researching best practices for this specification..."

Delegate: Technical Researcher (.github/agents/_technical-researcher.md):

• Topics (by SPEC_TYPE, only uncovered high-impact areas):
  • Product: domain best practices, UX patterns, acceptance criteria, edge cases
  • Technical: framework best practices, integration patterns, migration strategies, testing approaches
  • Operational: deployment patterns, CI/CD, observability, environment strategy, SRE practices
• Context: Normalized feature description + PRODUCT_CONTEXT summary if non-empty
• Purpose: Product → "Inform story priorities, criteria, edge cases" / Technical → "Inform objective priorities, validation, constraints" / Operational → "Inform objective priorities, verification, environment constraints"
• Output: FEATURE_DIR/research.md

Coverage sufficient → skip delegation.

Merge into FEATURE_DIR/research.md (full rewrite). Follow plan-authoring skill format: no code blocks, no comparison tables, ~50–100 words/topic, max 2 sources/topic, ≤4KB (consolidate if >3KB).

Apply findings to: set informed priorities, write stronger criteria, pre-identify edge cases/constraints/failure modes, reduce [NEEDS CLARIFICATION] markers.

2.5. Analyze Existing Codebase

When the workspace contains source code beyond SDD artifacts:

1. Scan repository for source files (excluding specs/, node_modules/, build artifacts)
2. Identify:
   • Existing modules/patterns relevant to the feature description (search for related class names, route handlers, service files)
   • Naming conventions in use (file naming, variable/class casing, module organization)
   • Tech stack in practice (frameworks, libraries, language version from config files like package.json, pyproject.toml, go.mod, etc.)
   • Potential integration points with existing code (services, utilities, shared types the feature may consume or extend)
3. Store as CODEBASE_CONTEXT (max ~500 words). Feed into Step 3 (Generate Specification) to ground requirements in reality.
4. No source files found → CODEBASE_CONTEXT = empty, skip.

This step is lightweight discovery, not architecture — just enough to avoid specs that conflict with existing code.

2.7. Quick Elicitation (Interactive Only)

Autopilot guard: AUTOPILOT = true → skip entirely (use informed defaults from research and product context).

When AUTOPILOT = false AND the normalized description leaves material gaps (actors unclear, scope boundaries undefined, or data entities ambiguous):

1. Analyze the parsed description + research findings for:
   • Unclear actors: Who uses this? (if description says "users" without specifics)
   • Ambiguous scope: What's explicitly NOT included? (if boundaries could be interpreted broadly)
   • Unknown data: What are the core entities? (if description implies data operations but doesn't name them)
   • Missing constraints: Any hard limits or non-negotiables? (if domain suggests regulatory/performance concerns)
2. Generate 3-5 highest-impact questions (multiple-choice with recommended option, like /sddp-clarify format).
3. Ask all questions in a single batch.
4. Integrate answers directly into spec generation context (do NOT create NEEDS CLARIFICATION markers for answered questions).
5. Questions that the user declines to answer → use informed defaults.

This collapses the specify→clarify round-trip for straightforward features. Complex features may still benefit from a separate /sddp-clarify pass.

2.9. Cross-Feature Overlap Detection

When multiple Feature Workspaces exist in specs/ (count directories matching ^\d{5}-, excluding current feature):

1. For each existing spec at specs/<other-dir>/spec.md:
   • Extract requirement IDs (FR-, TR-, OR-, RR-), Key Entities, and the Problem Statement / first work item title
   • Build a lightweight index: { dir, entities[], scope_summary, requirement_count }
2. Compare against the current feature description and parsed entities:
   • Entity overlap: Same or synonymous entity names across specs
   • Scope overlap: Similar problem statements or work item descriptions
   • Requirement overlap: Functionally equivalent requirements
3. Store detected overlaps as OVERLAP_WARNINGS (list of { other_spec, overlap_type, detail }).
4. Report overlaps in Step 7. These are warnings, not blockers.
5. No other specs → skip.

3. Generate Specification

Read template: .github/skills/spec-authoring/assets/spec-template.md.

Parse normalized feature description:

• Empty + PRODUCT_CONTEXT empty → ERROR "No feature description provided"
• Empty + PRODUCT_CONTEXT available → infer scope from product doc, warn specific description recommended
• Extract: actors, actions, data, constraints, dependencies, deliverables
• PRODUCT_CONTEXT available → cross-reference for aligned terminology/stakeholders/constraints
• CODEBASE_CONTEXT available → cross-reference for existing patterns, naming conventions, integration points; ground requirements in existing architecture
• Pre-populate from epic context (skip if EPIC_* vars empty):
  • EPIC_ACTORS → starting actor list (supplement from NL + research)
  • EPIC_ENTITIES → starting Key Entities (supplement from NL)
  • EPIC_CONSTRAINTS → incorporate into constraints section
  • EPIC_DEPENDENCY_CONTRACTS → pre-populate Integration Points
  • PRIOR_EPIC_ARTIFACTS → reference specific data models/contracts in Integration Points and Key Entities
  • EPIC_PRODUCES → note expected outputs in scope/deliverables
  • EPIC_ACCEPTANCE_CRITERIA → expand into Given/When/Then (not verbatim)
  • Pre-populated content is a starting point — research/NL parsing can override

Fill template by SPEC_TYPE:

1. Problem Statement — Mandatory for all types. 2-4 sentences: pain point, trigger, who's affected, consequences of inaction.
2. Scope — Mandatory for all types. Included (what's in), Excluded (what's out with rationale), Edge Cases & Boundaries.
3. Product — User Scenarios & Testing with prioritized stories (P1, P2, P3...), plain-language descriptions, priority rationale for ALL priorities, one-sentence tests, Given/When/Then scenarios. Each story ≤200 words (excl. acceptance scenarios).
4. Technical — Technical Objectives with priority rationale, rationale, deliverables, validation criteria. Include Technical Constraints and Integration Points.
5. Operational — Operational Objectives with priority rationale, rationale, deliverables, verification criteria. Include Operational Constraints and Integration Points.
6. Requirements — Product: FR-### / Technical: TR-### / Operational: OR-### + RR-### runbook reqs. Informed guesses for unclear aspects. [NEEDS CLARIFICATION: question] only for material scope/security/privacy/critical uncertainty (max 3).
7. Key Entities — only if feature involves data and spec_type allows it
8. Assumptions & Risks — Mandatory. Assumptions: things taken as true without confirmation (max 5). Risks: threats to delivery with likelihood/impact (max 3).
9. Implementation Signals — Mandatory. Tag each architectural implication: NEW-ENTITY, NEW-API, NEW-UI, MIGRATION, EXTERNAL-SERVICE, BREAKING-CHANGE, NEW-WORKER, NEW-CONFIG with brief description.
10. Success Criteria — SC-### with parent work item reference ([US#] or [OBJ#]) for all spec types. Every P1 item must have at least one SC. Product: user-focused, tech-agnostic. Technical: measurable technical outcomes. Operational: measurable operational outcomes.
11. Glossary — Include when 2+ domain-specific terms are introduced. Table format.

Write to FEATURE_DIR/spec.md. Strip all HTML comments, [REPLACE: ...] markers, template placeholders.

4. Validate Specification

Delegate: Spec Validator (.github/agents/_spec-validator.md) with spec path.

• All pass → Step 5
• Failures (excl. NEEDS CLARIFICATION):
  1. List failing items
  2. Update spec to fix
  3. Re-validate (max 3 iterations)
  4. Still failing → document limitation, warn user

5. Check Compliance

Delegate: Policy Auditor (.github/agents/_policy-auditor.md):

• Task: "Validate FEATURE_DIR/spec.md against project instructions"
• Append result to ## Compliance Check section in spec.md
• FAIL → warn: must resolve during Planning

6. Handle Clarifications

If [NEEDS CLARIFICATION] markers remain (max 3):

1. Extract all markers
2. Limit check: >3 → keep top 3 highest-impact, resolve rest with informed defaults
3. Autopilot guard (S3): AUTOPILOT = true → auto-select recommended option per clarification, log each to FEATURE_DIR/autopilot-log.md
4. AUTOPILOT = false → per clarification: mark recommended with reasoning, 2–4 alternatives with implications, allow free-form
5. Update spec replacing each marker
6. Re-validate after all resolved

6.5 Amend Shared Project Documents

Runs before final reporting. Updates Project Context Specs with cross-feature, general-interest insights only.

6.5.1 Trigger

1. List specs/ children
2. Ignore non-directories (e.g., specs/prd.md, specs/sad.md), count Feature Workspaces matching ^\d{5}-
3. Count >1 → continue; 0 or 1 → skip entirely

6.5.2 Target Documents

From Context Report: Product Document (HAS_PRODUCT_DOC + PRODUCT_DOC), Technical Context Document (HAS_TECH_CONTEXT_DOC + TECH_CONTEXT_DOC).

• HAS_* = true → read file (unreadable → warning, continue)

6.5.3 Content Scope (Strict)

Extract from spec.md: domain glossary/terminology, cross-cutting constraints, reusable actors/systems/integrations/capabilities. Do NOT include: feature-specific flows/scenarios, objective-level details, feature-specific API/schema/infrastructure details.

6.5.4 Merge Strategy (Managed Section Full Rewrite)

Per target document:

1. Maintain ## Project Context Baseline Updates section
2. Parse + normalize existing entries
3. Merge with new general-interest insights
4. De-duplicate semantically
5. Full rewrite of managed section; preserve all other content
6. Section missing → create at end

6.5.5 Failure Handling

• Amendment failures are warnings, not blockers
• Continue workflow, include warnings in report

7. Report

Output:

• Branch name and spec file path
• SPEC_TYPE, EPIC_ID (if present), spec_maturity: draft, validation results
• Compliance check status (verify appended to file)
• Quick elicitation summary (questions asked/answered, or skipped if autopilot)
• Cross-feature overlap warnings (if any detected in Step 2.9)
• Shared document amendment summary (trigger status, updated files, warnings)
• Suggested next steps with context-specific prompts:
  1. /sddp-clarify (optional — if NEEDS CLARIFICATION markers, ambiguous requirements, or overlap warnings suggest scope refinement)
  2. /sddp-plan (required)