conversation-to-spec

name

conversation-to-spec

description

Guide conversational requirement gathering with domain experts (non-coders), then automatically draft SEA specifications (ADR → PRD → SDS → SEA-DSL), check generator availability, and trigger generator creation if needed. Democratizes software development so domain experts can chat about their needs and get working software without hallucinations (generator-first principle). Requires confirmed claims from conversational-development skill before spec drafting begins.

Conversation-to-Spec

Vision: Domain experts who don't know how to code can chat with an AI agent about their problem, agree on what to build, have specs drafted automatically, and get working software without hallucinations.

No-Technical-Debt Rule

This skill forbids placeholders of any kind:

• No TODO/FIXME/XXX/HACK/STUB markers
• No stubs, mocks-as-implementations, or empty handlers
• No raise NotImplementedError / throw new Error("not implemented")
• No pass or placeholder logic

Core Workflow

Phase 1: Discovery & Understanding
├─ Ask clarifying questions about domain, users, problems
├─ Identify domain concepts (link to semantic-anchoring)
├─ Confirm understanding before proceeding
└─ Document session context

Phase 2: Requirement Extraction
├─ Extract functional requirements from confirmed claims
├─ Extract non-functional requirements
├─ Identify constraints & invariants
├─ Map to existing patterns (check if generators exist)
└─ EARS format requirement conversion

Phase 3: Spec Drafting
├─ Choose appropriate spec type based on stage
├─ Add semantic references to Knowledge Graph
└─ Maintain traceability chain: ADR → PRD → SDS → SEA-DSL

Phase 4: Generator Check
├─ Query sea-pattern-library for existing patterns
├─ Identify gaps (missing generators/adapters)
└─ Flag for sea-generator-builder if needed

Phase 5: Validation
├─ Validate spec with governance-validation
├─ Validate semantic references
├─ Verify spec-first compliance
└─ Get user confirmation before proceeding

Phase 6: Artifact Presentation
├─ Present CADSL artifacts to stakeholders
├─ Deliver generated spec artifacts
├─ Capture feedback and next steps
└─ Iterate (update specs + re-validate)

---

Phase 1: Discovery & Understanding

Progressive Question Framework

Problem Domain (Start Here):

Question	Purpose
"What problem are you trying to solve?"	Core need identification
"Who will use this system?"	User identification
"What happens when this problem occurs?"	Impact understanding
"What would success look like?"	Outcome definition

Domain Concepts (Semantic Anchoring):

Identify key nouns and verbs — these become domain concepts:

User says: "We need to track customer orders and process payments"
         ↓
Extract concepts:
- Customer (Entity)
- Order (Entity)
- Track (Action/Flow)
- Process (Action/Flow)
- Payment (Entity/Flow)

Current State:

Question	Why It Matters
"How do you handle this now?"	Reveals existing patterns, manual workarounds
"What tools/systems do you use?"	Integration points, existing data
"What frustrates you about the current approach?"	Pain points become requirements
"What would you never want to change?"	Invariants and constraints

Confirmation Loop (CRITICAL):

Before proceeding, ALWAYS confirm understanding:

"Let me confirm what I understand so far:

You need [SYSTEM NAME] that helps [WHO] to [DO WHAT] by [HOW].

Key things it needs to do:
1. [Requirement 1]
2. [Requirement 2]
3. [Requirement 3]

Is this correct? What did I miss or misunderstand?"

Wait for confirmation. If the user corrects you, update your understanding and repeat.

Cognitive Artifact Generation During Discovery

Generate CADSL artifacts to visualize understanding as conversation progresses:

Conversation Pattern	Artifact
"We need to ensure X, Y, Z"	Checklist
"Should we do A or B?"	Decision Tree
"When will this be ready?"	Timeline/Roadmap
"How do these concepts relate?"	Mind Map
"Who needs to approve this?"	Stakeholder Map

Invoke the cognitive-artifacts skill from sea-domain-forge to generate these.

---

Phase 2: Requirement Extraction

EARS Format (Easy Approach to Requirements Syntax)

