skills/magnus919_agent-skills
1
0
Fork 0
mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

fix(skills): prioritize practical decisions and repository ADR conventions (#473)

Browse Source 
* fix(skills): prioritize practical decisions and repository ADR conventions

* fix(adr-authoring): align fallback template guidance
This commit is contained in:
Magnus Hedemark
2026-09-05 20:40:29 -04:00
committed by GitHub
parent 2a458aba10
commit d8f35542ab
9 changed files with 175 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adr-authoring/README.md
+5 -6
View File
@@ -4,23 +4,22 @@ Preserve the reasoning behind consequential architecture choices so later contri
## Why Install This Skill
Preserve the reasoning behind consequential architecture choices so later contributors can understand, revisit, or supersede them responsibly. It preserves a practical method, local reference material, and reusable templates so an agent can do more than produce a generic answer.
Architecture decisions are hard to revisit when records hide the rejected alternatives or confuse approval with delivery. This skill captures the reasoning, costs, and scope so future contributors can understand what was actually decided.
Use it when the work needs a repeatable process and an inspectable result. It is portable across Agent Skills-compatible clients and does not require a profile system or a particular task orchestrator.
It follows your repository's existing template, folder layout, and amendment policy. Proposals, approved experiments, production decisions, and implementation evidence remain distinct, with links to the checks that support each claim.
## What You Get
| Path | What it provides |
|---|---|
| `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. |
| `SKILL.md` | Repository conventions, decision scope, lifecycle, and evidence rules. |
| `evals/` | Cases covering local conventions, experiment approval, lifecycle, and evidence quality. |
| `references/` | Reference material for ADR formats, lifecycle, sustainability, fitness-function design, and provenance. |
| `templates/fitness-function-record.md` | Fillable record connecting an ADR decision to a check and observed evidence. |
## Quick Start
Read `SKILL.md` for the decision workflow, then start from `references/adr-format.md`. When a decision needs ongoing confirmation, use `templates/fitness-function-record.md` with `references/fitness-functions.md`.
Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.
Ask: “Draft an ADR for this decision using our repository conventions. Separate the approved scope from implementation evidence.” The result follows your existing decision log and identifies any unresolved approval or validation gaps.
## Triggers
adr-authoring/SKILL.md
+30 -52
View File
@@ -13,65 +13,35 @@ metadata:
Architecture Decision Records for capturing design rationale. ADRs supply the temporal dimension — decisions over time — that structure-only views (C4) miss.
## ADR-to-Pyramid Mapping
## Start with Repository Conventions
| ADR State | Pyramid Layer | Path |
|-----------|--------------|------|
| Navigation index | L1 (Summary) | 01-summary/adr-index.md |
| Active ADRs | L2 (Analysis) | 02-analysis/architecture-decisions/ADR-NNN.md |
| Superseded ADRs | L3 (Dossiers) | 03-dossiers/adr-superseded.md |
1. Read the repository's agent instructions, contributing guide, ADR index, template, and a few recent records before drafting. Reuse the established location, numbering, headings, status vocabulary, approval process, and amendment policy.
2. Treat this skill's layouts and templates as fallbacks only. Do not move, renumber, rename, or rewrite existing ADRs to fit the skill. If local conventions conflict, preserve the existing records and identify the specific conflict before changing the convention.
3. If no convention exists, use a flat `docs/adr/` directory, stable sequential identifiers, a small index, and a lightweight Nygard template (MADR when option analysis needs more structure). Read `references/project-setup-guide.md` only when establishing a new decision log.
4. Read `references/adr-to-pyramid-mapping.md` only if the project already uses artifact pyramids or the user requests that organization. Index links can provide layered navigation without relocating canonical records.
Without ADRs, an agent sees a snapshot of the structure but cannot reconstruct the path that led to it. Active ADRs in L2 provide the decision rationale. Superseded ADRs in L3 preserve the history of rejected alternatives.
## Decision, Approval, and Evidence
Keep these three facts distinct, using the repository's existing fields or linked records:
- **Proposal:** What is recommended, why, alternatives, consequences, and unresolved questions. A draft or recommendation is not an accepted decision.
- **Decision authority and scope:** Who approved what, when, and for which environment or stage. Approval to experiment permits the bounded experiment; it does not establish production adoption. An accepted ADR may authorize only an experiment if that scope is explicit. Do not invent a decider, date, or broader approval.
- **Implementation evidence:** Links to changes, checks, observed results, and remaining gaps. Acceptance does not prove implementation; passing a prototype check does not prove production readiness. Label a validation plan as planned until results exist.
For example, “approved an isolated database trial” supports a trial-scoped decision. A successful restore rehearsal is evidence for the tested recovery scenario; neither fact alone means “database adopted in production.”
## ADR Lifecycle
ADRs progress through six stages, each with a gate criterion:
Use the local lifecycle and amendment rules. When absent, use `proposed → accepted | rejected`, with accepted decisions later `deprecated` or `superseded` by a linked successor.
```
Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting
```
Preserve accepted rationale. By default, a changed decision gets a new ADR; update the old record's status and successor link while retaining its identifier and location. If the repository uses living documents, make dated, attributable amendments under its policy. Do not impose mutability on an immutable log or replace a living-document process with an immutable one.
| Stage | Status | Pyramid Layer | Consumer |
|-------|--------|--------------|----------|
| Initiating | `proposed` | L2 (02-analysis/) | Engineers evaluating |
| Researching | `proposed` | L2 (02-analysis/) | Engineers evaluating |
| Evaluating | `proposed` | L2 (02-analysis/) | Engineers deciding |
| Implementing | `accepted` | L2 (02-analysis/) | Implementers, reviewers |
| Maintaining | `accepted` | L2 (02-analysis/) | New team members, auditors |
| Sunsetting | `deprecated`/`superseded` | L3 (03-dossiers/) | Historians |
All live ADRs (proposed + accepted) stay in L2. Only superseded/deprecated ADRs move to L3. Proposed ADRs that are rejected should be moved to L3 with status `rejected` and a note on why.
### Alternative Lifecycle: AWS ADR Process
AWS Prescriptive Guidance defines a complementary lifecycle with a structured review process for teams that prefer formal immutability over living documents.
**States:** `proposed → accepted | rejected | superseded`
**Key difference:** AWS treats ADRs as strictly immutable once accepted. Changing a decision requires a new ADR that supersedes the old one. The community ADR repo's teamwork advice prefers mutable living documents with date-stamped updates. Choose the model that fits your team's culture.
**AWS Review Process:**
1. **Proposal** — any team member creates an ADR in `proposed` state. The author is the ADR owner.
2. **Review meeting** — dedicated time slot with structured format:
- **10-15 minutes silent reading** — each member reads the ADR and adds comments
- **Comment read-out** — the owner reads each comment aloud; team discusses
- **Action points** — identified issues get an assignee; tracked to resolution
3. **Decision** — three outcomes:
- **Accepted** → owner adds timestamp, version, stakeholder list. State → `accepted`. Immutable.
- **Rework** → state stays `proposed`. Owner resolves action points and re-schedules review.
- **Rejected** → owner documents rejection reason (prevents future re-litigation). State → `rejected`. File moves to L3.
4. **Superseding** — new decision invalidates an accepted ADR? Create a new ADR. On acceptance, update old ADR status to `superseded` and move it to L3.
```
[Identify need] → [Draft (proposed)] → [10-15m silent read] → [Discuss]
↓ ↓ ↓
[Rework/review] ← [Needs rework] [Accepted] → [Immutable]
[Rejected] → [L3]
```
Record rejection and supersession reasons, maintain the index, and preserve links. Review format and meeting length follow the team's process; acceptance requires evidence of the relevant decision authority, not a mandatory ceremony.
## Template Selection
Use the repository template first. This table applies only when no template is established.
| When | Template | Sections |
|------|----------|----------|
| Quick decision, single rationale | **Nygard** | Status, Context, Decision, Consequences |
@@ -84,7 +54,7 @@ Full catalog with section-by-section guidance in `references/adr-format.md`.
## File Naming Conventions
Use present tense imperative verb phrases, lowercase-dashes, `.md` extension:
Follow local naming first. For a new log, use present tense imperative verb phrases, lowercase-dashes, `.md` extension:
```
001-choose-database.md
@@ -98,9 +68,9 @@ Status lives in the document header, not the filename — status changes shouldn
- **Who can create:** Any team member who has read the ADR process docs
- **What justifies:** Decisions affecting future "why", cross-team coordination, long-term maintainability, external interfaces
- **What does NOT:** Limited scope/time/risk, already covered by standards, temporary workarounds/POCs
- **What usually does NOT:** Routine changes already covered by standards. Record a bounded experiment when its authorization, constraints, or consequences need durable rationale.
- **Roles per ADR:** Primary contact, secondary contact, accountable team
- **Living documents preferred:** Insert new info with date stamps rather than superseding ADRs for every update. Immutability is ideal in theory; mutability works better in practice.
- **Amendments:** Follow repository policy; preserve decision history and distinguish new evidence from a changed decision.
See `references/adr-format.md` for the full governance model and teamwork questions.
@@ -110,6 +80,14 @@ See `references/adr-format.md` for the full governance model and teamwork questi
Read `references/fitness-functions.md` to select the function's scope, cadence, evidence, threshold, owner, exception path, and retirement rule. Use `templates/fitness-function-record.md` for the operational record. Keep the ADR as the owner of the durable decision and its link to confirmation; keep implementation and execution in the project's test, CI, telemetry, or governance systems.
## Completion and Boundaries
Complete when the requested ADR or review follows local conventions, identifies decision scope and authority without invention, preserves history, and distinguishes observed evidence from planned checks. If acceptance is unresolved, deliver a proposed record and name the missing decision rather than claiming acceptance.
## When not to use
Route system-wide architecture and change sequencing to `software-architecture`, and named-tool implementation to the relevant operational skill. This skill owns decision rationale and confirmation links, not execution of the implementation or a general observability program.
## Contents
- `references/adr-format.md` — template catalog (11 formats: Nygard, MADR, Tyree & Akerman, Business Case, Planguage, Alexandrian, ITD, arc42, EdgeX, Gareth Morgan, NHS Wales), template selection decision tree, lifecycle stages, file naming, team governance, examples reference
adr-authoring/evals/evals.json
+33 -2
View File
@@ -17,7 +17,7 @@
{
"id": "template-selection",
"prompt": "We are starting to write ADRs for a new project and I have seen many formats: the original Nygard format, MADR, and heavier enterprise templates. The team has different preferences. How do I choose a template, and should I even pick one?",
"expected_output": "A template-selection approach that prioritizes consistency and the decision's needs over format loyalty: the response explains that the template catalog exists because decision contexts differ — the original Nygard format suits a focused technical decision, MADR adds structure for incremental updates, and heavier formats carry the governance fields larger organizations need — and prescribes picking one default for the org with the selection made on criteria: the depth of governance required, how the ADRs will be consumed (read by the team, audited by a governance board), and the update pattern (append-only records versus evolving documents). It recommends starting with a lightweight default and migrating to a heavier format only if the governance need appears, and it stresses that the bigger win is a fixed convention — one template, one naming scheme, one location — over the choice of which format, because consistency is what makes ADRs searchable and reliable.",
"expected_output": "A template-selection approach that prioritizes consistency and the decision's needs over format loyalty: the response explains that the template catalog exists because decision contexts differ \u2014 the original Nygard format suits a focused technical decision, MADR adds structure for incremental updates, and heavier formats carry the governance fields larger organizations need \u2014 and prescribes picking one default for the org with the selection made on criteria: the depth of governance required, how the ADRs will be consumed (read by the team, audited by a governance board), and the update pattern (append-only records versus evolving documents). It recommends starting with a lightweight default and migrating to a heavier format only if the governance need appears, and it stresses that the bigger win is a fixed convention \u2014 one template, one naming scheme, one location \u2014 over the choice of which format, because consistency is what makes ADRs searchable and reliable.",
"assertions": [
"Template choice is tied to the decision context and governance need, not format loyalty",
"The response compares Nygard, MADR, and heavier formats on concrete criteria",
@@ -53,7 +53,7 @@
{
"id": "fitness-functions",
"prompt": "We have an accepted ADR mandating that new services must use our standard logging format, but a year later half the services violate it and nobody noticed until an incident. I want the architecture rules enforced automatically. How do I turn ADRs into checkable constraints?",
"expected_output": "A fitness-function approach that turns ADR decisions into automated checks: the response explains the concept — a fitness function is an automated test or check that continuously validates an architectural characteristic, and the ADR maps to one or more functions (a check that scans service code or configuration for the standard logging setup, run in CI or as a periodic audit). It prescribes the workflow: for each ADR with a mechanical consequence, define the check, implement it in the project's test or CI layer, and attach it to the ADR record so the link between decision and enforcement is explicit. The response covers the boundary: not every decision is mechanically checkable (judgment calls stay in review), but anything with a detectable pattern should be checked, and the check must be part of the definition of done for new services, not a retrofit after incidents. It includes an example check shape for the logging standard.",
"expected_output": "A fitness-function approach that turns ADR decisions into automated checks: the response explains the concept \u2014 a fitness function is an automated test or check that continuously validates an architectural characteristic, and the ADR maps to one or more functions (a check that scans service code or configuration for the standard logging setup, run in CI or as a periodic audit). It prescribes the workflow: for each ADR with a mechanical consequence, define the check, implement it in the project's test or CI layer, and attach it to the ADR record so the link between decision and enforcement is explicit. The response covers the boundary: not every decision is mechanically checkable (judgment calls stay in review), but anything with a detectable pattern should be checked, and the check must be part of the definition of done for new services, not a retrofit after incidents. It includes an example check shape for the logging standard.",
"assertions": [
"The fitness-function concept is explained as automated enforcement of architectural rules",
"Each mechanical ADR consequence maps to a concrete check",
@@ -97,6 +97,37 @@
"The response explains why the boundary prevents duplicated or ambiguous ownership",
"The proposed output includes an ADR-to-function-to-evidence trace rather than a standalone metric program"
]
},
{
"id": "repository-conventions-first",
"prompt": "Write the next ADR. CONTRIBUTING.md requires architecture/decisions/DEC-042.md, headings Status, Problem, Choice, Effects, and immutable accepted records. DEC-041 is accepted. Your skill suggests pyramid folders and living documents.",
"expected_output": "Draft DEC-042 using the repository conventions without reorganizing the decision log.",
"assertions": [
"Uses architecture/decisions/DEC-042.md and the specified headings",
"Preserves DEC-041 and its existing path and rationale",
"Does not create pyramid directories or impose living-document amendments"
]
},
{
"id": "experiment-approval-scope",
"prompt": "I approved an isolated PostgreSQL trial. Restore and deletion checks passed in the harness. Production adoption is still undecided. Draft an ADR using our Proposed/Accepted statuses.",
"expected_output": "Record the bounded trial approval and observed evidence separately from a proposed production decision.",
"assertions": [
"Does not describe production adoption as accepted",
"If marked Accepted, explicitly limits the decision to the trial",
"Distinguishes completed harness checks from production validation still needed",
"Does not invent an approval date or decider"
]
},
{
"id": "living-document-local-policy",
"prompt": "Our ADR policy uses dated amendments to accepted records in decisions/. ADR-007 remains in force. Add new trial evidence without changing the decision; do not supersede it.",
"expected_output": "Add a dated evidence amendment under the local living-document policy while preserving the accepted decision.",
"assertions": [
"Keeps ADR-007 in decisions/ and retains its accepted rationale",
"Uses a dated amendment for the new evidence without inventing results",
"Does not create a replacement ADR merely to enforce immutability"
]
}
]
}
adr-authoring/references/adr-format.md
+7 -3
View File
@@ -269,7 +269,7 @@ Chosen option: "[option 1]", because [justification].
**Origin:** https://arc42.org/overview — License: CC-BY-SA 4.0
**When to use:** Decisions that need to be documented within the full arc42 architecture documentation framework. This is the ADR-specific template by the arc42 team, distinct from the arc42 full documentation template (used by the `arc42-context` skill for system context/constraint documentation).
**When to use:** Decisions that need to be documented within the full arc42 architecture documentation framework. This is the ADR-specific template by the arc42 team, distinct from the arc42 full documentation template.
**Sections:**
@@ -287,7 +287,7 @@ Chosen option: "[option 1]", because [justification].
| **10. Quality Requirements** | Quality scenarios, quality tree |
| **11. Risks & Technical Debt** | Known risks, debt; ordered by priority |
**Relationship to arc42-context skill:** Our arc42-context skill uses the full arc42 template for documenting system constraints at the project level. This ADR template is a *lightweight version* focused on a single decision within that framework. Use this when documenting a decision inside existing arc42 documentation.
**Relationship to system documentation:** Use this when documenting a decision inside existing arc42 documentation. Route broader system architecture work to `software-architecture`.
---
@@ -483,6 +483,8 @@ Green = good fit Amber = moderate Red = poor fit
---
Use the repository template when one exists. The following tree is a fallback for a new convention.
### Template Selection Decision Tree
```
@@ -614,6 +616,8 @@ scale.
## Architecture Decision Log (ADL) Conventions
Existing repository paths, identifiers, templates, and amendment rules take precedence over these fallback examples. Never relocate accepted or superseded records merely to match this guide.
### File Naming
```
@@ -621,7 +625,7 @@ NNN-short-present-tense-phrase.md
```
Rules:
- **Number:** Zero-padded sequence (001, 002, ... 010). Avoid gaps; renumber on conflict.
- **Number:** Zero-padded sequence (001, 002, ... 010). Preserve published identifiers; gaps are acceptable. Resolve a collision on an unpublished draft without renumbering existing records.
- **Phrase:** Present tense imperative verb phrase — like a good commit message.
- Good: `012-use-postgresql-for-transaction-storage.md`
- Bad: `012-postgresql.md` (no verb), `012-decided-to-use-postgresql.md` (past tense)
adr-authoring/references/adr-to-pyramid-mapping.md
+3 -1
View File
@@ -1,5 +1,7 @@
# ADR-to-Pyramid Mapping
Apply only when artifact pyramids are already the project convention or explicitly requested. Existing ADR paths and lifecycle rules take precedence. Prefer links from pyramid indexes to canonical ADRs; this mapping does not require moving superseded records.
## Mapping Table
| ADR State | Pyramid Layer | What Lives There | Consumer |
@@ -8,7 +10,7 @@
| Active ADRs | **L2** (02-analysis/) | Full decision record: context, options, rationale, consequences | Engineers, reviewers |
| Superseded ADRs | **L3** (03-dossiers/) | Historical decisions that have been replaced | Historians, anyone challenging a current decision |
## Why ADRs Need Three Layers
## Why Layered Navigation Can Help
ADRs are modular by nature — each decision is a single document. But they still benefit from progressive disclosure:
adr-authoring/references/project-setup-guide.md
+13 -9
View File
@@ -2,16 +2,17 @@
A repeatable workflow for establishing Architecture Decision Records in a codebase that doesn't have them yet.
Use only after checking that no local convention exists or when the user asks to establish one. Existing repository instructions override every fallback below, including location, template, review workflow, and amendment policy.
## Quick Checklist
- [ ] Choose a template (default: MADR)
- [ ] Choose a template (default: Nygard; MADR for multi-option analysis)
- [ ] Decide directory location (default: `docs/adr/`)
- [ ] Write a README index (`docs/adr/README.md`)
- [ ] Document conventions in `CONTRIBUTING.md`
- [ ] Document ADR location in `AGENTS.md` (AI agents need to know where to look)
- [ ] Add `.hermes/` to `.gitignore` if it doesn't exist
- [ ] Create initial batch of ADRs for the design decisions already made
- [ ] File as a single PR: issue → branch → ADRs + docs → PR
- [ ] Deliver through the repository's established review workflow
## Step-by-Step
@@ -19,8 +20,8 @@ A repeatable workflow for establishing Architecture Decision Records in a codeba
| When | Template | Sections |
|------|----------|----------|
| Quick decision, single rationale | **Nygard** | Status, Context, Decision, Consequences |
| Multi-option trade-off analysis | **MADR** (default) | Status, Deciders, Date, Context, Decision Drivers, Considered Options, Outcome, Links |
| Quick decision, single rationale | **Nygard** (default) | Status, Context, Decision, Consequences |
| Multi-option trade-off analysis | **MADR** | Status, Deciders, Date, Context, Decision Drivers, Considered Options, Outcome, Links |
| High-stakes / regulatory | **Tyree & Akerman** | 12 sections (Issue, Positions, Argument, Implications, etc.) |
| Vendor / procurement | **Business Case** | Evaluation criteria, cost/SWOT analysis |
| QA / NFR focused | **Planguage** | Tag, Gist, Priority, Stakeholders, Risks |
@@ -72,24 +73,27 @@ and rationale behind significant design choices. Always check the ADR index at
document constraints or rejected alternatives that inform your approach.
```
### 6. Issue-First PR Workflow
### 6. Example Issue-First PR Workflow
Use this only if the repository requires an issue-first workflow; do not create issues, commits, or PRs solely because this example lists them.
1. File an issue documenting the adapter/architecture design (L1 summary + L2 key decisions)
2. Branch from main with a descriptive name (`feat/adapter-architecture`)
3. Create ADR files using the MADR template
4. Document convention in `CONTRIBUTING.md`
5. Add agent reference in `AGENTS.md`
6. Add `.hermes/` to `.gitignore` if missing (local dev artifacts should not be committed)
6. Ignore generated local artifacts only when relevant to this project
7. Commit with `Signed-off-by` (DCO) and `Refs: #NNN` in the commit body
8. Push and open PR referencing the issue (`Closes #NNN`)
## ADR Lifecycle (for ongoing use)
```text
proposed → accepted → [deprecated | superseded by ADR-NNNN | rejected]
proposed → accepted | rejected
accepted → deprecated | superseded by ADR-NNNN
```
- **Immutable rule:** Existing ADRs are never edited after acceptance. To change a decision, write a new ADR and update the old one's status.
- **Fallback amendment rule (local policy takes precedence):** Preserve accepted rationale. To change a decision, write a new ADR and update only the old record's status and successor link.
- **Linking:** Every ADR's Links section should reference related ADRs with semantic link types: `Refined by`, `Supersedes`, `Defined by`, `Contradicts`.
- **Retired numbers:** Never reuse an ADR number — if rejected, leave the number retired in the index with status `rejected`.
data-architect/README.md
+8 -11
View File
@@ -1,23 +1,18 @@
# Data Architect — Virtual Expert for Teams Who Don't Have One
# Data Architect
A virtual data architect that helps you spot data platform problems you didn't know you had. If your pipelines are growing faster than your team, your cloud bill is climbing, or you're about to choose a data platform — load this skill.
Make data architecture choices grounded in workload, ownership, operating cost, and evidence.
## Why Install This Skill
When your agent loads this skill, it becomes a **senior data architect** who can:
Choosing a store or platform should start with the decision in front of you. This skill compares the current approach with viable alternatives, explains the maintenance burden, and identifies what evidence would justify a change.
- **Run a QuickScan** — 5-minute diagnostics that surface common data platform gaps
- **Discover data assets** — inventory every system producing data your team consumes
- **Assess data maturity** — evaluate where you are on the data maturity curve
- **Design data architectures** — data mesh readiness, event-driven data products, data lakehouse, streaming, and real-time analytics
- **Establish governance** — data ownership models, business glossary, data contracts
- **Create migration plans** — structured paths from current state to target architecture
For a small transactional service, it focuses on correctness, recovery, and the team's ability to operate it. For broader platform work, it adds discovery, data mesh readiness, governance, and migration planning as needed. You get a practical recommendation and validation steps without an up-front maturity questionnaire.
## What You Get
| Directory | Purpose |
|-----------|---------|
| `SKILL.md` | Symptom recognition guide, QuickScan diagnostic, consulting workflow, and resource routing |
| `SKILL.md` | Decision workflow, tradeoff rules, evidence requirements, and resource routing |
| `references/` | Discovery framework, maturity model, architecture patterns, data mesh readiness, event-driven products, platform evaluation, governance, compliance, anti-patterns, and case studies |
| `scripts/` | Interactive governance maturity assessment |
| `templates/` | Architecture decision record and data architecture design-session worksheets |
@@ -29,11 +24,13 @@ Load this when your data pipelines are growing out of control, teams disagree on
## Requirements
No special system requirements. Designed for agentic AI assistants. Platform operations route to `platform-engineering`, pipeline implementation to `data-engineering`, and interface contracts to `api-design-and-evolution`.
No runtime needed for the guidance; Python 3 for the optional governance assessment. Platform operations route to `platform-engineering`, pipeline implementation to `data-engineering`, and interface contracts to `api-design-and-evolution`.
## Quick Start
Ask: “Compare our current transactional store with the proposed alternative, including ownership, recovery evidence, and conditions that would change the recommendation.”
From the skill directory, run the interactive governance assessment when the question is "How mature is our data governance?":
```bash
data-architect/SKILL.md
+33 -119
View File
@@ -18,105 +18,36 @@ metadata:
topics: data-architecture, data-modeling, data-warehouse, data-governance, data-platform, data-products, data-mesh, event-driven-data, etl, streaming, cloud-data
---
# Data Architect — Virtual Expert
# Data Architect
When this skill is loaded, I become a **virtual data architect** — someone who's seen enough data platforms go wrong to recognize the patterns early. I don't wait for you to know the right questions. If you're not sure where to start, tell me and I'll run a discovery.
## Start with the Decision
## Do You Need an Architect? (Recognizing the Symptoms)
1. Identify the decision and use the supplied context and repository artifacts first. For a bounded store choice or review, do not begin with a persona introduction, organization-wide inventory, or maturity questionnaire. Ask only for missing constraints that could change the recommendation; label other assumptions and proceed.
2. Classify the workload: transactional system of record, analytical serving, event exchange, or a combination. Establish the consumers, correctness requirements, data size and growth, concurrency, latency, retention/deletion needs, and recovery objectives that matter to this decision.
3. Compare the current approach with the smallest viable alternative. Include ownership, on-call burden, maintainability, migration and exit cost, and the team's ability to operate it. State which requirement would justify a more complex platform.
4. Deliver a recommendation with reasons, accepted costs, uncertainties, and the evidence that would change it. When evidence is insufficient, propose a bounded trial with success criteria rather than presenting the platform choice as settled.
Load this skill if any of these sound familiar — even if you're not sure what to do about them:
## Practical Decision Rules
**Pain signals:**
- Your data team is 3-5 people and growing, and you're starting to trip over each other
- Different teams have different definitions for the same business terms ("what does 'active customer' even mean?")
- You're about to pick a data platform and everyone has a strong opinion but no clear criteria
- Your cloud data bill keeps climbing and nobody can explain which pipeline is driving it
- Data pipelines break regularly and the root cause is hard to trace
- You're building your third pipeline that does basically the same thing as the first two
- Someone just asked "should we use Data Mesh?" and you need a sanity check
- You're migrating from an on-prem warehouse to the cloud and don't know the right sequence
- **Transactional store:** Start with transaction boundaries, consistency, constraints, access patterns, and concurrent updates. Do not prescribe a warehouse, mesh, lakehouse, or analytical modeling exercise unless an actual consumer requires it. Route database implementation and recovery operations to `postgres`, and service implementation to `backend-engineering`.
- **Operational complexity:** Every additional datastore, replication path, or streaming service needs an accountable owner and a concrete workload benefit. Retaining the current platform is a valid recommendation when it meets the requirements.
- **Recovery and deletion:** A backup or configured policy is not recovery evidence. Require a representative restore rehearsal and checks of required invariants. Where deletions must survive recovery, specify how deletion records outlive the restored snapshot, how they are reapplied before access resumes, and how absence is verified. Keep commands and runbooks in the owning tool skill.
- **Evidence:** Separate observed behavior, assumptions, and planned validation. A successful prototype supports only its tested conditions. Experiment approval does not imply production adoption; route durable decision records to `adr-authoring` and follow repository conventions before using `templates/adr-template.md` as a fallback.
- **Platform selection:** Evaluate workload fit and total operating cost before vendor features. If one missing fact changes the winner, name it and the smallest check that resolves it.
**Ambient anxiety signals:**
- "I feel like we should have a data catalog but I'm not sure"
- "We have data quality issues that keep surfacing in production"
- "I think we need better governance but nobody wants to be the one to slow things down"
- "We're growing fast and I'm worried our current setup won't scale"
Not sure if you need help? Say "I don't know where to start" and I'll run a quick discovery.
## QuickScan — Five Minutes to Spot Common Gaps
If you're not sure what problems you have, answer these yes/no questions. I'll use your answers to identify where to focus. You don't need to know anything about data architecture to answer them.
**Q1: Data inventory.** Can you list every system that produces data your team consumes? Do you know what's in each one?
- If no → we should start with data source discovery (`references/discovery-framework.md`)
**Q2: Data definitions.** If two teams use the term "active customer" or "revenue," would they get the same answer?
- If no → you have a semantic alignment problem. Let's talk about business glossary and data contracts.
**Q3: Data ownership.** For each important dataset, is there a named person responsible for its quality?
- If no → we should design a data ownership model. This is a governance maturity gap.
**Q4: Pipeline observability.** When a pipeline breaks, can you trace which source caused it and which reports are affected?
- If no → you need column-level lineage. Let's look at data catalogs and lineage tooling.
**Q5: Platform selection criteria.** If you had to pick between Snowflake, BigQuery, Redshift, and Databricks today, would you have a structured way to decide?
- If no → load `references/cloud-platform-comparison.md` and `references/architecture-patterns.md`.
**Q6: Data quality SLAs.** Do you know the accuracy and freshness of your most critical datasets?
- If no → governance maturity gap. See `references/governance-maturity.md`.
**Q7: Cost attribution.** Can you explain this month's cloud data bill? Do you know which pipelines, queries, or storage consume the most?
- If no → you need cost observability. This is a FinOps for data problem.
**Q8 : Schema management.** When a source system changes its schema, does anything automatically detect and flag the change?
- If no → you need schema registry or contract testing. Let's look at data contracts.
**Scoring:**
- **0-2 no's:** You're in decent shape. Pick the specific area that bothers you most.
- **3-5 no's:** Classic growing-pain territory. Say "I don't know where to start" and I'll prioritize.
- **6-8 no's:** You've been flying without instruments. This is exactly the right time to bring in architectural thinking.
I embody these traits when consulting:
**I push back on premature solutions.** Before any technology recommendation, I need to understand the business problem, the actual scale, the consumers, and the team's capability.
**I make tradeoffs explicit.** Every decision is a set of tradeoffs — I frame them clearly rather than giving a single right answer.
**I think in systems, not components.** I trace data from source to consumption, identifying where quality degrades, latency accumulates, governance gaps exist, and costs blow up.
**I design for the team that will maintain it.** A clever architecture is a liability if the team can't operate it. I factor in team size, skill level, and organizational context.
**I teach as I go.** If you don't know what a term means or why I'm asking a question, say so. I'll explain the concept and why it matters before we move on. The goal is not just to give you answers — it's to help you recognize these patterns yourself next time.
**I'm honest about uncertainty.** If your context needs something I'm not sure about, I'll tell you and suggest how to validate it.
## Consulting Patterns
## Task-Specific Workflow
### Architecture Review
When you present a design for review:
1. Ask clarifying questions about constraints (scale, budget, team, timeline)
2. Identify implicit assumptions that may be wrong
3. Trace failure modes — what breaks and how
4. Suggest alternatives with clear tradeoff language
5. Prioritize findings by impact
6. **Produce an ADR** — Say "capture that as an ADR" and I'll generate a structured Architecture Decision Record using `templates/adr-template.md`
### Decision Framework
When asked "X vs Y", I structure the answer:
- Core difference in architectural philosophy
- What problem each solves best
- What context tilts the decision
- Migration cost if you pick wrong
- Operational complexity of each
Trace the relevant data flow and failure modes using available evidence. Rank findings by impact, distinguish verified defects from hypotheses, retain working components, and give a concrete next action for each material finding. Do not infer missing retries, incremental processing, or observability solely from symptoms.
### Strategy & Roadmap
When planning multi-quarter evolution:
1. Current-state assessment — what you have, what hurts
2. Identify quick wins with high impact-to-effort ratio
3. Sequence investments so each phase enables the next
4. Flag organizational dependencies (hiring, skill building, governance maturity)
5. Define success criteria for each phase
### Decision Comparison
Use a compact comparison of viable options against the constraints, then state the recommended option, accepted tradeoffs, owner, validation needed, and reconsideration trigger. Avoid generic platform surveys when the workload is already clear.
### Strategy and Roadmap
For multi-quarter evolution, assess current bottlenecks, sequence incremental investments, name organizational dependencies, and define an observable success criterion for each phase. Load broader discovery or governance material only when the scope warrants it.
### Data Mesh or Event-Driven Data Product Design
@@ -131,34 +62,13 @@ When planning multi-quarter evolution:
Load `references/data-mesh-readiness-and-operating-model.md` for adoption assessment, `references/event-driven-data-products.md` for product and recovery decisions, and `templates/architecture-design-session.md` for a facilitated workshop artifact.
## Proactive Discovery — When You Don't Know Where to Start
## Discovery When the Problem Is Unclear
If you load this skill and say "I don't know where to start" or "just help me figure out what I need," here's what I'll do. You don't need to prepare anything.
**Step 1: Context grab (2 minutes)**
I'll ask a few quick things:
- How big is your data team? (1-2 people? 3-10? 10+?)
- How many data sources do you have?
- What's the #1 thing that's bothering you right now? (cost, reliability, speed, confusion)
- Are you on a cloud platform already, and which one?
**Step 2: QuickScan (covered above)**
I'll walk through the 8 questions. Just answer yes/no — I'll track the score.
**Step 3: Prioritize**
Based on your answers, I'll tell you:
- The one thing I'd fix first (highest impact, lowest effort)
- The one thing I'd plan for but not act on yet (emerging risk)
- What to ignore for now (it can wait)
**Step 4: Next action**
I'll give you a concrete next step — something you can do today, in this session, that will produce value. Maybe it's "let's sketch your current data flow" or "let me help you define what 'customer' means so both teams align."
**To trigger this:** Just say "I don't know where to start." I'll take it from there.
Use `references/discovery-framework.md` when the user asks for discovery or the decision cannot yet be bounded. Start with the most costly symptom and its affected consumer. For a requested quick scan, cover reliability, cost, shared definitions, ownership, and traceability; mark unknowns and prioritize the first concrete investigation. Treat symptoms as hypotheses, not proof that a catalog, schema registry, or new platform is required. Do not score organizational maturity from a count of yes/no answers.
## Core Expertise Areas
I have deep knowledge across these domains. Each has a reference file with decision guides — load them on demand when the topic comes up:
Load only the references needed for the current decision:
- **Data modeling** — Kimball, Inmon, Data Vault, lakehouse, star vs snowflake. → `references/architecture-patterns.md`
- **Data warehousing & lakehouse** — Medallion architecture, cloud warehouse design, cost optimization. → `references/architecture-patterns.md`
@@ -180,7 +90,7 @@ Load these on demand when the topic comes up:
- `references/architecture-patterns.md` — Decision framework for Kimball, Inmon, Data Vault, lakehouse, data fabric capabilities, data mesh, and hybrid shapes. Also covers streaming vs batch, star vs snowflake, and Medallion architecture.
- `references/anti-patterns.md` — 13 named anti-patterns with symptoms, root causes, and remediations. Load when doing design review or incident post-mortem.
- `references/discovery-framework.md` — Structured discovery questions and consulting session flow. Load at the start of a new architecture engagement.
- `references/discovery-framework.md` — Structured discovery questions and consulting session flow. Load when discovery is requested or the decision cannot yet be bounded.
- `references/cloud-platform-comparison.md` — Snowflake vs BigQuery vs Redshift vs Databricks: architecture, pricing, scaling, lock-in vectors, and decision framework. Load when doing platform selection or migration planning.
- `references/governance-maturity.md` — Staged data governance maturity model (Level 0-5) with DAMA-DMBOK framework, what each stage looks like in practice, and progression paths. Load when designing or assessing a governance program.
- `references/vendor-evaluation.md` — Structured evaluation criteria for data catalogs (Atlan, Alation, Collibra, DataHub, etc.), ETL/ELT tools (Fivetran, Airbyte, dbt), and orchestration (Airflow, Dagster, Prefect). Load during vendor selection.
@@ -191,10 +101,10 @@ Load these on demand when the topic comes up:
## Scripts & Templates
The skill includes tools I can run during a session:
Use these resources only for their stated purpose:
- `scripts/governance-assessment.py` — Interactive governance maturity assessment. Asks 15 scored questions across 5 dimensions, produces a maturity level, dimension scores, and prioritized recommendations. Run when someone asks "how mature is our governance?"
- `templates/adr-template.md` — Architecture Decision Record template. I'll fill this in when you say "capture that as an ADR" during a consulting session.
- `templates/adr-template.md` — Fallback Architecture Decision Record template when no repository template exists; use `adr-authoring` for lifecycle and approval handling.
- `templates/architecture-design-session.md` — Structured workshop worksheet for current state, workloads, candidate patterns, decisions, experiments, and owners.
Usage:
@@ -219,11 +129,15 @@ This skill is for data architecture strategy, design, and governance. Don't load
## Common Anti-Patterns (Quick Reference)
The most frequent issues I flag:
Check for these decision failures:
- **Silver bullet thinking** — Adopting Data Mesh because it's trendy, not because your org is ready for domain ownership
- **Governance as an afterthought** — "We'll add governance later" (you won't, and it'll cost 10x)
- **Governance as an afterthought** — Deferring ownership, retention, and access decisions without a named follow-up owner
- **SoR vs SSoT confusion** — Treating a transactional System of Record (e.g. ERP) as the enterprise Single Source of Truth, creating a bottleneck
- **Neglecting the team** — Designing a system nobody can operate or troubleshoot
See all 13 with full remediations in `references/anti-patterns.md`.
## Completion
Complete when the requested review, decision comparison, or roadmap identifies the recommendation, tradeoffs, ownership, evidence gaps, and next validation step. Stop expanding discovery once enough context supports that artifact. If a decisive constraint remains unknown, deliver the conditional recommendation and the specific question or check needed to resolve it.
data-architect/evals/evals.json
+43 -10
View File
@@ -5,7 +5,7 @@
{
"id": "quickscan-assessment",
"prompt": "My team's data pipelines keep breaking, the cloud bill is climbing without explanation, and nobody agrees on what 'customer' means across our reports. I do not know where to start. Run a quick scan of our data organization and tell me what the top gaps are.",
"expected_output": "A quick-scan assessment that turns the symptoms into a structured gap list: the response walks the five-minute scan over the common failure areas — pipeline reliability (how data is loaded, where failures happen and whether they are detected), cost (where spend concentrates, whether compute is runaway or rightsized), definitions (whether 'customer' and other core entities are defined once or redefined per report), ownership (who owns each pipeline and what happens when it breaks), and trust (whether anyone can trace a number on a dashboard to its source). It maps each symptom to the likely root gap: breaking pipelines to missing ownership and observability, climbing bills to ungoverned compute, and the customer disagreement to a missing shared semantic layer. It ends with the prioritized gaps and the first concrete action for each.",
"expected_output": "A quick-scan assessment that turns the symptoms into a structured gap list: the response walks the five-minute scan over the common failure areas \u2014 pipeline reliability (how data is loaded, where failures happen and whether they are detected), cost (where spend concentrates, whether compute is runaway or rightsized), definitions (whether 'customer' and other core entities are defined once or redefined per report), ownership (who owns each pipeline and what happens when it breaks), and trust (whether anyone can trace a number on a dashboard to its source). It maps each symptom to the likely root gap: breaking pipelines to missing ownership and observability, climbing bills to ungoverned compute, and the customer disagreement to a missing shared semantic layer. It ends with the prioritized gaps and the first concrete action for each.",
"assertions": [
"The scan covers pipeline reliability, cost, definitions, ownership, and trust",
"Each symptom is mapped to a likely root gap rather than a superficial fix",
@@ -17,19 +17,19 @@
{
"id": "pipeline-architecture-review",
"prompt": "We ingest events from our app into a warehouse through a chain of scripts, transform them in the database, and export dashboards. The pipeline works but takes 14 hours and fails often. Review this architecture and tell me what should change.",
"expected_output": "An architecture review that evaluates the pipeline against the properties that matter: the response assesses the current state (script-based orchestration, in-database transforms, batch frequency) and identifies the structural weaknesses — fragile orchestration without retries and monitoring, transformations that run in the serving database and scale poorly, no incremental processing so the 14-hour runtime grows with data volume, and no data-quality checks between stages so failures surface downstream. It proposes the target shape: orchestration with retries and observability, staging and transform layers that separate raw, cleaned, and modeled data, incremental or partitioned processing to bound runtime, and quality gates at each stage. The review is prioritized: the changes that reduce failure and runtime land first, and it identifies which parts of the current architecture can stay (the serving layer, the dashboards) while the plumbing is reworked.",
"expected_output": "An evidence-aware review of the reported 14-hour runtime and failures. Investigate orchestration, retries, query execution, incremental processing, and quality gates without assuming these are absent or that database transforms are inherently wrong. Prioritize changes supported by observations, propose bounded checks for uncertain causes, and retain working components.",
"assertions": [
"The review identifies the structural weaknesses: fragile orchestration, in-DB transforms, no incremental processing",
"It proposes a layered target with raw, cleaned, and modeled stages and quality gates",
"Incremental or partitioned processing is prescribed to bound the runtime",
"Changes are prioritized by failure-and-runtime reduction",
"Working parts such as the serving layer are retained rather than rewritten wholesale"
"Separates observed runtime and failures from hypothesized causes",
"Investigates retries, monitoring, incremental processing, and query execution without claiming missing features as facts",
"Makes proposed architecture changes conditional on evidence of bottlenecks",
"Prioritizes next checks and changes by failure and runtime impact",
"Retains working components when no evidence supports replacing them"
]
},
{
"id": "platform-decision-framework",
"prompt": "We need a data platform and are torn between using our existing Postgres for everything, adopting a cloud warehouse, and a newer lakehouse stack. The team has different opinions and the vendors are pushing hard. How do I make this decision properly?",
"expected_output": "A decision framework that defers the platform choice until the requirements are understood: the response identifies the decisions the platform must serve — the workloads (analytics, ML feature access, real-time versus batch), the data volumes and concurrency, the team's skills and operating capacity, and the future direction (lakehouse expansion, streaming). It frames the comparison across the named options on those requirements, including the total cost of ownership (licensing, compute, storage, and the people cost of operating each), and it exposes the vendor-pressure dynamic by grounding the choice in the workload evidence rather than platform enthusiasm. The framework produces a recommendation with the conditions under which the other options would win, and a pilot or proof-of-value step before commitment. It explicitly warns against picking the platform to avoid a later decision.",
"expected_output": "A decision framework that defers the platform choice until the requirements are understood: the response identifies the decisions the platform must serve \u2014 the workloads (analytics, ML feature access, real-time versus batch), the data volumes and concurrency, the team's skills and operating capacity, and the future direction (lakehouse expansion, streaming). It frames the comparison across the named options on those requirements, including the total cost of ownership (licensing, compute, storage, and the people cost of operating each), and it exposes the vendor-pressure dynamic by grounding the choice in the workload evidence rather than platform enthusiasm. The framework produces a recommendation with the conditions under which the other options would win, and a pilot or proof-of-value step before commitment. It explicitly warns against picking the platform to avoid a later decision.",
"assertions": [
"The framework defines the workloads, volumes, concurrency, and team capacity before comparing platforms",
"Options are compared on total cost of ownership including operating people-cost",
@@ -41,7 +41,7 @@
{
"id": "semantic-layer-governance",
"prompt": "Marketing reports revenue one way, finance reports it another, and the two numbers are different by 12%. I need to fix the definitions and stop the argument. How do I set up a governed semantic layer without freezing all data work?",
"expected_output": "A semantic-layer governance design that treats definitions as owned artifacts: the response establishes a single source of truth for core metrics (revenue, customer, active user) with a written definition, the calculation, and the owner for each, and it explains the governance model — definitions change through a review process with recorded rationale rather than per-report improvisation. The migration path keeps work moving: the semantic layer is introduced for the disputed metrics first, reports are migrated one at a time with a comparison period showing the old and new numbers side by side, and the legacy report is retired only when it matches. The response explains the 12% difference by identifying the likely divergence points (inclusion of refunds, definition of the reporting period, deduplication rules) and prescribes documenting those as part of the definition.",
"expected_output": "A semantic-layer governance design that treats definitions as owned artifacts: the response establishes a single source of truth for core metrics (revenue, customer, active user) with a written definition, the calculation, and the owner for each, and it explains the governance model \u2014 definitions change through a review process with recorded rationale rather than per-report improvisation. The migration path keeps work moving: the semantic layer is introduced for the disputed metrics first, reports are migrated one at a time with a comparison period showing the old and new numbers side by side, and the legacy report is retired only when it matches. The response explains the 12% difference by identifying the likely divergence points (inclusion of refunds, definition of the reporting period, deduplication rules) and prescribes documenting those as part of the definition.",
"assertions": [
"Core metrics get a written definition, calculation, and named owner",
"Definitions change through a review process, not per-report improvisation",
@@ -53,7 +53,7 @@
{
"id": "strategy-roadmap",
"prompt": "Our data team spends all its time firefighting broken pipelines and has no time to build the analytics the business is asking for. Leadership wants a data strategy. What should the strategy and roadmap contain, and how do we get out of firefighting?",
"expected_output": "A data strategy that addresses the firefighting trap structurally: the response frames the strategy around the outcomes the business needs and the capabilities required, then sequences a roadmap that first stabilizes the foundation — ownership for the broken pipelines, observability so failures are detected and repaired fast, and the quick wins that stop the most frequent incidents — before adding net-new analytics. The roadmap is phased with explicit criteria for moving from one phase to the next: the firefighting load must fall below a threshold, not just a calendar date. It covers the governance and staffing implications (who owns the platform, how new requests are triaged), and it names the metrics that show the strategy working: incident rate, time-to-repair, on-time analytics delivery. The response resists a roadmap that schedules the new analytics first while the foundation stays broken.",
"expected_output": "A data strategy that addresses the firefighting trap structurally: the response frames the strategy around the outcomes the business needs and the capabilities required, then sequences a roadmap that first stabilizes the foundation \u2014 ownership for the broken pipelines, observability so failures are detected and repaired fast, and the quick wins that stop the most frequent incidents \u2014 before adding net-new analytics. The roadmap is phased with explicit criteria for moving from one phase to the next: the firefighting load must fall below a threshold, not just a calendar date. It covers the governance and staffing implications (who owns the platform, how new requests are triaged), and it names the metrics that show the strategy working: incident rate, time-to-repair, on-time analytics delivery. The response resists a roadmap that schedules the new analytics first while the foundation stays broken.",
"assertions": [
"The strategy is organized around business outcomes and required capabilities",
"The roadmap sequences foundation stabilization before net-new analytics",
@@ -133,6 +133,39 @@
"Remediation ownership is assigned across domain product, platform enforcement, and federated governance responsibilities",
"Recurring failures or exceptions feed a review that proposes a global rule, domain rule, platform control, or explicit non-standardization decision"
]
},
{
"id": "bounded-transactional-store",
"prompt": "Two engineers maintain a small order service on PostgreSQL. We need atomic order and inventory updates at 30 writes/sec and have no analytics consumer. Compare keeping it with adopting a lakehouse. Give a practical recommendation.",
"expected_output": "Recommend retaining the transactional store subject to verifying workload requirements, with concrete tradeoffs and a bounded validation plan.",
"assertions": [
"Leads with the recommendation or relevant workload tradeoffs rather than persona or a maturity questionnaire",
"Uses atomic updates and operational ownership as decision criteria",
"Does not introduce a warehouse or mesh without a consumer requirement",
"Names evidence needed to validate workload fit rather than asserting capacity from write rate alone"
]
},
{
"id": "recovery-deletion-evidence",
"prompt": "We have nightly backups of our transactional evidence store. Records deleted after a backup must not reappear to users after restoring it. What must our architecture decision address before we claim recovery works?",
"expected_output": "Define deletion continuity across restoration, verification before serving, and evidence needed from a rehearsal.",
"assertions": [
"Distinguishes backup existence from tested recovery evidence",
"Addresses a deletion record or equivalent mechanism that survives restoring an older snapshot",
"Requires reapplying deletions before reopening access and checking deleted records remain absent",
"Routes PostgreSQL recovery implementation to postgres instead of supplying an operations runbook"
]
},
{
"id": "conditional-choice-no-questionnaire",
"prompt": "We already operate Postgres for a 20 GB transactional application with two maintainers. We need a store choice this week, but peak concurrency is unknown. Help us decide without running a company-wide maturity assessment.",
"expected_output": "Provide a conditional workload-grounded recommendation and a focused check of concurrency.",
"assertions": [
"Uses supplied context without requesting a broad inventory or maturity score",
"Names peak concurrency as an uncertainty and a bounded way to measure its effect",
"Includes maintainability and the cost of introducing another platform",
"States a condition that would change the recommendation"
]
}
]
}