---
skill_name: [tech]-patterns
description: [Framework]-based [Technology] patterns. Use when writing idiomatic [Technology] code with [Framework], implementing common workflows, or building type-safe operations. Cross-references [tech]-docs for syntax reference.
trigger: When writing [Technology] code with [Framework], implementing [tech] patterns, or handling [tech] errors
keywords: [tech], [technology], patterns, [framework], [key-pattern-1], [key-pattern-2]
version: 0.1.0
---

# [Technology] + [Framework] Patterns

This skill provides [Framework]-based patterns for [Technology]. For complete syntax reference, see **[tech]-docs skill** which contains all official documentation.

## Quick Pattern Reference

**When to use [tech]-docs:**
- Syntax reference: `rg "[SYNTAX-KEYWORD]" ..//[tech]-docs/references/`
- Function reference: `rg "[FUNCTION-NAME]" ../[tech]-docs/references/`
- Complete guides: `rg "[concept]" ../[tech]-docs/references/guides/ -i -l`

**When to use this skill:**
- [Framework]-based patterns
- Common workflows with [Framework]
- Type-safe operations
- Error handling patterns
- Best practices

## [Framework]-Based Patterns

### Basic Pattern 1: [Pattern Name]

```[language]
import { [Framework-Import] } from "[framework]"
import type { [Type-Import] } from "[library]"

// [Pattern description]
const [functionName] = ([params]: [ParamType]) =>
  [Framework].gen(function* () {
    // Step 1: [Description]
    const result = yield* [operation]

    // Step 2: [Description]
    return yield* [transform](result)
  })
```

**Key patterns:**
- Use [pattern-1] for [use-case-1]
- Always [requirement] with `[code-example]`
- Use `.[pipe-operator]` for [composability-note]
- Use proper [framework] [concept] for [purpose]

### Basic Pattern 2: [Repository/Service Pattern]

```[language]
import { [Context], [Framework], [Layer] } from "[framework]"
import { [Client] } from "[library]"

// Define service interface
class [ServiceName] extends [Context].Tag("[ServiceName]")<
  [ServiceName],
  {
    [method1]: ([param]: [Type]) => [Framework].[Effect]<[Return], [Error]>
    [method2]: ([param]: [Type]) => [Framework].[Effect]<[Return]>
    [method3]: () => [Framework].[Effect]<[ReadonlyArray]<[Type]>>
  }
>() {}

// Implement with [Client]
export const [ServiceName]Live = [Layer].[effect](
  [ServiceName],
  [Framework].gen(function* () {
    const client = yield* [Client]

    return [ServiceName].of({
      [method1]: ([param]) =>
        [Framework].gen(function* () {
          const result = yield* client.[operation]([args]).[pipe](
            [Framework].[orDie],
            [Framework].[flatMap](([value]) =>
              [condition]
                ? [Framework].[fail](new [ErrorType]({ [errorProp]: [value] }))
                : [Framework].[succeed]([value])
            )
          )

          return yield* [Schema].[decodeUnknown]([SchemaType])(result)
        }),

      [method2]: ([param]) =>
        [Framework].gen(function* () {
          const id = yield* [generateId]()
          const now = yield* [DateTime].now

          yield* client.[insert]([data]).[pipe]([Framework].[orDie])

          return yield* [Schema].[decode]([SchemaType])({
            [prop1]: [value1],
            [prop2]: [value2],
          })
        }),

      [method3]: () =>
        [Framework].gen(function* () {
          const results = yield* client.[query]([args]).[pipe]([Framework].[orDie])

          return yield* [Framework].[forEach](
            results,
            [Schema].[decodeUnknown]([SchemaType]),
            { [concurrency]: "[value]" }
          ).[pipe]([Framework].[orDie])
        }),
    })
  })
)
```

**Pattern notes:**
- Use [Context].Tag for service definitions
- Return [Framework] types with proper error channels
- Decode ALL [client] results with [Schema]
- Use [Framework].[orDie] for "impossible" errors
- Use proper error types ([ErrorType]) for expected failures

### Advanced Pattern 1: [Complex Workflow]

