Style Anchors Collection

Style Anchors Collection

Systematically identifies, documents, and organizes code examples that demonstrate approved patterns from technical requirements. Creates a structured library of style anchors used throughout implementation.

Prerequisites

• Completed technical-requirements.yaml
• Optional: Access to existing codebase or reference repositories

Purpose

Style anchors are concrete code examples that serve as templates for implementation. They prevent drift by:

• Establishing approved patterns before coding begins
• Providing specific file:line references instead of abstract descriptions
• Documenting when and how to use each pattern
• Creating a reusable pattern library for the project

Collection Process

Step 0: Determine Output Directory

If no directory was provided as a parameter, prompt the user:

"Where should I create the style anchors? (This should be the same base directory as your requirements documents)"

Wait for user response. Store the provided path as base_directory.

Step 1: Load Technical Context

1. Load {base_directory}/requirements/technical-requirements.yaml 2. Parse for key architecture patterns:

• Architecture pattern (monolithic, microservices, etc.)
• Technology stack (language, frameworks, libraries)
• Testing strategy (TDD, frameworks)
• Data model approach (database, schema patterns)
• API patterns (REST, GraphQL, etc.)
• Security patterns (auth, validation)

3. Identify pattern categories to collect anchors for (typical categories):

• Services - Service layer patterns with dependency injection
• Testing - Test structure, mocking, TDD patterns
• Validation - Input/output validation, schema validation
• API - Endpoint handlers, middleware, routing
• Data Access - Database queries, ORM patterns, migrations
• Error Handling - Error types, error propagation, recovery

Step 2: Present Collection Plan

Display identified categories to the user:

## Style Anchors Collection

Based on your technical requirements, I'll collect code examples for these pattern categories:

1. Services (Effect.Service pattern with dependency injection)
2. Testing (Effect service testing with @effect/vitest)
3. Validation (Schema.Class validation patterns)
4. Error Handling (Tagged errors with Effect)

For each category, I'll ask you to provide:
- File path to exemplar code
- Line range (e.g., 10-50)
- What the pattern demonstrates
- When to use it

You can provide examples from:
- Your current codebase
- A reference repository (will link to it)
- Suggest "none" to skip a category

Ask: "Ready to begin collection?"

Wait for confirmation.

Step 3: Interactive Collection

For each category identified:

3.1. Ask for source file:

## Category: [Category Name]

What file demonstrates your preferred [pattern description]?

Options:
1. Provide file path from current project (e.g., src/services/UserService.ts)
2. Provide URL to reference repository file
3. Type "none" to skip this category
4. Type "help" for guidance on what makes a good style anchor

Your answer:

3.2. Ask for line range:

What line range should I reference?

Format: Start-End (e.g., 10-50)
Or: Single line number (e.g., 25)
Or: "all" for entire file

Your answer:

3.3. If file is accessible, read and display:

## Code Preview

[Display the code from specified lines]

Does this look correct? (yes/no/adjust)

If "adjust", loop back to line range question.

3.4. Ask what pattern demonstrates:

What does this code example demonstrate?

Examples:
- "Service pattern with Effect.Service and dependency injection"
- "TDD test structure using it.effect from @effect/vitest"
- "Schema validation with proper error handling"

Your answer:

3.5. Ask when to use:

When should developers use this pattern?

Examples:
- "When creating any service class in the service layer"
- "When testing Effect-based services"
- "When validating external input data"

Your answer:

3.6. Generate anchor ID:

Create anchor ID from pattern name (kebab-case, e.g., service-pattern, test-effect-services)

3.7. Confirm and continue:

✓ Collected anchor: [anchor-name]

Continue to next category? (yes/no/review)

Step 4: Generate Outputs

4.1. Create directory structure:

mkdir -p {base_directory}/artifacts/style-anchors

4.2. Generate index.yaml:

Create {base_directory}/artifacts/style-anchors/index.yaml with:

• Version and metadata
• Categories with collected anchors
• Anchor definitions with source references
• Usage matrix mapping patterns to task types
• Total count and collection date

