Spec Miner

# Analysis Checklist

## Comprehensive Checklist

| Area | What to Find | Glob/Grep Patterns |
|------|--------------|-------------------|
| **Entry points** | main.ts, app.ts, index.ts | `**/main.{ts,js,py}` |
| **Routes** | Controllers, route files | `**/routes/**/*`, `@Controller` |
| **Models** | Entities, schemas | `**/models/**/*`, `@Entity` |
| **Auth** | Guards, middleware, JWT | `**/auth/**/*`, `passport` |
| **Validation** | DTOs, validators, pipes | `**/dto/**/*`, `@IsString` |
| **Error handling** | Exception filters, try/catch | `ExceptionFilter`, `catch` |
| **External calls** | HTTP clients, SDK usage | `fetch(`, `axios.` |
| **Config** | Env files, config modules | `**/.env*`, `ConfigService` |
| **Tests** | Test files reveal behaviors | `**/*.spec.ts`, `**/*.test.ts` |
| **Background jobs** | Queues, cron, workers | `@Cron`, `Bull`, `Queue` |

## Analysis Phases

### Phase 1: Structure Discovery
- [ ] Identify technology stack
- [ ] Map directory structure
- [ ] Find entry points
- [ ] List all modules/packages

### Phase 2: API Surface
- [ ] Document all endpoints
- [ ] Note HTTP methods and paths
- [ ] Identify request/response formats
- [ ] Find authentication requirements

### Phase 3: Data Layer
- [ ] Map all data models
- [ ] Document relationships
- [ ] Find migrations
- [ ] Note validation rules

### Phase 4: Business Logic
- [ ] Trace main flows
- [ ] Identify business rules
- [ ] Document state transitions
- [ ] Find external integrations

### Phase 5: Security
- [ ] Check authentication method
- [ ] Review authorization patterns
- [ ] Find input validation
- [ ] Note security configurations

### Phase 6: Quality & Testing
- [ ] Review existing tests
- [ ] Note test coverage
- [ ] Document error handling
- [ ] Find logging patterns

## Verification Questions

Before finalizing specification:

- [ ] All endpoints documented?
- [ ] All models mapped?
- [ ] Authentication flow clear?
- [ ] Error responses documented?
- [ ] External dependencies listed?
- [ ] Uncertainties flagged?


# Analysis Process

## Step 1: Project Structure

```bash
# Find entry points
Glob: **/main.{ts,js,py,go}
Glob: **/app.{ts,js,py}
Glob: **/index.{ts,js}

# Find routes/controllers
Glob: **/routes/**/*.{ts,js}
Glob: **/controllers/**/*.{ts,js}
Grep: @Controller|@Get|@Post|router\.|app\.get
```

## Step 2: Data Models

```bash
# Database schemas
Glob: **/models/**/*.{ts,js,py}
Glob: **/schema*.{ts,js,py,sql}
Glob: **/migrations/**/*
Grep: @Entity|class.*Model|schema\s*=
```

## Step 3: Business Logic

```bash
# Services and logic
Glob: **/services/**/*.{ts,js}
Grep: async.*function|export.*class
```

## Step 4: Authentication & Security

```bash
# Auth patterns
Glob: **/auth/**/*
Glob: **/guards/**/*
Grep: @Guard|middleware|passport|jwt
```

## Step 5: External Integrations

```bash
# External calls
Grep: fetch\(|axios\.|HttpService|request\(
Glob: **/integrations/**/*
Glob: **/clients/**/*
```

## Step 6: Configuration

```bash
# Config files
Glob: **/*.config.{ts,js}
Glob: **/.env*
Glob: **/config/**/*
```

## Quick Reference

| Pattern | Purpose |
|---------|---------|
| `**/main.{ts,js,py}` | Entry points |
| `**/routes/**/*` | API routes |
| `**/models/**/*` | Data models |
| `@Controller\|@Get` | NestJS patterns |
| `router.\|app.get` | Express patterns |


# EARS Format

## EARS Syntax

Easy Approach to Requirements Syntax for clear, unambiguous requirements.

### Basic Patterns

**Ubiquitous (Always)**
```
The system shall [action].
```

**Event-Driven**
```
When [trigger], the system shall [action].
```

**State-Driven**
```
While [state], the system shall [action].
```

**Conditional**
```
While [state], when [trigger], the system shall [action].
```

**Optional**
```
Where [feature enabled], the system shall [action].
```

## Example Observations

### Authentication

**OBS-AUTH-001: Login Flow**
```
While credentials are valid, when POST /auth/login is called,
the system shall return JWT access token (15m) and refre