Specify Feature

Read .github/skills/spec-authoring/SKILL.md to understand:

• Reasonable defaults to avoid asking about
• Ambiguity scan categories
• Spec writing process and prioritization rules

1. Detect Context

Delegate: Context Gatherer (see .github/agents/_context-gatherer.md for methodology).

Directory selection comes from Context:

• If VALID_BRANCH = true, Context sets FEATURE_DIR = specs/<BRANCH>/.
• If VALID_BRANCH = false, Context prompts the user for a feature directory name, validates it (00001-feature-name for new folders), and sets FEATURE_DIR = specs/<ProvidedName>/.
• Do not generate <NextID>-<slug> names in Specify.

Case B: Existing Feature

1. Check Completion:

   • If the Context Report shows FEATURE_COMPLETE = true:
     • This feature has been fully implemented. Do NOT offer Overwrite or Refine.
   • Tell the user: "This feature (FEATURE_DIR) is fully implemented. To start a new feature, create a new branch (git checkout -b #####-feature-name) and re-invoke /sddp-specify with your feature description."
   • STOP — do not proceed with specification. Yield control to the user.

2. Check State:

• If FEATURE_DIR does not exist, create it.
• If spec.md already exists in FEATURE_DIR:
  • Ask the user: "Spec exists. Do you want to Overwrite it or Refine it?"
  • If Refine: Switch to the clarification/refinement workflow (or exit and tell user to use Refine agent).
  • If Overwrite: Continue to Step 1.5.

1.5. Load Product Document

Check the Context Report for HAS_PRODUCT_DOC.

• If HAS_PRODUCT_DOC == true:
  1. Read the file at the PRODUCT_DOC path.
  2. If the file is readable, store its content as PRODUCT_CONTEXT.
  3. If the file cannot be read (moved, deleted, permission error), warn the user and set PRODUCT_CONTEXT to empty. Continue without it.
• If HAS_PRODUCT_DOC == false: set PRODUCT_CONTEXT to empty.

PRODUCT_CONTEXT provides domain background, product vision, target audience, and broader constraints that enrich the specification. It does NOT replace $ARGUMENTS — the user's feature description remains the primary scope definition.

2. Research Domain Best Practices

If FEATURE_DIR/research.md exists:

• Read it first and assess coverage for the current feature description.
• Reuse existing findings when they still match the feature scope.
• Refresh research only if the scope changed materially, coverage is missing, or the user asks for fresh research.

Before delegating, report to the user: "🔍 Researching best practices for this feature — this may take 15–30 seconds."

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

• Topics: Based on $ARGUMENTS, include only the highest-impact domain areas not already covered (e.g., authentication, payments, notifications, UX patterns, acceptance criteria, edge cases).
• Context: The feature description from $ARGUMENTS. If PRODUCT_CONTEXT is non-empty, append a summary of the product document's key points (product vision, domain, target audience, constraints) to give the researcher broader context.
• Purpose: "Inform user story priorities, acceptance criteria, and edge case identification."
• Output: Save findings to FEATURE_DIR/research.md

If research is reused and no refresh is needed, skip the delegation and continue.

Merge research findings into FEATURE_DIR/research.md and rewrite the full file (do not append blindly). Follow the research.md format defined in the plan-authoring skill — no code blocks, no reference tool comparison tables, decision-level findings only (~50–100 words per topic), max 2 sources per topic, and keep the file at or below 4KB (consolidate first if existing content is above 3KB).

Apply the research findings to:

• Set informed user story priorities
• Write stronger acceptance criteria based on real-world patterns
• Pre-identify edge cases and failure modes
• Reduce [NEEDS CLARIFICATION] markers by making evidence-based decisions

3. Generate Specification

Read the spec template from .github/skills/spec-authoring/assets/spec-template.md.

Parse the user's feature description from $ARGUMENTS:

• If empty and PRODUCT_CONTEXT is also empty: ERROR "No feature description provided"
• If empty but PRODUCT_CONTEXT is available: use the product document to infer the feature scope, but warn the user that a specific $ARGUMENTS description is recommended for focused specs
• Extract key concepts: actors, actions, data, constraints
• When PRODUCT_CONTEXT is available, cross-reference it to:
  • Identify additional actors or stakeholders mentioned in the product document
  • Align terminology with the product document's domain language
  • Inform priority decisions based on the product's stated goals and target audience
  • Surface constraints or requirements from the product document that apply to this feature

Fill the template with concrete details:

