Create Architecture Decision Records (ADRs) following LCA conventions. INVOKE THIS SKILL when user: - Asks to "document a decision" or "record a decision" - Mentions "ADR", "decision record", or "architectural decision" - Wants to capture trade-offs or options considered - Needs to supersede or update an existing decision - Asks about decision history or rationale Trigger keywords: ADR, decision record, architectural decision, trade-offs, options, rationale
/plugin marketplace add rayk/lucid-toolkit/plugin install architect@lucid-toolkitThis skill is limited to using the following tools:
<quick_start> <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]
[Describe the context and problem. What forces are at play? Why is this decision needed now?]
Chosen option: "[Option N]" because [justification].
Positive:
Negative:
Neutral:
[etc.]
</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
# 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 |
<success_criteria> An ADR is complete when:
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.