4.3. Generate individual .md files:

For each collected anchor, create {base_directory}/artifacts/style-anchors/[anchor-id].md with:

• YAML frontmatter (id, name, category, tags, created date)
• Overview section
• Source reference
• Code example (from file if accessible)
• What it demonstrates
• When to use
• Pattern requirements (derived from best practices)
• Common mistakes to avoid (derived from best practices)
• Related anchors (cross-references)

4.4. Populate pattern requirements and mistakes:

Use knowledge from implementation-plan-best-practices to add:

• ✓ Pattern Requirements: 3-7 must-do items specific to the pattern
• ❌ Common Mistakes: 3-7 anti-patterns to avoid

Step 5: Summary

Display collection summary:

## Style Anchors Collection Complete ✓

**Directory:** {base_directory}/artifacts/style-anchors/

**Collected Anchors:** [count]

📁 Categories:
  - Services: [n] anchors
  - Testing: [n] anchors
  - Validation: [n] anchors
  - Error Handling: [n] anchors

📄 Generated Files:
  ✓ index.yaml (master index with usage matrix)
  ✓ [anchor-1].md
  ✓ [anchor-2].md
  ✓ [anchor-3].md

These anchors will be automatically referenced by implementation-planner
when generating task instructions.

Next Step: Run /implementation-planner to generate milestones and tasks

Output Formats

index.yaml Structure

The master index file includes: version, project, generated, technical_requirements_ref, categories (each with id, name, description, anchors list), anchors (each with id, name, file, category, source reference, applies_to rules, tags), usage_matrix (mapping architecture patterns and task types to recommended anchors), and meta (counts and dates).

Individual Anchor .md Structure

Each anchor file includes: YAML frontmatter (id, name, category, tags, created), and sections for Overview, Source Reference, Code Example, What This Demonstrates, When to Use, Pattern Requirements, Common Mistakes to Avoid, Related Anchors, and Test Coverage.

See [references/output-spec.md](references/output-spec.md) for the complete specification of both index.yaml and individual anchor files, including all fields, formatting rules, and usage matrix structure.

See [references/example.md](references/example.md) for a full example anchor document.

Pattern Requirements and Mistakes Generation

For Service Patterns:

Requirements:

• ✓ All service methods MUST return Effect types
• ✓ Use Effect.gen for async operations
• ✓ Fail with tagged errors, not throw
• ✓ Validate inputs with Schema.decode before processing
• ✓ Declare all dependencies in dependencies array

Mistakes:

• ❌ Using async/await instead of Effect.gen
• ❌ Throwing errors instead of Effect.fail
• ❌ Direct database access without dependency injection
• ❌ Skipping input validation
• ❌ Using any or type assertions on external data

For Test Patterns:

Requirements:

• ✓ Use it.effect from @effect/vitest for Effect tests
• ✓ Provide all service dependencies in test setup
• ✓ Test both success and failure cases
• ✓ Use descriptive test names that explain behavior
• ✓ Follow TDD: write test first, then implementation

Mistakes:

• ❌ Using regular it() for Effect-based code
• ❌ Not providing required service dependencies
• ❌ Testing only happy path, ignoring errors
• ❌ Vague test names like "test 1" or "it works"
• ❌ Modifying tests to pass broken implementation

For Validation Patterns:

Requirements:

• ✓ Use Schema.Class for all data validation
• ✓ Validate at system boundaries (user input, external APIs)
• ✓ Return validation errors, don't throw
• ✓ Include helpful error messages
• ✓ Never use type assertions on external data

Mistakes:

• ❌ Using type assertions instead of validation
• ❌ Throwing generic errors instead of validation errors
• ❌ Validating internal function arguments (trust internal code)
• ❌ Skipping validation on external input
• ❌ Using any type for external data

For Error Handling Patterns:

Requirements:

