# Rayk Lucid Toolkit Create Adr

> <objective>

- Skill: `tomevault-io/rayk-lucid-toolkit-create-adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/rayk-lucid-toolkit-create-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rayk-lucid-toolkit-create-adr/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/rayk-lucid-toolkit-create-adr

---


<objective>
Guide creation of Architecture Decision Records that capture the "why" behind architectural choices. ADRs are append-only documents that preserve decision history, enabling future maintainers to understand context and trade-offs.
</objective>

<quick_start>
<workflow>
1. **Identify decision scope**: What architectural choice needs documentation?
2. **Gather context**: Why is this decision being made now? What drivers exist?
3. **Document options**: What alternatives were considered?
4. **Analyze trade-offs**: Explicit positive, negative, neutral consequences
5. **Record decision**: Write ADR with proper numbering and status
6. **Link to architecture docs**: Reference from relevant ARCHITECTURE.md
</workflow>

<naming_convention>
```
adr-NNN-{slug}.md

Examples:
adr-001-use-protocol-buffers.md
adr-002-adopt-event-sourcing.md
adr-003-schema-org-boundaries.md
```

Numbers are sequential and never reused. Superseded ADRs keep their number.
</naming_convention>

<template>
```markdown
# ADR-NNN: {Title}

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date**: YYYY-MM-DD
**Deciders**: [list of people involved]
**Technical Story**: [ticket/issue reference if applicable]

## Context and Problem Statement

[Describe the context and problem. What forces are at play? Why is this decision needed now?]

## Decision Drivers

* [Driver 1: e.g., Performance requirements]
* [Driver 2: e.g., Team expertise]
* [Driver 3: e.g., Maintenance burden]

## Considered Options

1. [Option 1]
2. [Option 2]
3. [Option 3]

## Decision Outcome

**Chosen option**: "[Option N]" because [justification].

### Consequences

**Positive:**
* [Benefit 1]
* [Benefit 2]

**Negative:**
* [Drawback 1]
* [Drawback 2]

**Neutral:**
* [Side effect that is neither good nor bad]

## Pros and Cons of Options

### Option 1: [Name]

* Good, because [argument]
* Good, because [argument]
* Bad, because [argument]

### Option 2: [Name]

* Good, because [argument]
* Bad, because [argument]
* Bad, because [argument]

### Option 3: [Name]

[etc.]

## Links

* [Link to related ADRs]
* [Link to architecture documentation]
* [Link to external references]
```
</template>
</quick_start>

<adr_lifecycle>
<statuses>
| Status | Meaning | Action |
|--------|---------|--------|
| Proposed | Under discussion | Gather feedback, refine options |
| Accepted | Decision made | Implement, update architecture docs |
| Deprecated | No longer relevant | Document why, keep for history |
| Superseded | Replaced by newer ADR | Link to superseding ADR |
</statuses>

<append_only_rule>
ADRs are **never deleted or modified** after acceptance. They are historical records.

**To change a decision**:
1. Create new ADR with next number
2. Reference original: "Supersedes ADR-NNN"
3. Update original status: "Superseded by ADR-XXX"

This preserves the decision trail and reasoning evolution.
</append_only_rule>

<numbering>
- Start at 001
- Always 3 digits with leading zeros
- Sequential, never skip numbers
- Superseded ADRs keep their original number
</numbering>
</adr_lifecycle>

<decision_drivers>
<common_drivers>
When gathering context, consider these common architectural drivers:

**Technical**:
- Performance requirements (latency, throughput)
- Scalability needs (horizontal, vertical)
- Reliability requirements (uptime, fault tolerance)
- Security constraints (compliance, data protection)

**Organizational**:
- Team expertise and capacity
- Time-to-market pressure
- Budget constraints
- Existing technology investments

**Operational**:
- Maintenance burden
- Monitoring and observability
- Deployment complexity
- Rollback capabilities

**Strategic**:
- Vendor lock-in considerations
- Future flexibility needs
- Integration requirements
- Standards compliance
</common_drivers>

<elicitation>
Ask these questions to surface drivers:

1. "What problem is this decision solving?"
2. "What happens if we don't make this decision?"
3. "What constraints are non-negotiable?"
4. "Who will be affected by this decision?"
5. "How long do we expect this decision to remain valid?"
</elicitation>
</decision_drivers>

<trade_off_analysis>
<explicit_consequences>
LCA mandates explicit trade-offs—never assume decisions are purely positive.

**Positive consequences**: What improves? What becomes easier?
**Negative consequences**: What gets harder? What new problems emerge?
**Neutral consequences**: What changes without clear good/bad valence?
</explicit_consequences>

<analysis_framework>
For each option, evaluate against:

| Criterion | Weight | Option 1 | Option 2 | Option 3 |
|-----------|--------|----------|----------|----------|
| Performance | High | ++ | + | - |
| Maintainability | Medium | + | ++ | + |
| Team familiarity | Low | - | + | ++ |
| Migration effort | Medium | -- | + | + |

Use: `++` (strong positive), `+` (positive), `0` (neutral), `-` (negative), `--` (strong negative)
</analysis_framework>

<hidden_costs>
Surface hidden costs explicitly:

- **Learning curve**: Time for team to become proficient
- **Migration path**: Effort to move from current state
- **Operational overhead**: Ongoing maintenance burden
- **Technical debt**: Future refactoring this creates
- **Lock-in**: Difficulty switching away later
</hidden_costs>
</trade_off_analysis>

<lca_specific_adrs>
<common_decisions>
Architecture decisions frequently needed in LCA systems:

**Boundary Decisions**:
- "Where should the Conduit boundary be?"
- "What Protocol Buffer version to use?"
- "How to version the API?"

**Composition Decisions**:
- "How to decompose this into Atoms?"
- "What should the Composite orchestrate?"
- "Where does this logic belong?"

**Data Strategy Decisions**:
- "What Schema.org types at boundaries?"
- "How to model this internally?"
- "Where is the mapping layer?"

**Performance Tunnel Decisions**:
- "Is this bottleneck proven by profiling?"
- "What optimization approach?"
- "How to encapsulate complexity?"
</common_decisions>

<example_adr>
```markdown
# ADR-005: Use Schema.org/Product at API Boundary

