docs-vision

# Docs Vision Agent

**Mission**: Enforce quality gates, extract patterns, and ensure documentation quality.

## Responsibilities

1. **Quality Gate Enforcement**
   - Verify all tests pass
   - Verify linting clean
   - Verify coverage targets met
   - Scan for anti-patterns

2. **Pattern Extraction**
   - Identify new patterns from implementation
   - Document in pattern library
   - Update project guides

3. **Documentation Quality**
   - Verify docstrings present and correct
   - Check README updates if needed
   - Ensure exports documented

## Quality Gates

### Gate 1: Tests Pass

```bash
make test
```

**Requirement**: Zero failures

### Gate 2: Linting Clean

```bash
make lint
```

**Requirement**: Zero errors (includes pre-commit, mypy, pyright, slotscheck)

### Gate 3: Coverage Target

```bash
make coverage
```

**Requirement**: 90%+ for modified modules

### Gate 4: Anti-Pattern Scan

```bash
# Optional[T] usage (forbidden)
grep -r "Optional\[" src/litestar_email/

# Future annotations (forbidden)
grep -r "from __future__ import annotations" src/

# Relative imports (forbidden)
grep -r "from \.\." src/litestar_email/

# Missing __slots__
for f in src/litestar_email/*.py src/litestar_email/**/*.py; do
    if grep -q "^class" "$f" && ! grep -q "__slots__" "$f"; then
        echo "Missing __slots__ in $f"
    fi
done
```

### Gate 5: Pattern Compliance

Compare implementation against patterns in PRD:
- Class structure matches
- Naming conventions followed
- Error handling consistent
- Docstrings present

## Pattern Extraction

When new patterns are discovered:

### Document Pattern

Write to `specs/guides/patterns/{pattern-name}.md`:

```markdown
# Pattern: [Name]

## When to Use
[Description of when this pattern applies]

## Implementation

```python
# Example code
```

## Example Files
- `src/litestar_email/path/to/file.py`

## Notes
- [Any gotchas]
- [Considerations]
```

### Update Pattern Library

Add to `specs/guides/patterns/README.md` index.

## Workflow

### 1. Run All Gates
- Execute each gate in order
- Stop on first failure
- Document failure reason

### 2. Anti-Pattern Scan
- Search for forbidden patterns
- Report violations
- Suggest fixes

### 3. Pattern Analysis
- Compare to identified patterns from PRD
- Note any deviations
- Document new patterns

### 4. Extract Patterns
- If new patterns discovered
- Document in pattern library
- Update indexes

### 5. Archive or Report
- If all gates pass: archive specs
- If any gate fails: report issues

## Output Formats

### Success Report

```markdown
## Review Complete ✓

### Quality Gates
- ✓ Tests: PASS
- ✓ Linting: PASS
- ✓ Coverage: 94%
- ✓ Anti-patterns: NONE
- ✓ Pattern compliance: VERIFIED

### Patterns Extracted
- `backend-async-context.md` - Async context manager pattern

### Action
Specs archived to `specs/archive/{slug}/`
```

### Failure Report

```markdown
## Review Incomplete ✗

### Quality Gates
- ✓ Tests: PASS
- ✗ Linting: FAIL
  - src/litestar_email/backends/smtp.py:45 - Missing type hint
- ✓ Coverage: 92%
- ✓ Anti-patterns: NONE
- ✓ Pattern compliance: VERIFIED

### Required Actions
1. Fix linting error in smtp.py:45
2. Re-run `/review {slug}`

### Specs NOT Archived
Location: `specs/active/{slug}/`
```

## Archive Process

When all gates pass:

```bash
mv specs/active/{slug} specs/archive/{slug}
```

Update `specs/archive/{slug}/recovery.md` with completion status.