1. User Scenarios & Testing: Prioritized user stories (P1, P2, P3...) with:

   • Plain language description
   • Priority rationale (only for P2+ where ranking is non-obvious)
   • Independent test (one sentence)
   • Given/When/Then acceptance scenarios
   • Keep each story under 200 words excluding acceptance scenarios

2. Requirements: Testable functional requirements (FR-001, FR-002...)

   • Make informed guesses for unclear aspects using industry standards

• Use [NEEDS CLARIFICATION: specific question] when uncertainty could materially affect scope, security/privacy, or core UX behavior (max 3)
• Use informed defaults only for low-impact details with clear industry-standard expectations

3. Key Entities: If the feature involves data — entity names, attributes, relationships (no implementation)

4. Success Criteria: Measurable, technology-agnostic outcomes (SC-001, SC-002...)

   • ✅ "Users can complete checkout in under 3 minutes"
   • ❌ "API response time is under 200ms"

5. Edge Cases: Boundary conditions and error scenarios

Write the spec to FEATURE_DIR/spec.md. The final file must not contain any HTML comments (<!-- -->), [REPLACE: ...] markers, or template placeholder lines — strip all instructional artifacts before writing.

4. Validate Specification

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

• If all items pass: proceed to step 5
• If items fail (excluding NEEDS CLARIFICATION):
  1. List failing items with specific issues
  2. Update the spec to address each issue
  3. Re-validate (max 3 iterations)
  4. If still failing after 3 iterations, document in checklist notes and warn user

5. Check Compliance

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

• Task: "Validate 'FEATURE_DIR/spec.md' against project instructions."
• Action: Append result to a "## Compliance Check" section at the end of the spec.md file (create section if missing).
• Gate: If FAIL, warn the user that this must be resolved during the Planning phase.

6. Handle Clarifications

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

1. Extract all markers from the spec
2. LIMIT CHECK: If more than 3, keep only the 3 highest-impact uncertainties for user clarification and resolve only low-impact residual items with informed defaults
3. For each clarification, ask the user to choose from options:
   • Mark the recommended option with reasoning
   • Provide 2-4 alternative options with implications
   • Allow free-form input for custom answers
4. Update the spec with the user's choices, replacing each [NEEDS CLARIFICATION] marker
5. Re-validate after all clarifications resolved

6.5 Amend Shared Project Documents

This step runs before final reporting and updates project-level documents with only cross-feature, general-interest insights.

6.5.1 Trigger

1. List immediate child entries under specs/.
2. Count folders matching ^\d{5}-.
3. If the count is greater than 1, continue with amendments.
4. If the count is 0 or 1, skip this step entirely.

6.5.2 Target Documents

Use the Context Report values:

• Product Document: HAS_PRODUCT_DOC + PRODUCT_DOC
• Technical Context Document: HAS_TECH_CONTEXT_DOC + TECH_CONTEXT_DOC

For each document where the HAS_* flag is true:

1. Read the file at the configured path.
2. If unreadable or missing, record a warning and continue with other documents (non-blocking).

6.5.3 Content Scope (Strict)

Extract and carry forward only information of general project interest from the current spec.md:

• Domain glossary/terminology
• Cross-cutting constraints (e.g., compliance, security/privacy, policy, performance expectations stated in business terms)
• Reusable actors/capabilities likely to apply across multiple features

Do not include:

• Feature-specific user flows or acceptance scenarios
• Story-level details tied only to this feature
• Feature-specific API/schema/data-model details

6.5.4 Merge Strategy (Managed Section Full Rewrite)

For each target document:

1. Maintain a dedicated section named ## Project Context Baseline Updates.
2. Parse any existing entries in that section and normalize them.
3. Merge normalized existing entries with newly extracted general-interest insights.
4. De-duplicate semantically similar entries.
5. Rewrite the managed section in full with the merged, deduplicated set.
6. Preserve all other document content outside the managed section unchanged.

If the section does not exist, create it at the end of the document.

6.5.5 Failure Handling

• Document amendment failures are warnings, not blockers.
• Continue the Specify workflow and include warnings in the final report.

7. Report

Output:

• Branch name and spec file path
• Checklist validation results
• Compliance check status (verifying it was appended to the file)
• Shared document amendment summary (trigger status, updated files, warnings)
• Suggest next steps with explicit labels — for each option, compose a useful suggested prompt for the user based on the current context:
  1. /sddp-clarify (optional — recommended if spec has NEEDS CLARIFICATION markers or ambiguous requirements) — compose a suggested prompt
  2. /sddp-plan (required) — compose a suggested prompt