# SDD Workflow - 8 Stages

**Version**: 1.0
**Framework**: ITDA Specification Driven Development

---

## Overview

This document defines the complete 8-stage Specification Driven Development workflow used in this project. Each stage has dedicated skills, quality gates, and constitutional validation.

```
Research → Requirements → Design → Tasks → Implementation → Testing → Deployment → Monitoring
```

---

## Stage 1: Research

**Purpose**: Gather information, explore options, evaluate technologies

### Responsible Skills

- `@requirements-analyst` - Stakeholder interviews, domain research
- `@system-architect` - Technology evaluation, architecture research
- `@technical-writer` - Documentation research

### Activities

1. **Stakeholder Interviews**
   - Identify business goals
   - Understand user needs
   - Clarify constraints

2. **Domain Research**
   - Study domain concepts
   - Review existing solutions
   - Identify best practices

3. **Technology Evaluation**
   - Research frameworks/libraries
   - Compare alternatives
   - Assess team expertise

4. **Feasibility Analysis**
   - Technical feasibility
   - Resource feasibility
   - Timeline feasibility

### Deliverables

- `research.md` - Research findings and recommendations
- Technology comparison matrix
- Feasibility assessment

### Quality Gates

- [ ] Research questions answered
- [ ] Options evaluated (minimum 2)
- [ ] Recommendations justified
- [ ] Stakeholders reviewed

### Constitutional Validation

- **Article VI**: Consult `steering/tech.md` for technology stack
- **Article VI**: Consult `steering/structure.md` for architecture patterns

### Template

Use `templates/research.md` template.

---

## Stage 2: Requirements

**Purpose**: Define unambiguous, testable requirements in EARS format

### Responsible Skills

- `@requirements-analyst` - EARS requirements creation
- `@project-manager` - Priority, scope, timeline
- `@change-impact-analyzer` - Impact analysis (brownfield)

### Activities

1. **Requirements Gathering**
   - Extract from stakeholder interviews
   - Analyze user stories
   - Identify functional/non-functional requirements

2. **EARS Conversion**
   - Convert to EARS format (5 patterns)
   - Add acceptance criteria
   - Assign requirement IDs (REQ-XXX-NNN)

3. **Requirements Review**
   - Stakeholder validation
   - Completeness check
   - Ambiguity elimination

4. **Impact Analysis** (Brownfield only)
   - Identify ADDED requirements
   - Identify MODIFIED requirements
   - Identify REMOVED requirements
   - Assess breaking changes

### Deliverables

- `requirements.md` - EARS requirements with acceptance criteria
- Requirements coverage matrix
- `changes.md` - Delta specification (brownfield)

### Quality Gates

- [ ] All requirements in EARS format
- [ ] Requirement IDs assigned
- [ ] Acceptance criteria defined
- [ ] Stakeholders approved
- [ ] **Constitutional validation passed (Article IV)**

### Constitutional Validation

- **Article IV**: EARS format enforced
- **Article V**: Requirements assigned unique IDs
- **Article VI**: Consult `steering/product.md` for business context

### Validation Command

```bash
@constitution-enforcer validate requirements.md
```

### Template

Use `templates/requirements.md` template.

---

## Stage 3: Design

**Purpose**: Create technical design with requirements traceability

### Responsible Skills

- `@system-architect` - Architecture, C4 diagrams, ADR
- `@api-designer` - API contracts (REST/GraphQL/gRPC)
- `@database-schema-designer` - Database schema, ER diagrams
- `@ui-ux-designer` - UI/UX wireframes, prototypes

### Activities

1. **Architecture Design**
   - Define system structure
   - Create C4 diagrams (Context, Container, Component)
   - Write Architecture Decision Records (ADR)
   - Map requirements to components

2. **API Design**
   - Define API contracts
   - Create OpenAPI/GraphQL schemas
   - Document endpoints
   - Map requirements to endpoints

3. **Database Design**
   - Create ER diagrams
   - Define schema (tables, relationships)
   - Generate DDL statements
   - Map requirements to entities

4. **UI/UX Design** (if applicable)
   - Create wireframes
   - Design user flows
   - Define design system
   - Map requirements to screens