```[language]
// [Description of complex workflow]
const [workflowName] = (
  client: [ClientType],
  [param1]: [Type1],
  [param2]: [Type2]
) =>
  [Framework].gen(function* () {
    // Step 1: [Description]
    const [result1] = yield* client.[operation1]([args]).[pipe]([Framework].[orDie])

    // Step 2: [Conditional logic]
    if ([condition]) {
      return yield* [Framework].[fail](
        new [ErrorType]({ [prop]: [value] })
      )
    }

    // Step 3: [Operation]
    yield* client.[operation2]([args]).[pipe]([Framework].[orDie])

    // Step 4: [Final operation]
    yield* client.[operation3]([args]).[pipe]([Framework].[orDie])

    return { [successProp]: [value] }
  }).[pipe](
    // Wrap in [transaction/context] for [reason]
    client.[wrapperMethod]
  )
```

**Workflow pattern notes:**
- Use `client.[wrapperMethod]` to wrap [Framework] in [boundary-type]
- [Technology] automatically [handles] [scenario]
- Keep [workflows] [constraint] ([example-constraint])
- Use [alternative] for [use-case]

### Type Safety Pattern: [Schema Validation]

```[language]
// Define [type] schema
class [TypeName] extends [Schema].Class<[TypeName]>("[TypeName]")({
  [prop1]: [Schema].[Type1],
  [prop2]: [Schema].[Type2],
  [prop3]: [Schema].[Type3],
}) {}

// [Operation] with [client]
const [operationName] = (client: [ClientType], [param]: [ParamType]) =>
  [Framework].gen(function* () {
    const result = yield* client.[operation]<{ [key]: { [nestedKey]: unknown } }>`
      [QUERY-SYNTAX]
      [QUERY-BODY]
    `.[pipe]([Framework].[orDie])

    // Decode with Schema for type safety
    return yield* [Schema].[decodeUnknown]([TypeName])(result.[key].[nestedKey]).[pipe](
      [Framework].[orDie]
    )
  })
```

**Type safety notes:**
- Use `[Schema].[Class]` for [type] schemas
- Always decode [source] with `[Schema].[decodeUnknown]`
- Use proper [Framework] [channel] for [purpose]

## Cross-Reference Guide

### Syntax Reference → [tech]-docs

For complete [Technology] syntax, use [tech]-docs references:

```bash
# [Category 1]
rg "[SYNTAX-1]\|[SYNTAX-2]" ../[tech]-docs/references/[category]/

# [Category 2]
rg "[FUNCTION-1]\|[FUNCTION-2]" ../[tech]-docs/references/[category]/

# [Category 3]
rg "[KEYWORD-1]" ../[tech]-docs/references/[category]/
```

### Guides → [tech]-docs

For conceptual understanding and best practices:

```bash
# [Topic 1]
rg "[topic-1-keyword]" ../[tech]-docs/references/guides/ -i -l | head -5

# [Topic 2]
rg "[topic-2-keyword]" ../[tech]-docs/references/guides/ -i -l

# [Topic 3]
rg "[topic-3-keyword]" ../[tech]-docs/references/guides/ -i -l
```

### Code Examples → [tech]-docs

For working code samples:

```bash
# [Language] examples
rg "[import-pattern]" ../[tech]-docs/references/samples/ -l

# [Specific pattern] examples
rg "[pattern-keyword]" ../[tech]-docs/references/samples/ -A10

# [Operation] examples
rg "[operation-keyword]" ../[tech]-docs/references/samples/ -A5
```

## Common Pitfalls & Solutions

### Pitfall 1: [Common Mistake]
**Problem**: [Description of problem]
**Solution**: [Description of solution]

```[language]
// ❌ WRONG
[wrong-code-example]

// ✅ CORRECT
[correct-code-example]
```

### Pitfall 2: [Common Error]
**Problem**: [Error message or scenario]
**Solution**: [Fix description]

```[language]
// Problem code
[problematic-code]

// Fixed code
[fixed-code]
```

### Pitfall 3: [Type Safety Issue]
**Problem**: [Type error scenario]
**Solution**: [Type-safe approach]

