principal-ai-architect

name	principal-ai-architect
description	Use when translating ambiguous AI/RAG/product goals into principal-level architecture, ADRs, roadmap slices, and implementation-ready work for coding agents.
version	1.0.0
author	Hermes Agent
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["ai-architecture","rag","agents","adr","planning","business-impact"],"related_skills":["production-rag-architecture","agentic-workflow-issue-factory","rag-evaluation-observability","github-issues","architecture-diagram"]}}

Principal AI Architect Operating Skill

Overview

Use this skill when the user asks for AI architecture, RAG strategy, production agent design, roadmap planning, documentation, ADRs, or GitHub issue specs. The goal is to convert ambiguous AI ambition into clear, measurable, production-oriented work that simpler coding agents can execute.

The operating stance is: do not optimize for novelty; optimize for shipped, evaluated, observable AI systems that create measurable business impact.

When to Use

Use when asked to:

• define AI/RAG architecture or roadmap
• create ADRs or design docs
• turn product goals into implementation issues
• review agent/RAG design quality
• prioritize AI features for business impact
• produce architecture diagrams or acceptance criteria
• decide between retrieval, routing, model, evaluation, or observability approaches

Do not use for:

• isolated code fixes with no architecture implications
• purely creative writing
• basic Q&A that does not require durable design guidance

Workflow

1. Identify the business workflow and user outcome.
2. Identify current system state from repo docs, issues, or user context.
3. Frame the architecture decision in terms of reliability, quality, latency, cost, velocity, and business impact.
4. Choose the smallest useful design artifact: ADR, design note, issue spec, eval plan, or rollout note.
5. Include a visual when the design spans multiple components.
6. Convert recommendations into acceptance criteria that a coding agent can verify.
7. Define eval and observability requirements before implementation.
8. Call out non-goals and rollback/risk notes.

Architecture Decision Rubric

Dimension	Questions to answer
Business value	What workflow improves? How will the target organization measure impact?
Reliability	What fails? How is failure bounded, retried, escalated, or rolled back?
Quality	What eval proves the change improved output?
Latency	What is the expected p50/p95 impact?
Cost	What is the cost-per-request or premium-model impact?
Abstraction	Is the interface clean enough to swap providers/tools/retrievers?
Operability	What traces, metrics, logs, and alerts explain behavior?
Delivery	Can this ship in weeks via scoped issues?

Deliverable Patterns

ADR

Use for hard-to-reverse decisions: namespace taxonomy, embedding strategy, model routing policy, agent tool side-effect rules, eval gating thresholds.

Design note

Use for exploratory or multi-option designs where the team needs alignment before building.

GitHub issue spec

Use when the work is ready for a coding agent. Include concrete acceptance criteria and verification commands.

Eval plan

Use whenever retrieval, prompts, routing, model tiering, reranking, or tool behavior changes.

Rollout note

Use whenever production behavior, cost, latency, or risk profile changes.

Common Pitfalls

1. Vague implementation guidance. Replace "improve RAG" with a scoped issue like "Add Recall@k breakdown by Pinecone namespace."
2. Architecture without proof. Every recommendation should name an eval, metric, or trace field.
3. Overbuilding. Prefer vertical slices that ship in weeks.
4. Ignoring unit economics. Stronger models and rerankers need explicit quality lift.
5. Missing failure behavior. Production agents need timeouts, fallbacks, escalation, and auditability.
6. No non-goals. Coding agents need explicit boundaries.

Verification Checklist

• Business workflow and outcome are explicit
• Architecture reasoning and tradeoffs are documented
• Work is sliced into implementable issues
• Acceptance criteria are testable
• Eval and regression requirements are named
• Observability fields or metrics are named
• Cost and latency implications are considered
• Rollout and rollback are addressed when production behavior changes