• ✓ Use tagged errors (Effect.fail with custom error class)
• ✓ Include context in error objects (IDs, values)
• ✓ Propagate errors with Effect, don't catch and hide
• ✓ Define error types near where they're used
• ✓ Document expected errors in function signatures

Mistakes:

• ❌ Throwing errors instead of Effect.fail
• ❌ Using string error messages instead of typed errors
• ❌ Catching errors and ignoring them
• ❌ Generic error messages without context
• ❌ Not documenting what errors a function can produce

Usage Matrix Generation

Map technical requirements to anchor recommendations:

From architecture.pattern:

• effect-based-services → service-pattern, test-pattern, error-handling
• schema-validation → validation-schema, api-validation
• rest-api → api-pattern, validation-schema, error-handling

By task type:

• code → primary pattern for layer + validation + error-handling
• test → test-pattern + pattern being tested
• api → api-pattern + validation-schema + error-handling
• docs → (no anchors typically needed)
• config → (no anchors typically needed)

Best Practices

What Makes a Good Style Anchor

1. Concrete - Real file paths, not abstract descriptions 2. Specific - Line numbers for precision (20-50 lines ideal) 3. Complete - Shows full pattern, not just snippet 4. Current - Reflects current best practices 5. Exemplary - Demonstrates pattern correctly

Red Flags (When Collecting)

• Code example has TODOs or FIXMEs
• File uses deprecated patterns
• Code doesn't compile/run
• Example is too trivial (< 10 lines)
• Example is too complex (> 100 lines)
• No tests exist for the pattern

Edge Cases

No Existing Codebase

If user has no current codebase:

I notice you don't have an existing codebase. Would you like to:

1. Skip style anchor collection for now (can add later)
2. Reference external examples (Effect documentation, framework examples)
3. Create minimal example files as anchors

Which approach works best for your project?

User Skips All Categories

No style anchors collected. This means:

⚠️  Implementation-planner will generate tasks WITHOUT concrete examples
⚠️  Risk of architectural drift increases
⚠️  Developers will need to infer patterns from requirements

Recommendation: Collect at least 1-2 anchors for critical patterns
(e.g., service pattern, test pattern)

Continue without anchors? (yes/no)

File Not Accessible

If user provides file path that can't be read:

I can't access [file-path]. Would you like to:

