Tdd

Create the Technical Design Document. Argument: $ARGUMENTS

Context Gathering

Before interviewing, explore the project's current build and test setup:

1. Check for existing docs:

• Read docs/TECHNICAL_DESIGN_DOCUMENT.md — if revising, don't start from scratch
• Read CLAUDE.md for build/test commands
• Read docs/ARCHITECTURE.md if it exists (for technology context)
• Read README.md for setup instructions

1. Explore the codebase:

• Look for test directories (tests/, __tests__/, spec/, *_test.go, *.test.ts, test_*.py)
• Read package.json, pyproject.toml, Cargo.toml, Makefile, docker-compose.yml for tooling, test commands, dependencies
• Read 1-2 existing test files to understand patterns (fixtures, helpers, naming)
• Check for CI config (.github/workflows/, .gitlab-ci.yml, Jenkinsfile)
• Check for linter/formatter config (.eslintrc, ruff.toml, .golangci.yml, rustfmt.toml)
• Summarize what you found to the user before starting — "Here's what I see in the project: ..."

Interview

Use AskUserQuestion to understand how the team builds, tests, and ships. Adapt based on what the codebase already reveals.

1. Testing strategy — What test frameworks are in use? Where do tests live? Are there separate unit/integration/e2e layers? What needs integration tests vs unit tests? Any critical flows that need e2e coverage?
2. Dev environment — How do developers set up locally? Docker, nix, manual install? What external services are needed (databases, queues, caches)?
3. CI/CD pipeline — What runs on every PR? What runs nightly? What gates block merging? How are deployments triggered?
4. Coding standards — Linter config, formatter, type checker? Any style guides or conventions not captured in tooling?
5. Tooling decisions — Package manager, build system, monorepo tools? Why these over alternatives?
6. Error handling & observability — Logging framework, error tracking, metrics? How do you debug production issues?
7. Dependencies — How are deps managed? Pinned versions? Vulnerability scanning? Update cadence?

For inherited projects, explore before asking — "I see you have pytest with a tests/ folder but no integration tests yet — is that intentional?" and "Your CI runs make test but there's no lint step — is that by design?"

Write

Write to docs/TECHNICAL_DESIGN_DOCUMENT.md:

# Technical Design Document

**Version:** [version]
**Date:** [date]

## Testing Strategy

[This section is the source of truth that all other skills (/feature, /fix, /roadmap, /autopilot) reference when deciding what tests to write.]

### Test Layers

| Layer | Scope | Framework | Run Command | When to Write |
|-------|-------|-----------|-------------|---------------|
| Unit | Single function/module, no I/O | [e.g., pytest, vitest, go test] | [e.g., make test-unit] | Every change — business logic, pure functions, validators |
| Integration | Component boundaries, real dependencies | [e.g., pytest + testcontainers, supertest] | [e.g., make test-integration] | API endpoints, database queries, service interactions, middleware |
| E2E | Full user flows, production-like environment | [e.g., playwright, cypress, k6] | [e.g., make test-e2e] | Critical user paths, auth flows, payment flows |

### Test Conventions

- **File location:** [e.g., `tests/unit/`, `tests/integration/`, `tests/e2e/` or colocated `__tests__/`]
- **Naming:** [e.g., `test_.py`, `.test.ts`, `_test.go`]
- **Fixtures/factories:** [where shared test helpers live]
- **Test database:** [how integration tests get a database — testcontainers, sqlite, etc.]
- **CI behavior:** [which layers run on PR, which run nightly]

### Coverage Expectations

- Unit tests: cover all business logic, validation, and error paths
- Integration tests: cover all API endpoints, database operations, and external service calls
- E2E tests: cover critical user journeys (list the 3-5 most important flows)

## Dev Environment

### Setup

[Step-by-step local setup. Prerequisites, install commands, env vars.]

### External Dependencies

| Service | Local Setup | Purpose |
|---------|------------|---------|
| [e.g., PostgreSQL] | [e.g., docker compose up] | [e.g., primary data store] |

## CI/CD Pipeline

### PR Checks

| Check | Command | Blocks Merge |
|-------|---------|-------------|
| [e.g., Lint] | [e.g., make lint] | Yes |
| [e.g., Unit tests] | [e.g., make test-unit] | Yes |
| [e.g., Integration tests] | [e.g., make test-integration] | Yes |
| [e.g., E2E tests] | [e.g., make test-e2e] | No (nightly) |

### Deployment

[How deployments are triggered. Environments, promotion strategy, rollback procedure.]

## Coding Standards

- **Linter:** [tool and config file]
- **Formatter:** [tool and config file]
- **Type checker:** [tool and config file]
- **Conventions not captured in tooling:** [anything humans need to know]

## Tooling

| Tool | Purpose | Why This Over Alternatives |
|------|---------|---------------------------|
| [tool] | [what it does] | [rationale] |

## Error Handling & Observability

- **Logging:** [framework, format, levels]
- **Error tracking:** [service, how errors are reported]
- **Metrics:** [what's measured, where dashboards live]

## Dependency Management

- **Package manager:** [tool]
- **Version strategy:** [pinned, ranges, etc.]
- **Vulnerability scanning:** [tool, frequency]
- **Update cadence:** [how often, who owns it]

Adapt the structure to the project. A small project may skip Observability. A monorepo may need per-package sections. Use judgment.

After Writing

1. Present the document to the user for review. Iterate until they're satisfied.
2. Suggest next steps based on what exists:

• No architecture doc? → "Define system structure with /architecture"
• No threat model? → "Consider /security for the threat model"
• Ready to build? → "Create feature specs with /spec , then /roadmap"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0xrafasec
• Source: 0xrafasec/ai-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.