**Status**: Accepted
**Date**: 2025-01-15
**Deciders**: Architecture team

## Context and Problem Statement

Our product catalog API needs to be consumable by AI agents and third-party
integrations. We need a data format that is self-describing and follows
industry standards.

## Decision Drivers

* AI agents need to understand our data semantically
* Third-party integrations should work without custom documentation
* Internal models need to remain optimized for computation

## Considered Options

1. Custom JSON schema with documentation
2. Schema.org/Product with JSON-LD serialization
3. GraphQL with custom types

## Decision Outcome

**Chosen option**: "Schema.org/Product with JSON-LD serialization" because
it provides semantic interoperability for AI consumers while following
established web standards.

### Consequences

**Positive:**
* AI agents can parse and understand our data without training
* Follows LCA principle of Schema.org at boundaries
* SEO benefits from structured data

**Negative:**
* Schema.org types are verbose compared to internal models
* Mapping layer adds complexity
* Some product attributes don't map cleanly

**Neutral:**
* Team needs to learn JSON-LD serialization

## Links

* Relates to ARCHITECTURE.md#data-strategy
* Schema.org Product: https://schema.org/Product
```
</example_adr>
</lca_specific_adrs>

<directory_structure>
<placement>
ADRs live in a dedicated directory at the architecture level they affect:

```
project/
├── ARCHITECTURE.md
├── adr/
│   ├── adr-001-initial-architecture.md
│   ├── adr-002-use-protocol-buffers.md
│   └── adr-003-schema-org-boundaries.md
└── services/
    └── order-service/
        ├── architecture.md
        └── adr/
            └── adr-001-caching-strategy.md
```
</placement>

<index>
Maintain an index file for discoverability:

```markdown
# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [001](adr-001-initial-architecture.md) | Initial Architecture | Accepted | 2025-01-01 |
| [002](adr-002-use-protocol-buffers.md) | Use Protocol Buffers | Accepted | 2025-01-05 |
| [003](adr-003-schema-org-boundaries.md) | Schema.org at Boundaries | Accepted | 2025-01-15 |
```
</index>
</directory_structure>

<validation>
<checklist>
Before marking ADR Accepted:

- [ ] Clear problem statement (why now?)
- [ ] Decision drivers listed with rationale
- [ ] At least 2 options considered
- [ ] Chosen option clearly stated with justification
- [ ] Positive consequences documented
- [ ] Negative consequences documented (mandatory—no free lunches)
- [ ] Neutral consequences considered
- [ ] Links to related architecture docs
- [ ] Proper numbering (adr-NNN format)
- [ ] Date and deciders recorded
</checklist>
</validation>

<success_criteria>
An ADR is complete when:

- A future reader can understand WHY the decision was made
- Trade-offs are explicit, not hidden
- Alternative options are documented for historical context
- Links connect to relevant architecture documentation
- Status accurately reflects decision state
</success_criteria>

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/rayk) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->