Pattern	Template	Example
Ubiquitous	"The system shall [action]"	"The system shall store customer orders"
Event-Driven	"When [trigger], the system shall [action]"	"When payment succeeds, the system shall send confirmation"
State-Driven	"While [state], the system shall [action]"	"While order is pending, the system shall show status"
Optional	"Where [condition], the system shall [action]"	"Where user is premium, the system shall show extra features"
Unwanted	"If [condition], then the system shall [prevent]"	"If payment fails, then the system shall prevent order completion"

Requirement Classification

Category	How to Identify
Functional	"The system shall create, read, update, delete, calculate, notify"
Non-Functional	"How well" — fast, secure, reliable, scalable, usable
Constraint	"Must/never" hard limits — GDPR, data retention, role-based access
Invariant	Business rules that never change — "Order total = sum of items"

Epistemic gate: Only use claims with epistemic_status: "declared" from the conversational-development skill as inputs to EARS extraction. Never convert observed claims directly into requirements.

---

Phase 3: Spec Drafting

Choose Spec Type

Stage	Spec Type	When to Use
Early/Exploratory	ADR	Architecture decision, technology choices
Requirements Defined	PRD	Features, user stories, acceptance criteria
Design Ready	SDS	Technical design, SEA-DSL flows
Implementation Ready	SEA-DSL	Entity/flow definitions for code generation

Spec Content Templates

ADR:

# ADR-XXX: [Title]

## Context
[Why this decision needs to be made]

## Decision
[What was decided]

## Consequences
- Positive: [benefits]
- Negative: [costs]
- Neutral: [trade-offs]

## Related
- Follow-up PRD: PRD-XXX

PRD:

# PRD-XXX: [Feature Name]

## Problem Statement
[One paragraph describing the problem]

## User Stories (EARS format)
- US-001: When [event], the [user] shall [action]

## Functional Requirements
- FR-001: The system shall [action]

## Non-Functional Requirements
- NFR-001: [Quality] — [threshold]

## Acceptance Criteria
- [ ] [Measurable criterion]

## Traceability
- Implements: ADR-XXX

SDS:

# SDS-XXX: [Service Name]
boundedContext: [context-name]
service: [service-name]
implements:
  prd: "PRD-XXX"
  adr: "ADR-XXX"

semanticRefs:
  - conceptId: "sea:BoundedContext"
  - conceptId: "domain:[Entity]"

Traceability Chain

Every spec MUST link to its upstream documents supported by the current traceability model (ADR/PRD/SDS). SEA-DSL and generated-code links should be added when corresponding traceability types are implemented.

ADR → PRD → SDS → SEA-DSL → Generated Code

---

Phase 4: Generator Check

Check for existing generators before creating new ones:

# List existing SEA-DSL specs
find docs/specs -name "*.sea" -type f

# Check for similar patterns
grep -r "Entity \"Customer\"" docs/specs
grep -r "Flow \"Create" docs/specs

What You Need	Gap?	Action
Entity CRUD	No	Use bounded-context generator
Message pub/sub	No	Use outbox publisher
New domain pattern	Yes	Flag for sea-generator-builder

---

Phase 5: Validation

just spec-guard     # Validate spec structure + cross-references
just flow-lint      # Enforce CQRS annotation requirements

Before finalizing, get explicit user confirmation:

"I've drafted the specifications based on our conversation:

[Summary of specs created]

✅ Validated:
- Spec structure: PASS
- CQRS annotations: PASS
- Semantic references: PASS
- Governance constraints: PASS

Next steps:
1. Review the specs at [path]
2. If approved, run the generation pipeline
3. Generated code will be at [path]

Does this look correct? Should I proceed with generation?"

---

Phase 6: Artifact Presentation

1. Generate CADSL artifacts for interactive review (via cognitive-artifacts skill)
2. Allow domain experts to check/uncheck requirements, adjust timelines
3. Validate all artifact semanticRefs link to Knowledge Graph concepts
4. Link artifacts to specs for traceability:

# In SDS frontmatter
artifacts:
  - type: "Requirements Checklist"
    path: ".omc/artifacts/requirements-checklist.html"
    semanticAnchor: "sea:Flow"

5. Offer to generate an internal communication summarizing what was produced (via internal-comms skill)