5. **Requirements Traceability**
   - Create requirements coverage matrix
   - Map requirements → design decisions
   - Validate 100% coverage

### Deliverables

- `design.md` - Complete technical design
- C4 diagrams (Context, Container, Component)
- ADR documents
- API specifications (OpenAPI/GraphQL)
- Database DDL
- Requirements coverage matrix

### Quality Gates

- [ ] All requirements mapped to design
- [ ] Architecture aligned with `steering/structure.md`
- [ ] Technology stack matches `steering/tech.md`
- [ ] ADRs document key decisions
- [ ] **Constitutional validation passed (Articles I, II, VII, VIII)**

### Constitutional Validation

- **Article I**: Features designed as libraries
- **Article II**: CLI interfaces specified
- **Article V**: 100% requirements coverage
- **Article VI**: Design aligned with steering files
- **Article VII**: Project count ≤ 3 (or Phase -1 Gate approval)
- **Article VIII**: No custom abstraction layers (or Phase -1 Gate approval)

### Validation Command

```bash
@constitution-enforcer validate design.md
```

### Phase -1 Gates

Trigger gates if:

- Project count > 3 (Article VII)
- Custom abstraction layers proposed (Article VIII)

### Template

Use `templates/design.md` template.

---

## Stage 4: Tasks

**Purpose**: Break design into actionable implementation tasks

### Responsible Skills

- `@project-manager` - Task breakdown, scheduling, dependencies
- `@software-developer` - Implementation planning
- `@test-engineer` - Test planning

### Activities

1. **Task Decomposition**
   - Break design into implementation tasks
   - Define task dependencies
   - Estimate effort (story points/hours)
   - Assign priority (P0, P1, P2, P3)

2. **Requirements Mapping**
   - Map tasks to requirements
   - Validate coverage
   - Identify gaps

3. **Test Planning**
   - Plan unit tests
   - Plan integration tests
   - Plan E2E tests
   - Map tests to requirements

4. **Scheduling**
   - Create sprint/milestone plan
   - Allocate resources
   - Identify risks

### Deliverables

- `tasks.md` - Task breakdown with requirements mapping
- Sprint/milestone plan
- Test plan
- Requirements coverage matrix (tasks → requirements)

### Quality Gates

- [ ] All requirements mapped to tasks
- [ ] Task dependencies identified
- [ ] Effort estimated
- [ ] Test plan complete
- [ ] Risks identified

### Constitutional Validation

- **Article V**: Tasks mapped to requirements
- **Article VI**: Plan aligned with steering context

### Template

Use `templates/tasks.md` template.

---

## Stage 5: Implementation

**Purpose**: Write code following Test-First imperative

### Responsible Skills

- `@software-developer` - Code implementation
- `@test-engineer` - Test implementation (BEFORE code)
- `@code-reviewer` - Code review

### Activities

1. **Test-First Development (Red-Green-Blue)**
   - **Red**: Write failing test for requirement
   - **Green**: Write minimal code to pass test
   - **Blue**: Refactor with confidence

2. **Library-First Implementation**
   - Implement features as libraries
   - Expose CLI interface
   - Write library tests
   - Document library API

3. **Code Review**
   - SOLID principles validation
   - Security audit (OWASP Top 10)
   - Performance review
   - Best practices enforcement

4. **Traceability**
   - Add requirement IDs in code comments
   - Reference requirements in commit messages
   - Update requirements coverage matrix

### Deliverables

- Source code (libraries + applications)
- Test suites (unit, integration, E2E)
- CLI interfaces
- Code review reports

### Quality Gates

- [ ] **Tests written BEFORE code (Article III)**
- [ ] **Features implemented as libraries (Article I)**
- [ ] **CLI interfaces provided (Article II)**
- [ ] Test coverage ≥ 80%
- [ ] Code review passed
- [ ] No critical security issues
- [ ] **Constitutional validation passed**

### Constitutional Validation

- **Article I**: Library-First enforced
- **Article II**: CLI interfaces exist
- **Article III**: Test-First followed (check git history)
- **Article V**: Code comments reference requirements
- **Article VI**: Code aligned with steering context

