| 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
- Identify the business workflow and user outcome.
- Identify current system state from repo docs, issues, or user context.
- Frame the architecture decision in terms of reliability, quality, latency, cost, velocity, and business impact.
- Choose the smallest useful design artifact: ADR, design note, issue spec, eval plan, or rollout note.
- Include a visual when the design spans multiple components.
- Convert recommendations into acceptance criteria that a coding agent can verify.
- Define eval and observability requirements before implementation.
- 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
- Vague implementation guidance. Replace "improve RAG" with a scoped issue like "Add Recall@k breakdown by Pinecone namespace."
- Architecture without proof. Every recommendation should name an eval, metric, or trace field.
- Overbuilding. Prefer vertical slices that ship in weeks.
- Ignoring unit economics. Stronger models and rerankers need explicit quality lift.
- Missing failure behavior. Production agents need timeouts, fallbacks, escalation, and auditability.
- No non-goals. Coding agents need explicit boundaries.
Verification Checklist