```[language]
// ❌ WRONG - no type safety
const [var] = yield* [operation].[pipe]([Framework].[orDie])
[unsafe-access]  // Runtime error!

// ✅ CORRECT - type-safe with Schema
const result = yield* [operation].[pipe]([Framework].[orDie])
const [var] = yield* [Schema].[decodeUnknown]([Type])(result.[key]).[pipe]([Framework].[orDie])
[safe-access]  // Type-safe!
```

## Production Patterns from [Reference Project]

For real-world [Framework] + [Technology] patterns, see:
- `[path/to/services]` - Service implementations
- `[path/to/client]` - Client configuration
- `[path/to/tests]` - Test patterns and fixtures

**Key [project] patterns:**
- Use `[pattern-1]` for [purpose]
- All [services] return [Framework] types with proper [channels]
- [Schema] validation on ALL [operations]
- [Wrapper] with automatic [handling]
- Test [harness] with [test-pattern]

## Next Steps

1. **First time with [Technology]?** → See [tech]-docs skill, run `rg "[getting-started-keyword]" ../[tech]-docs/references/guides/ -i -l`
2. **Need syntax reference?** → See [tech]-docs references
3. **Building a new [service]?** → Copy patterns from [reference-project]
4. **Testing?** → See `[path/to/test-harness]` for test patterns
5. **Advanced [feature]?** → See **[tech]-advanced skill** for [advanced-patterns]

**For complete syntax and API reference, always cross-reference the [tech]-docs skill.**

---

## Template Instructions

**Replace the following placeholders:**

- `[TECH]` → Technology abbreviation (e.g., "pg", "react")
- `[Technology]` → Full technology name (e.g., "PostgreSQL", "React")
- `[tech]` → Lowercase name (e.g., "postgres", "react")
- `[Framework]` → Framework name (e.g., "Effect", "React")
- `[framework]` → Lowercase framework (e.g., "effect", "react")
- `[language]` → Programming language (e.g., "typescript", "python")
- `[Pattern Name]` → Descriptive pattern name
- `[Pattern description]` → What the pattern does
- `[functionName]` → Example function name
- `[params]` → Function parameters
- `[ParamType]` → Parameter type
- `[operation]` → Framework operation
- `[transform]` → Transform function
- `[Context]`, `[Layer]`, `[Effect]` → Framework concepts
- `[Client]` → Client/library name
- `[ServiceName]` → Service class name
- `[method1]`, `[method2]`, etc. → Service methods
- `[Type]`, `[Type1]`, etc. → Type names
- `[Error]`, `[ErrorType]` → Error types
- `[Schema]` → Schema library
- `[SchemaType]` → Schema type name
- `[generateId]`, `[DateTime]` → Utility functions
- `[insert]`, `[query]`, etc. → Client operations
- `[SYNTAX-KEYWORD]`, `[FUNCTION-NAME]` → Search patterns
- `[concept]` → Core concepts
- `[pattern-1]`, `[use-case-1]` → Pattern descriptions
- `[key-pattern-1]`, `[key-pattern-2]` → Keywords
- `[category]` → Doc category
- `[topic-1-keyword]`, etc. → Topic search terms
- `[import-pattern]` → Import syntax
- `[operation-keyword]` → Operation names
- `[wrong-code-example]`, `[correct-code-example]` → Code examples
- `[Reference Project]` → Reference codebase name
- `[path/to/services]`, etc. → File paths
- `[getting-started-keyword]` → Getting started search term

**Key sections to customize:**

1. **Patterns**: Add 3-5 core patterns for your technology + framework
2. **Cross-references**: Update grep patterns to match your docs skill
3. **Pitfalls**: Document common mistakes specific to your technology
4. **Production patterns**: Reference real codebases using this technology
5. **Next steps**: Link to docs skill and advanced skills

**Validation:**

1. Test all grep cross-references work (`rg` commands should return results)
2. Verify relative paths resolve (`../[tech]-docs/references/` exists)
3. Check skill is < 500 lines
4. Ensure patterns are complete and runnable
5. Validate all placeholders are replaced

**Best practices:**

- Keep patterns focused and practical
- Include both basic and advanced examples
- Show anti-patterns (❌ WRONG) alongside correct patterns (✅ CORRECT)
- Reference real production codebases
- Maintain bidirectional cross-links with docs skill