### Validation Command

```bash
@constitution-enforcer validate src/
@code-reviewer review src/
@security-auditor audit src/
```

### Red-Green-Blue Cycle Example

```bash
# 1. RED - Write failing test
git commit -m "test: add failing test for REQ-AUTH-001"

# 2. GREEN - Write minimal code
git commit -m "feat: implement REQ-AUTH-001 (authentication)"

# 3. BLUE - Refactor
git commit -m "refactor: improve authentication logic (REQ-AUTH-001)"
```

---

## Stage 6: Testing

**Purpose**: Validate all requirements are met with real services

### Responsible Skills

- `@test-engineer` - Test execution, coverage analysis
- `@quality-assurance` - QA strategy, acceptance testing
- `@traceability-auditor` - Requirements coverage validation

### Activities

1. **Test Execution**
   - Run unit tests
   - Run integration tests (real services)
   - Run E2E tests
   - Measure coverage

2. **Traceability Validation**
   - Validate requirements → test mapping
   - Identify untested requirements
   - Verify 100% coverage

3. **Integration Testing (Real Services)**
   - Use real databases (Docker containers)
   - Use test environments for external APIs
   - Justify any mocks

4. **Acceptance Testing**
   - Validate acceptance criteria
   - User acceptance testing (UAT)
   - Stakeholder sign-off

### Deliverables

- Test execution reports
- Coverage reports (≥ 80%)
- Traceability audit report (100% coverage)
- UAT results
- Bug reports

### Quality Gates

- [ ] All tests passing
- [ ] Coverage ≥ 80%
- [ ] **100% requirements coverage (Article V)**
- [ ] **Integration tests use real services (Article IX)**
- [ ] UAT passed
- [ ] **Constitutional validation passed**

### Constitutional Validation

- **Article III**: Test-First evidence in git history
- **Article V**: 100% requirements → test coverage
- **Article IX**: Integration tests use real services (mocks justified)

### Validation Command

```bash
@traceability-auditor validate requirements.md tests/
@constitution-enforcer validate tests/
```

---

## Stage 7: Deployment

**Purpose**: Deploy to production with monitoring

### Responsible Skills

- `@devops-engineer` - CI/CD pipelines, deployment automation
- `@cloud-architect` - Infrastructure provisioning (IaC)
- `@release-coordinator` - Multi-component release management
- `@site-reliability-engineer` - Production readiness review

### Activities

1. **Infrastructure Provisioning**
   - Provision cloud resources (Terraform/Bicep)
   - Configure environments (dev, staging, prod)
   - Set up databases, caching, queues

2. **CI/CD Pipeline**
   - Automated build
   - Automated testing
   - Automated deployment
   - Rollback strategy

3. **Release Coordination**
   - Coordinate multi-component releases
   - Feature flag configuration
   - Backward compatibility validation
   - Staged rollout plan

4. **Production Readiness**
   - Health check endpoints
   - Logging configuration
   - Monitoring setup
   - Alerting rules

5. **Deployment Execution**
   - Deploy to staging
   - Smoke tests
   - Deploy to production
   - Monitor deployment

### Deliverables

- IaC code (Terraform/Bicep)
- CI/CD pipeline configuration
- Deployment runbooks
- Rollback procedures
- Production readiness checklist

### Quality Gates

- [ ] Staging deployment successful
- [ ] Smoke tests passed
- [ ] Monitoring configured
- [ ] Alerts configured
- [ ] Rollback tested
- [ ] Production readiness review passed

### Constitutional Validation

- **Article VI**: Infrastructure aligned with `steering/structure.md`

---

## Stage 8: Monitoring

**Purpose**: Monitor production, respond to incidents, iterate

### Responsible Skills

- `@site-reliability-engineer` - SLO/SLI monitoring, incident response
- `@performance-optimizer` - Performance monitoring, optimization
- `@bug-hunter` - Production bug investigation

### Activities

1. **Observability Setup**
   - Metrics collection (Prometheus, CloudWatch)
   - Log aggregation (ELK, Splunk)
   - Distributed tracing (Jaeger, Zipkin)
   - Dashboards (Grafana)

