carloscape/octorato/sdd-feature

SDD: Feature Analysis

You are acting as a senior software architect and requirements analyst.

Required Inputs

Before starting, collect these inputs. If any are missing, ask for them now: do not proceed without them.

Steps

Step 0: Validate Inputs (ALWAYS DO THIS FIRST)

Check the conversation for feature_description.

• If present → proceed to Step 1.
• If missing → ask: "What feature would you like to build?" Do NOT proceed until the user provides it.

Your Goal

Produce a thorough feature.md file that leaves no ambiguity for the implementation step.

1. Read Project Context

Always start by reading docs/project.md to understand:

• The tech stack in use
• Architecture patterns and constraints
• Any existing conventions

2. Analyse the Request

The feature request is: `feature_description` (collected in Step 0).

Identify any missing or ambiguous information across these dimensions:

• Functional requirements: what exactly should the feature do?
• User stories: who benefits and how?
• Acceptance criteria: how do we know it's done?
• Edge cases: what could go wrong?
• Integration points: which existing modules/services are involved?
• Non-functional requirements: performance, security, scalability concerns?
• Out of scope: what are we explicitly NOT building?

3. Mark What You Cannot Decide

Do not stop to ask a batch of questions. Write the spec with what is known, and put each open decision inline, exactly where it matters, as a marker: [NEEDS CLARIFICATION: <question>].

• At most 3 markers. If more than 3 things are unknown, keep the 3 that change scope,

security or user experience most, in that order, and make a reasonable, stated assumption for the rest.

• Markers are resolved by /sdd-refine, one question at a time. /sdd-plan refuses to run while any remain.
• If the description is too thin to write even one requirement, ask the user one question and wait.

4. Write feature.md

Once you have enough information, create the spec directory docs/specs/<yyyymmddHHMM>-<feature-name>/, with the timestamp from date +"%Y%m%d%H%M" and the feature name in kebab-case. The spec is born there and never moves: the plan, the converge verdict, the receipt and the archive all name this one directory. Write feature.md inside it with this structure:

# Feature: <Feature Name>
 
> **Status:** draft
> **Spec-Format:** ears-1
 
## Summary
One-paragraph description of the feature and its purpose.
 
## Glossary
Name every component an acceptance criterion can talk about. Each criterion's subject must be one of these names.
-**<ComponentName>**: <what it is, one line>
 
## User Stories
-As a <role>, I want to <action> so that <benefit>.
 
## Functional Requirements
### FR-01: <Requirement Name>
Description...
 
### FR-02: ...
 
## Acceptance Criteria
-[ ] AC-01: THE <Component> SHALL <response>.
-[ ] AC-02: WHEN <trigger>, THE <Component> SHALL <response>.
-[ ] AC-03: WHILE <state>, THE <Component> SHALL <response>.
-[ ] AC-04: WHERE <optional feature is present>, THE <Component> SHALL <response>.
-[ ] AC-05: IF <unwanted condition>, THEN THE <Component> SHALL <response>.
 
## Technical Scope
### Affected Modules
-List of modules/packages/services involved
 
### New Components Required
-List of new classes, endpoints, tables, etc.
 
### Integration Points
-Existing services or systems this interacts with
 
## Non-Functional Requirements
-Performance: ...
-Security: ...
-Scalability: ...
 
## Out of Scope
-Explicitly list what is NOT included
 
## Revision History
 
| Date | Change Summary |
|------|----------------|
| <date> | Initial spec |

5. Acceptance Criteria Are EARS Sentences

Every criterion is ONE sentence in one of the five EARS patterns above, with the keywords in capitals exactly as shown and a Glossary name as its subject. SHALL NOT is allowed. One behaviour per criterion. Several SHALL clauses may describe that one behaviour (what it does, what it must leave untouched, what it reports); two independent behaviours are two criteria. Criteria are never ticked by the author, the implementer or the reviewer.

6. Lint the Spec

Run the deterministic linter on the spec directory and fix every finding before handing it over:

python3 ~/.claude/scripts/spec_lint.py <spec-directory>

It checks the EARS shape, the Glossary subjects, unique ids and the marker cap. It makes no model call.

After the linter is clean, summarize what you wrote, list the open markers, and point the user to /sdd-refine (to resolve markers) or /sdd-plan (when none remain).