compliance

What this skill does

# Compliance Documentation Setup

Sets up Architecture Decision Records (ADRs), operational runbooks, and project compliance documentation with structured templates and best practices.

## What Gets Created

### Documentation Structure

1. **`docs/adr/`** - Architecture Decision Records directory
2. **`docs/adr/000-template.md`** - ADR template for new decisions
3. **`docs/adr/README.md`** - ADR index and guidelines
4. **`docs/runbook.md`** - Operational runbook with incident playbooks
5. **`docs/CONTRIBUTING.md`** - Contributing guidelines

### CLI Scripts

6. **`scripts/docs/new-adr.ts`** - Interactive ADR creation script
7. **`scripts/docs/list-adrs.ts`** - List all ADRs with status

## Quick Start

```bash
# Create a new ADR interactively
bun run scripts/docs/new-adr.ts

# List all ADRs
bun run scripts/docs/list-adrs.ts
```

## File Structure

```
docs/
├── adr/
│   ├── README.md                           # Index and guidelines
│   ├── 000-template.md                     # ADR template
│   ├── 001-meilisearch-over-algolia.md     # Example ADR
│   └── 002-better-auth-over-nextauth.md    # Example ADR
├── runbook.md                              # Operational runbook
└── CONTRIBUTING.md                         # Contributing guidelines

scripts/
└── docs/
    ├── new-adr.ts                          # Create new ADR
    └── list-adrs.ts                        # List ADRs
```

## ADR Template

### File: `docs/adr/000-template.md`

```markdown
# ADR [NUMBER]: [TITLE]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context

[What is the issue that we're seeing that is motivating this decision or change?]

## Decision

[What is the change that we're proposing and/or doing?]

## Rationale

### [Chosen Option] Advantages

1. [Advantage 1]
2. [Advantage 2]
3. [Advantage 3]

### [Alternative Option] Advantages (not chosen)

1. [Advantage 1]
2. [Advantage 2]
3. [Advantage 3]

### Why [Chosen Option] Wins

[Explanation of why the chosen option is better for this use case]

## Consequences

### Positive

- [Positive consequence 1]
- [Positive consequence 2]

### Negative

- [Negative consequence 1]
- [Negative consequence 2]

### Mitigations

- [How to address negative consequence 1]
- [How to address negative consequence 2]

## References

- [Link to relevant documentation]
- [Link to related ADRs]
```

## ADR Index

### File: `docs/adr/README.md`

```markdown
# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for this project.

## What is an ADR?

An Architecture Decision Record captures an important architectural decision made along with its context and consequences. ADRs help teams:

- **Document decisions** before they're forgotten
- **Communicate** the reasoning to new team members
- **Revisit** decisions when context changes
- **Learn** from past decisions

## ADR Status

| Status | Meaning |
|--------|---------|
| Proposed | Under discussion, not yet decided |
| Accepted | Decision has been made and is active |
| Deprecated | No longer relevant or recommended |
| Superseded | Replaced by a newer ADR |

## Index

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [001](001-meilisearch-over-algolia.md) | Meilisearch over Algolia | Accepted | 2026-01-11 |
| [002](002-better-auth-over-nextauth.md) | Better Auth over NextAuth | Accepted | 2026-01-11 |

## Creating a New ADR

1. Copy `000-template.md` to `NNN-short-title.md`
2. Fill in the template sections
3. Submit for team review
4. Update this index when accepted

Or use the CLI:

\`\`\`bash
bun run scripts/docs/new-adr.ts
\`\`\`

## Guidelines

1. **One decision per ADR** - Keep them focused
2. **Use past tense** - "We decided" not "We will decide"
3. **Be honest about trade-offs** - Document both pros and cons
4. **Link related ADRs** - Build a knowledge graph
5. **Update status** - Mark deprecated/superseded as needed
```

## Example ADRs

### File: `docs/adr/001-meilisearch-over-algolia.md`

```markdown
# ADR 001: Meilisearch over Algolia for Search

## Status

Accepted

## Context

We need a search solution for the digital store that supports:
- Full-text search with typo tolerance
- Faceted filtering
- Fast response times (<100ms)
- Self-hosted option for local development
- Reasonable cost at scale

## Decision

We will use Meilisearch instead of Algolia.

## Rationale

### Meilisearch Advantages

1. **Self-hosted option**: Docker container for local dev matches production behavior
2. **Cost**: Open-source, pay only for hosting vs. per-search pricing
3. **Performance**: Sub-50ms searches out of the box
4. **Simplicity**: Single binary, minimal configuration
5. **API compatibility**: REST API similar to Algolia, easy migration path

### Algolia Advantages (not chosen)

1. More mature, larger ecosystem
2. Built-in analytics
3. Global CDN infrastructure
4. Better for very large datasets (100M+ records)

### Why Meilisearch Wins

For our use case (<1M products, cost-sensitive, need local dev parity), Meilisearch provides better value. The self-hosted option eliminates vendor lock-in and allows identical local/production environments.

## Consequences

### Positive

- Lower operational costs
- Better local development experience
- No vendor lock-in

### Negative

- Self-managed infrastructure in production
- Less built-in analytics (using Langfuse instead)
- Smaller community than Algolia

### Mitigations

- Use Meilisearch Cloud for production to reduce ops burden
- Implement custom analytics via Langfuse
- Active community and growing ecosystem
```

### File: `docs/adr/002-better-auth-over-nextauth.md`

```markdown
# ADR 002: Better Auth over NextAuth for Authentication

## Status

Accepted

## Context

We need authentication for the digital store supporting:
- Email/password authentication
- Social providers (Google, GitHub, Discord)
- Session management
- Database-backed sessions
- TypeScript-first experience

## Decision

We will use Better Auth with better-auth-harmony instead of NextAuth (Auth.js).

## Rationale

### Better Auth Advantages

1. **TypeScript-first**: Full type safety without workarounds
2. **Simplicity**: Less configuration, more sensible defaults
3. **Plugin ecosystem**: better-auth-harmony adds multi-session support
4. **Better Auth UI**: Pre-built shadcn/ui components
5. **Database flexibility**: Works seamlessly with Drizzle ORM

### NextAuth Advantages (not chosen)

1. Larger community and more examples
2. More OAuth provider adapters
3. Longer track record

### Why Better Auth Wins

Better Auth's TypeScript experience and plugin system (particularly better-auth-harmony) provide a more cohesive developer experience. The Better Auth UI package eliminates the need to build auth forms from scratch while maintaining full customization.

## Consequences

### Positive

- Faster development with pre-built UI
- Better TypeScript support
- Cleaner session management

### Negative

- Smaller community
- Fewer OAuth provider adapters (can be added)
- Less documentation/examples

### Mitigations

- Core providers (Google, GitHub, Discord) are supported
- Growing community and documentation
- better-auth-harmony fills gaps in core functionality
```

## Contributing Guidelines

### File: `docs/CONTRIBUTING.md`

```markdown
# Contributing Guidelines

Thank you for your interest in contributing to this project!

## Getting Started

1. Fork the repository
2. Clone your fork locally
3. Install dependencies: `bun install`
4. Create a feature branch: `git checkout -b feature/your-feature`

## Development Workflow

1. **Write code** following the project's coding standards
2. **Write tests** for new functionality
3. **Run checks** before committing:
   ```bash
   bun run lint
   bun run build
   ```
4. **Commit** with a clear message following [Conventional Commits](https://www.conventionalcommits.org/)
5. **Push** and open a Pull Request

## Commit Message Format

```
type(scope): description

[optional body]