2. **SLO/SLI Monitoring**
   - Define Service Level Objectives (SLO)
   - Define Service Level Indicators (SLI)
   - Monitor error budgets
   - Alert on SLO violations

3. **Incident Response**
   - On-call rotation
   - Incident detection
   - Incident resolution
   - Post-mortem analysis

4. **Performance Monitoring**
   - Response time tracking
   - Resource utilization
   - Bottleneck detection
   - Optimization opportunities

5. **Continuous Improvement**
   - Analyze metrics
   - Identify improvements
   - Create new requirements (→ Stage 2)
   - Iterate

### Deliverables

- SLO/SLI definitions
- Monitoring dashboards
- Alert rules
- Incident runbooks
- Post-mortem reports
- Performance reports

### Quality Gates

- [ ] SLO/SLI defined and monitored
- [ ] Alerts configured and tested
- [ ] Incident response procedures documented
- [ ] Performance baselines established
- [ ] Post-mortem process in place

### Constitutional Validation

- **Article VI**: Monitor metrics aligned with product goals in `steering/product.md`

---

## Workflow Iteration

### Greenfield (0→1)

Full 8-stage workflow for new projects:

```
Research → Requirements → Design → Tasks → Implementation → Testing → Deployment → Monitoring
```

### Brownfield (1→n)

For changes to existing projects:

```
Research (change analysis) → Requirements (delta spec) →
Design (impact analysis) → Tasks → Implementation → Testing → Deployment → Monitoring
```

**Skills for Brownfield**:

- `@change-impact-analyzer` - Analyze ADDED/MODIFIED/REMOVED requirements
- `@traceability-auditor` - Validate existing coverage before changes

---

## Stage Summary Table

| Stage             | Skills                                                                           | Deliverables                  | Constitutional Articles |
| ----------------- | -------------------------------------------------------------------------------- | ----------------------------- | ----------------------- |
| 1. Research       | requirements-analyst, system-architect, technical-writer                         | research.md                   | VI                      |
| 2. Requirements   | requirements-analyst, project-manager, change-impact-analyzer                    | requirements.md, changes.md   | IV, V, VI               |
| 3. Design         | system-architect, api-designer, database-schema-designer, ui-ux-designer         | design.md, C4, ADR, API specs | I, II, V, VI, VII, VIII |
| 4. Tasks          | project-manager, software-developer, test-engineer                               | tasks.md, test plan           | V, VI                   |
| 5. Implementation | software-developer, test-engineer, code-reviewer                                 | source code, tests, CLI       | I, II, III, V, VI       |
| 6. Testing        | test-engineer, quality-assurance, traceability-auditor                           | test reports, coverage        | III, V, IX              |
| 7. Deployment     | devops-engineer, cloud-architect, release-coordinator, site-reliability-engineer | IaC, CI/CD, runbooks          | VI                      |
| 8. Monitoring     | site-reliability-engineer, performance-optimizer, bug-hunter                     | SLO/SLI, dashboards, alerts   | VI                      |

---

## Quick Start

### For New Features (Greenfield)

```bash
# Stage 1: Research
@requirements-analyst research [feature]

# Stage 2: Requirements
@requirements-analyst create requirements for [feature]

# Stage 3: Design
@system-architect design architecture for [feature]
@api-designer design API for [feature]

# Validate before proceeding
@constitution-enforcer validate requirements.md
@constitution-enforcer validate design.md

# Stage 4: Tasks
@project-manager break down tasks for [feature]

# Stage 5: Implementation
@test-engineer write tests for [requirement-id]
@software-developer implement [requirement-id]
@code-reviewer review [files]

# Stage 6: Testing
@traceability-auditor validate coverage
@test-engineer run all tests

# Stage 7: Deployment
@devops-engineer deploy to staging
@site-reliability-engineer production readiness review

# Stage 8: Monitoring
@site-reliability-engineer configure monitoring
```

### For Changes (Brownfield)

```bash
# Analyze impact first
@change-impact-analyzer analyze [change-description]

# Create delta specification
@requirements-analyst create delta spec for [change]

# Continue with stages 3-8...
```

---

**Powered by ITDA** - 8-stage specification-driven development workflow.