1. Provide a different file path
2. Paste the code directly (I'll store it in the anchor)
3. Provide a URL to the file
4. Skip this anchor

Your choice:

Integration with Implementation Planner

When implementation-planner runs:

1. Load style anchors:

   Read {base_directory}/artifacts/style-anchors/index.yaml

2. For each task generated:

• Determine task type and file patterns
• Query usage_matrix for recommended anchors
• Filter anchors by applies_to rules
• Include top 2-3 relevant anchors in task instructions

3. Task instruction template:

   instructions: |
     ## Style Anchors
     Follow these patterns:
     - `[anchor-id]` ([file]) - [what it demonstrates]
     - `[anchor-id]` ([file]) - [what it demonstrates]

     See artifacts/style-anchors/[anchor-id].md for detailed examples.

     ## [rest of task instructions]

Validation

After generation, validate:

• [ ] index.yaml is valid YAML
• [ ] All anchor IDs are unique
• [ ] All category references resolve
• [ ] All .md files exist for anchors in index
• [ ] All .md frontmatter matches index.yaml
• [ ] Source line ranges are valid format
• [ ] Usage matrix references valid anchors
• [ ] At least 1 anchor per category

Usage

To collect style anchors:

/style-anchors-collection [base-directory]

If no directory is provided, auto-detect by looking for requirements/technical-requirements.yaml in the current directory.

If not found, prompt the user: "Where are your requirements documents located?"

Wait for the user to provide a path before proceeding. Store as base_directory.

The skill will:

1. Load technical requirements from {base_directory}/requirements/technical-requirements.yaml 2. Identify pattern categories to collect 3. Interactively collect anchors for each category 4. Generate index.yaml in {base_directory}/artifacts/style-anchors/ 5. Generate individual .md files for each anchor 6. Display collection summary

Examples

See [references/example.md](references/example.md) for a sample anchor document.

Effect.Service with Repository Pattern

Overview

Demonstrates the Effect.Service pattern with dependency injection for business logic services. Shows how to compose services with repositories, handle errors using Result types, and maintain type safety throughout the service layer. This is the standard pattern for all business logic in the codebase.

Source Reference

Repository: current-project File: src/services/account-service.ts Lines: 15-65

View in GitHub

Code Example

// src/services/account-service.ts:15-65
import { Effect, pipe } from "effect"
import { AccountRepository } from "../repositories/account-repository"
import { AccountNotFoundError, AccountValidationError } from "../errors"
import type { Account, AccountId, CreateAccountInput } from "../types"

export class AccountService extends Effect.Service<AccountService>()("AccountService", {
  effect: Effect.gen(function* () {
    const repo = yield* AccountRepository

    return {
      // Find account by ID with error handling
      findById: (id: AccountId) =>
        pipe(
          repo.findById(id),
          Effect.mapError((dbError) =>
            new AccountNotFoundError({
              accountId: id,
              cause: dbError
            })
          )
        ),

      // Create new account with validation
      create: (input: CreateAccountInput) =>
        pipe(
          validateAccountInput(input),
          Effect.flatMap((validated) => repo.create(validated)),
          Effect.mapError((error) =>
            error._tag === "ValidationError"
              ? new AccountValidationError({ input, cause: error })
              : error
          )
        ),

      // List accounts with pagination
      list: (page: number = 1, pageSize: number = 50) =>
        pipe(
          repo.list({ offset: (page - 1) * pageSize, limit: pageSize }),
          Effect.map((accounts) => ({
            accounts,
            page,
            pageSize,
            hasMore: accounts.length === pageSize
          }))
        ),

      // Update account with optimistic locking
      update: (id: AccountId, updates: Partial<Account>) =>
        pipe(
          repo.findById(id),
          Effect.flatMap((existing) =>
            pipe(
              validateAccountInput({ ...existing, ...updates }),
              Effect.flatMap((validated) => repo.update(id, validated))
            )
          ),
          Effect.mapError((error) =>
            error._tag === "NotFound"
              ? new AccountNotFoundError({ accountId: id, cause: error })
              : new AccountValidationError({ input: updates, cause: error })
          )
        )
    }
  }),
  dependencies: [AccountRepository.Default]
}) {}

// Helper for input validation
const validateAccountInput = (input: CreateAccountInput) =>
  Effect.try({
    try: () => AccountSchema.parse(input),
    catch: (error) => new ValidationError({ message: "Invalid account data", cause: error })
  })

What This Demonstrates

• Effect.Service pattern - Class-based service with dependency injection
• Generator-based composition - Using Effect.gen for readable async logic
• Repository dependency - Injecting repository through Effect's dependency system
• Error mapping - Converting repository errors to domain errors
• Type safety - Full TypeScript typing throughout the pipeline
• Result types - Using Effect for error handling instead of try/catch
• Service methods - Multiple related operations grouped in one service
• Validation integration - Schema validation integrated with error handling
• Pagination pattern - Offset/limit pagination with hasMore indicator

When to Use

• Business logic services - Any service containing domain logic
• Multi-step operations - Operations requiring multiple repository calls
• Error transformation - When repository errors need domain context
• Composable operations - Operations that combine multiple effects
• Dependency injection - Services that depend on repositories or other services
• Type-safe pipelines - When maintaining types through transformation chains

Pattern Requirements

✓ Extend Effect.Service<T>() with unique service name ✓ Use Effect.gen for service implementation (not raw promises) ✓ Inject dependencies through dependencies array ✓ Return service methods as Effect types (not raw Promises) ✓ Map repository errors to domain-specific errors ✓ Use pipe for transformation chains (not method chaining) ✓ Validate inputs before passing to repository ✓ Type all inputs and outputs explicitly ✓ Group related operations in single service class

Common Mistakes to Avoid

❌ Using async/await instead of Effect.gen - breaks Effect composition ❌ Returning Promises instead of Effects from service methods ❌ Not mapping errors - letting repository errors leak to API layer ❌ Injecting services via constructor - use Effect dependencies instead ❌ Mixing Effect and Promise - choose one approach consistently ❌ Forgetting to yield dependencies - causes "cannot read property" errors ❌ Using try/catch - use Effect.try or Effect.tryPromise instead ❌ Creating new service instances - services are singletons via dependency system ❌ Not validating inputs - repository should receive validated data only

Related Anchors

• SA-002 - Repository with SQL Query Builder (data access layer)
• SA-004 - Effect.Service Testing with Mocks (testing this pattern)
• SA-015 - Error Handling with Result Types (error mapping strategies)
• SA-023 - Schema Validation with Zod (input validation approach)

Test Coverage

See SA-004 for comprehensive testing patterns for Effect.Service implementations, including mocking dependencies and testing error scenarios.

Additional Notes

• Effect version: Requires Effect 3.0+ for latest Service API
• Performance: Effect.gen has minimal overhead compared to raw Effects
• Migration: When converting from Promise-based services, replace async/await with Effect.gen and yield*
• Debugging: Use Effect.tapError to log errors without changing flow
• Transactions: Wrap multiple repository calls in Effect.gen for transaction-like semantics
• Caching: Consider SA-031 for adding caching layer to services

Style Anchor Document Specification

Document Type: Individual style anchor markdown file Version: 1.0.0 Generated By: style-anchors-collection skill Purpose: Documents a specific code pattern with unique identifier, example code, usage guidelines, and anti-patterns. Style anchors are referenced by code (SA-001, SA-002, etc.) in implementation plans.

---

Document Structure

File Naming Convention

Format: SA-{NNN}-{slug}.md

Rules:

• {NNN}: Zero-padded sequential number (001, 002, 042, 123)
• {slug}: Kebab-case descriptive name matching pattern
• Examples:
• SA-001-service-pattern.md
• SA-042-trpc-router-validation.md
• SA-123-effect-service-testing.md

Validation:

• Code must be unique across all style anchors
• Slug should be 2-5 words, lowercase, hyphen-separated
• Filename must match code field in frontmatter

File Location

{base_directory}/artifacts/style-anchors/SA-{NNN}-{slug}.md

Directory Structure:

artifacts/
└── style-anchors/
    ├── index.yaml              # Master index
    ├── SA-001-service-pattern.md
    ├── SA-002-repository-pattern.md
    ├── SA-003-trpc-router.md
    └── SA-004-service-testing.md

---

YAML Frontmatter

---
code: string                   # Unique identifier (required, format: SA-NNN)
name: string                   # Display name (required)
category: string               # Category ID from index.yaml (required)
tags: array<string>            # Search/filter tags (required, min: 1)
created: string                # YYYY-MM-DD format (required)
updated: string                # YYYY-MM-DD format (optional)
---

Field Descriptions:

• code: Unique identifier matching filename (e.g., "SA-001")
• name: Human-readable pattern name (e.g., "Effect.Service with Repository Pattern")
• category: Category ID from index.yaml (e.g., "services", "testing", "api")
• tags: Lowercase kebab-case tags (e.g., ["effect", "service", "repository", "dependency-injection"])
• created: Date anchor was created
• updated: Last modification date (omit if never updated)

Validation Rules:

• code: Must match pattern SA-\d{3} (e.g., SA-001, SA-042)
• code: Must match filename prefix
• code: Must be unique across all style anchors
• name: 10-100 characters
• category: Must reference valid category in index.yaml
• tags: 1-10 tags, each 2-30 characters, lowercase, kebab-case
• created: Valid YYYY-MM-DD date
• updated: If present, must be >= created

---

Markdown Content Structure

Required Sections

# [Name]

## Overview
[2-3 sentence description of what this pattern demonstrates]

## Source Reference
**Repository:** [current-project | external-url]
**File:** `[path/to/file.ext]`
**Lines:** [N-M | N]

[Optional: Link to source if available]

## Code Example

// [file:lines] or [description] [Actual code snippet - typically 20-50 lines]

[Optional: Additional code examples for variations]

## What This Demonstrates
[Bulleted list of key concepts shown in the code]
- [Concept 1 - what the pattern shows]
- [Concept 2 - architectural principle]
- [Concept 3 - best practice demonstrated]

## When to Use
[Clear guidance on when this pattern applies]
- [Use case 1 - specific scenario]
- [Use case 2 - file pattern or milestone type]
- [Use case 3 - architectural context]

## Pattern Requirements
[Mandatory rules when using this pattern]
✓ [Requirement 1 - must-follow rule]
✓ [Requirement 2 - mandatory approach]
✓ [Requirement 3 - required practice]

## Common Mistakes to Avoid
[Anti-patterns and pitfalls]
❌ [Mistake 1 - what not to do]
❌ [Mistake 2 - common error]
❌ [Mistake 3 - anti-pattern to avoid]

Optional Sections

## Related Anchors
[Cross-references to complementary patterns]
- **SA-002** - [Brief description of relationship]
- **SA-015** - [How patterns complement each other]

## Test Coverage
[Reference to corresponding test pattern]
See **SA-042** for testing this pattern.

## Additional Notes
[Edge cases, performance notes, version-specific guidance]
- [Note about edge case]
- [Performance consideration]
- [Version compatibility note]

---

Field Type Reference

---

Validation Summary

Required Elements

• ✓ YAML frontmatter with all required fields
• ✓ # [Name] heading matching frontmatter
• ✓ ## Overview
• ✓ ## Source Reference
• ✓ ## Code Example with language identifier
• ✓ ## What This Demonstrates
• ✓ ## When to Use
• ✓ ## Pattern Requirements (3-7 items with ✓)
• ✓ ## Common Mistakes to Avoid (3-7 items with ❌)

Optional Elements

• ## Related Anchors (cross-references)
• ## Test Coverage (testing pattern reference)
• ## Additional Notes (edge cases, performance)

Content Constraints

• Overview: 2-3 sentences, concise summary
• Code Example: 20-50 lines typical (longer if justified)
• Language identifier required in code fence
• Pattern Requirements: 3-7 checkmarked items
• Common Mistakes: 3-7 cross-marked items
• Use ✓ for requirements, ❌ for mistakes consistently

Quality Gates

1. Code uniquely identifies this anchor (SA-001 never reused) 2. Frontmatter matches filename and index.yaml entry 3. Code example is clear, complete, and runnable 4. Requirements are actionable and specific 5. Mistakes are concrete anti-patterns 6. Cross-references use anchor codes (not names)

---

Integration with Other Documents

Input Documents

• technical-requirements.yaml → Determines which patterns to collect
• Existing codebase → Source of exemplar code

Output Documents

• style-anchors/index.yaml → Master index referencing this anchor by code
• milestones.yaml → Optional global anchor references
• milestone-m*.tasks.yaml → Task-level anchor references

Workflow Position

technical-requirements.yaml → style-anchors-collection skill
                                          ↓
                              style-anchors/index.yaml + SA-*.md files
                                          ↓
                              implementation-planner (references by code)
                                          ↓
                              milestones.yaml (style_anchors: [SA-001, SA-003])
                                          ↓
                              milestone-m*.tasks.yaml (per-task references)

---

Code Assignment Strategy

Sequential Numbering

• Codes assigned sequentially: SA-001, SA-002, SA-003, ...
• Never reuse codes (even if anchor deleted)
• Gaps in sequence are acceptable

Category Grouping (Optional)

Optionally group codes by category for organization:

• SA-001 to SA-019: Services patterns
• SA-020 to SA-039: Testing patterns
• SA-040 to SA-059: API patterns
• SA-060 to SA-079: Data access patterns
• SA-080 to SA-099: Configuration patterns

Code Reservations

Reserve code ranges for future use:

• SA-900+: Reserved for project-specific patterns
• SA-990+: Reserved for deprecated/archived patterns

---

Usage in Implementation Plans

In milestones.yaml

style_anchors:
  - SA-001  # Effect.Service with Repository pattern
  - SA-003  # TRPC router with Zod validation
  - SA-015  # Error handling with Result types

In milestone-m*.tasks.yaml

tasks:
  - id: t1
    title: Implement ActivityService
    description: |
      Create service following SA-001 pattern.
    style_anchor_refs:
      - SA-001  # Service pattern
      - SA-015  # Error handling

In Task Instructions

Follow **SA-001** (Effect.Service with Repository pattern) for service structure.
Implement error handling per **SA-015**.

---

CLI Tool Support

Validation Command

sherpy validate style-anchors/SA-001-service-pattern.md

Checks:

• Frontmatter matches filename
• Code format valid (SA-\d{3})
• Code unique across all anchors
• All required sections present
• Code examples have language identifiers
• Cross-references valid anchor codes

Listing Command

sherpy list style-anchors
sherpy list style-anchors --category services
sherpy list style-anchors --tag effect

Output:

SA-001: Effect.Service with Repository Pattern [services]
SA-002: Repository with SQL Query Builder [data-access]
SA-003: TRPC Router with Zod Validation [api]
SA-004: Effect.Service Testing with Mocks [testing]

Reference Check Command

sherpy check-refs milestones.yaml

Checks:

• All referenced anchor codes exist
• No dangling references
• Anchors match milestone context

---

Best Practices

Writing Effective Anchors

DO:

• Use real production code as examples (not contrived)
• Show complete, runnable code snippets
• Make requirements actionable and specific
• Document concrete mistakes, not vague warnings
• Cross-reference related patterns

DON'T:

• Create anchors for trivial patterns (e.g., "how to import")
• Use incomplete or pseudo-code examples
• Write vague requirements ("code should be good")
• Skip common mistakes section
• Over-explain obvious code

Code Example Quality

Good Example:

// SA-001: Effect.Service with Repository pattern
export class AccountService extends Effect.Service<AccountService>()("AccountService", {
  effect: Effect.gen(function* () {
    const repo = yield* AccountRepository

    return {
      findById: (id: string) =>
        pipe(
          repo.findById(id),
          Effect.mapError(toAccountNotFoundError)
        )
    }
  }),
  dependencies: [AccountRepository.Default]
}) {}

Bad Example:

// Too generic, not showing pattern clearly
class Service {
  // ... implementation
}

Common Pitfalls

1. Vague Code References

• ❌ "See the account service"
• ✓ "Repository: current-project, File: src/services/account-service.ts, Lines: 15-45"

2. Missing Anti-Patterns

• ❌ Only showing what to do
• ✓ Documenting what NOT to do with ❌ markers

3. Inconsistent Formatting

• ❌ Mix of bullet styles, inconsistent emoji
• ✓ Always ✓ for requirements, ❌ for mistakes

4. Broken Cross-References

• ❌ "See the service testing anchor"
• ✓ "See SA-004 for testing this pattern"

5. Outdated Examples

• ❌ Code using deprecated APIs
• ✓ Update anchor when patterns evolve, increment updated date

---

Example Style Anchor

See example.md for a complete, realistic style anchor document.

---

Schema Version History

• 1.0.0 (2026-04-15): Initial specification
• Code-based identification system (SA-001, SA-002, etc.)
• Structured frontmatter with code, name, category, tags
• Required and optional markdown sections
• Integration with milestones and tasks via code references
• Validation rules and quality gates

---

Related Specifications

• style-anchors/index.yaml specification - Master index of all anchors
• milestones.yaml specification - References anchors by code
• milestone-m*.tasks.yaml specification - Task-level anchor references
• technical-requirements.yaml specification - Source of pattern needs