chore: add shared skills catalog (19 skills), installers, manifest, validator
This commit is contained in:
51
skills/documentation-and-adrs/SKILL.md
Normal file
51
skills/documentation-and-adrs/SKILL.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: documentation-and-adrs
|
||||
description: Use when documenting architectural decisions, drafting ADRs (Architecture Decision Records), or writing technical specifications and system documentation.
|
||||
---
|
||||
|
||||
# Architecture Decision Records (ADRs) & Technical Documentation
|
||||
|
||||
## Purpose
|
||||
Produce concise, actionable, and structured architectural documentation and ADRs that capture the context, options considered, and tradeoffs made.
|
||||
|
||||
## ADR Standard Structure (MADR Format)
|
||||
|
||||
```markdown
|
||||
# [Short title of solved problem and decision]
|
||||
|
||||
* **Status:** proposed | accepted | rejected | deprecated | superseded
|
||||
* **Deciders:** [List of stakeholders/engineers]
|
||||
* **Date:** YYYY-MM-DD
|
||||
|
||||
## Context and Problem Statement
|
||||
What problem are we solving? What are the constraints, requirements, and background context?
|
||||
|
||||
## Decision Drivers
|
||||
* Driver 1 (e.g. performance under 50ms latency)
|
||||
* Driver 2 (e.g. zero external infrastructure dependencies)
|
||||
* Driver 3 (e.g. strict backwards compatibility)
|
||||
|
||||
## Considered Options
|
||||
1. Option A — [Short description]
|
||||
2. Option B — [Short description]
|
||||
3. Option C — [Short description]
|
||||
|
||||
## Decision Outcome
|
||||
Chosen option: "Option A", because [justification linking to drivers].
|
||||
|
||||
### Positive Consequences
|
||||
* Clear benefit 1
|
||||
* Clear benefit 2
|
||||
|
||||
### Negative Consequences / Tradeoffs
|
||||
* Accepted limitation 1
|
||||
* Migration cost or operational overhead
|
||||
|
||||
## Pros and Cons of Options
|
||||
[Brief comparison table or bullet breakdown]
|
||||
```
|
||||
|
||||
## Documentation Principles
|
||||
1. **One Home per Fact:** Do not duplicate invariants across multiple files.
|
||||
2. **Focus on "Why" and "Tradeoffs":** Code shows *how*; documentation must explain *why* this choice was made over alternatives.
|
||||
3. **No Fluff / Slop:** Direct, concise language. Omit generic platitudes.
|
||||
Reference in New Issue
Block a user