@trohde/earos 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# @trohde/earos
+
+**CLI and web editor for the EaROS architecture assessment framework**
+
+[EaROS](https://github.com/ThomasRohde/EAROS) (Enterprise Architecture Rubric Operational Standard) is a structured framework for evaluating architecture artifacts consistently — by humans, AI agents, or both. This package gives you the CLI to scaffold and manage an EaROS workspace and a browser-based editor to create rubrics, run assessments, and author artifacts.
+
+---
+
+## Quick Start
+
+```bash
+npm install -g @trohde/earos
+earos init my-architecture --icons
+cd my-architecture && earos
+```
+
+That's it. Your workspace opens in the browser, ready to assess.
+
+Pass `--icons` to download the official architecture icon packages from **AWS**, **Azure**, and **GCP** into `./icons` during workspace initialization. The initializer creates stable Mermaid-friendly aliases under `./icons/aws/`, `./icons/azure/`, and `./icons/gcp/`.
+
+In an existing EaROS workspace, run `earos init . --icons` to fetch or refresh the icon sets without re-scaffolding the workspace.
+
+Override download URLs with environment variables if needed:
+- `EAROS_AWS_ICON_PACKAGE_URL` / `EAROS_AWS_ICON_PAGE_URL`
+- `EAROS_AZURE_ICON_PACKAGE_URL` / `EAROS_AZURE_ICON_PAGE_URL`
+- `EAROS_GCP_ICON_PACKAGE_URL` / `EAROS_GCP_ICON_PAGE_URL`
+
+---
+
+## What `earos init` Creates
+
+```
+my-architecture/
+├── core/                    Core meta-rubric (universal foundation, 9 dimensions)
+├── profiles/                Artifact-specific profiles (5 bundled: solution-architecture,
+│                            reference-architecture, adr, capability-map, roadmap)
+├── overlays/                Cross-cutting overlays (3 bundled: security, data-governance,
+│                            regulatory)
+├── standard/schemas/        JSON schemas for rubrics, evaluations, and artifacts
+├── templates/               Blank scaffolds for new profiles and evaluations
+├── evaluations/             Your evaluation records go here
+├── calibration/             Calibration artifacts and results
+├── .agents/skills/          10 EaROS skills for any AI coding agent
+├── earos.manifest.yaml      Single source of truth — inventory of all rubric files
+└── AGENTS.md                Project guide for AI agents (agent-agnostic)
+```
+
+The workspace is **agent-agnostic** — the `.agents/skills/` directory works with any AI coding agent that reads skill files (Claude Code, Cursor, Copilot Workspace, and others).
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `earos` | Start the web editor (Express server, opens browser) |
+| `earos init [dir] [--icons]` | Scaffold a complete EaROS workspace in `dir` and optionally download architecture icon packages from AWS, Azure, and GCP into `icons/`, with stable aliases in `icons/aws/`, `icons/azure/`, and `icons/gcp/` |
+| `earos validate <file>` | Validate a rubric or evaluation YAML against EaROS schemas (exit 0/1) |
+| `earos manifest` | Regenerate `earos.manifest.yaml` by scanning the filesystem |
+| `earos manifest add <file>` | Add a single file to the manifest |
+| `earos manifest check` | Verify the manifest matches the filesystem (exits non-zero on drift) |
+| `earos --help` | Show help |
+
+### Validate exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | File is valid |
+| `1` | Validation errors found (printed to stderr) |
+
+---
+
+## The Editor
+
+Running `earos` opens a browser-based editor with a **3×2 home screen**:
+
+| Audience | Cards |
+|----------|-------|
+| **Governance Teams** | Create Rubric, Edit Rubric |
+| **Reviewers** | New Assessment (guided wizard), Continue Assessment |
+| **Architects** | Create Artifact, Edit Artifact |
+
+Key editor features:
+
+- **Manifest-driven sidebar** — browse and load any rubric, profile, or overlay from your workspace
+- **Live YAML preview** — right panel updates in real time as you edit the form
+- **Schema validation** — status bar shows errors in real time against the EaROS JSON schemas
+- **Kind selector** — switches the form between `core_rubric`, `profile`, `overlay`, `evaluation`, and `artifact` — reshaping validation and field layout automatically
+- **Import / Export** — drag-and-drop YAML import; export as `<rubric_id>.yaml`
+- **Context-aware help** — inline guidance tied to the EaROS standard
+
+---
+
+## AI Agent Skills
+
+The initialized workspace includes **10 bundled skills** in `.agents/skills/` that any AI coding agent can use:
+
+| Skill | Purpose |
+|-------|---------|
+| `earos-assess` | Run a full 8-step evaluation on any architecture artifact |
+| `earos-review` | Audit an existing evaluation for over-scoring and unsupported claims |
+| `earos-template-fill` | Guide authors through writing an assessment-ready document |
+| `earos-artifact-gen` | Interview-driven artifact creation (produces schema-compliant YAML) |
+| `earos-create` | Create new rubrics (profiles, overlays, or core) through guided interview |
+| `earos-profile-author` | Technical YAML authoring guide for v2 field structure |
+| `earos-calibrate` | Run calibration exercises and compute inter-rater reliability |
+| `earos-report` | Generate executive reports from evaluation records |
+| `earos-validate` | Health check — validates all YAMLs against schemas |
+| `earos-remediate` | Generate prioritized improvement plans from evaluation results |
+
+See the [EaROS repository](https://github.com/ThomasRohde/EAROS) for full skill documentation.
+
+---
+
+## The EaROS Framework
+
+EaROS uses a **three-layer model**:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  OVERLAYS  — cross-cutting concerns                 │
+│  security · data-governance · regulatory            │
+├─────────────────────────────────────────────────────┤
+│  PROFILES  — artifact-specific extensions           │
+│  solution-architecture · reference-architecture     │
+│  adr · capability-map · roadmap                     │
+├─────────────────────────────────────────────────────┤
+│  CORE  — universal foundation (always applied)      │
+│  9 dimensions · 10 criteria                         │
+└─────────────────────────────────────────────────────┘
+```
+
+**Scoring** uses a 0–4 ordinal scale (0 = Absent → 4 = Strong) with explicit gate types that prevent weak scores from being hidden by weighted averages:
+
+| Gate | Effect |
+|------|--------|
+| `advisory` | Triggers a recommendation |
+| `major` | Caps the pass status |
+| `critical` | Blocks pass entirely; forces Reject |
+
+**Status outcomes:** Pass · Conditional Pass · Rework Required · Reject · Not Reviewable
+
+For the complete standard — scoring model, gate logic, status thresholds, DAG evaluation flow, and calibration protocol — see the [EaROS repository](https://github.com/ThomasRohde/EAROS).
+
+---
+
+## Links
+
+- **Repository:** [github.com/ThomasRohde/EAROS](https://github.com/ThomasRohde/EAROS)
+- **Issues:** [github.com/ThomasRohde/EAROS/issues](https://github.com/ThomasRohde/EAROS/issues)
+
+---
+
+## License
+
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — Thomas Rohde

package/assets/init/.agents/skills/earos-artifact-gen/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: earos-artifact-gen
+description: "Create architecture documents through guided interview. Triggers on \"create an architecture document\", \"generate a reference architecture\", \"help me write a solution architecture\", \"document my architecture\", \"new architecture document\", or any request to create/write/generate architecture artifacts."
+---
+
+# SKILL: earos-artifact-gen
+
+Interview an architect and generate a structured architecture artifact document that conforms to `standard/schemas/artifact.schema.json` and satisfies the evidence requirements of the relevant EAROS rubric.
+
+## References
+
+- Interview question templates: `references/interview-guide.md`
+- Output generation guide: `references/output-guide.md`
+- Artifact schema: `standard/schemas/artifact.schema.json`
+- Rubric files: discovered at runtime via `earos.manifest.yaml`
+
+---
+
+## Workflow
+
+### Step 1 — Determine artifact type and load rubric
+
+Ask the user: "What type of architecture artifact are you creating?"
+
+Common types: `solution_architecture`, `reference_architecture`, `adr`, `capability_map`, `roadmap`.
+
+Once confirmed:
+1. Read `earos.manifest.yaml` to find the matching profile.
+2. Load `core/core-meta-rubric.yaml` and the matching profile YAML.
+3. Load `standard/schemas/artifact.schema.json` for the artifact structure.
+4. Ask: "Are any cross-cutting concerns in scope? (security, data governance, regulatory compliance)" — load applicable overlays if yes.
+
+Announce what you loaded: "I'll use the [profile name] profile plus [overlays if any]. This covers [N] criteria."
+
+### Step 2 — Conduct the structured interview
+
+Read `references/interview-guide.md` before starting.
+
+Interview the architect section by section. Do not ask all questions at once — work through one section, confirm the responses, then move to the next. The sections follow the artifact schema structure:
+
+1. **Overview** — title, purpose, version, owner, status, audience
+2. **Business context** — business drivers, goals, stakeholders and their concerns
+3. **Scope and boundaries** — in-scope, out-of-scope, deferred, assumptions
+4. **Architecture views** — context view, functional decomposition, deployment topology, data flows
+5. **Key decisions and rationale** — major design choices, alternatives considered, tradeoffs
+6. **Quality attributes** — measurable targets, scenarios, architectural responses
+7. **Risks and mitigations** — open risks, mitigated risks, assumptions to validate
+8. **Operations and implementation** — deployment phasing, interface contracts, operational concerns
+9. **Compliance and governance** — applicable standards, controls implemented, evidence
+10. **Implementation guidance** — next steps, dependencies, open decisions
+
+**Interview technique:**
+- Ask questions in natural language, not in rubric criterion language. "What external systems does this connect to?" not "Describe your STK-01 stakeholders."
+- If an answer is thin, prompt for more: "Can you be more specific about [X]?" or "What would someone need to know to implement that?"
+- If the architect doesn't know something, record it as an assumption or open question rather than skipping it.
+- After each section, summarize what you captured and ask: "Does that accurately capture it? Anything to add?"
+
+Use `references/interview-guide.md` for question templates and guidance on what constitutes a useful answer.
+
+### Step 3 — Map answers to rubric criteria
+
+After completing the interview, map each collected answer to the rubric criteria it satisfies:
+
+For each criterion in the core + profile:
+- Identify which section(s) of the interview contain the evidence
+- Note if the evidence is thin (would score 1–2) vs. adequate (would score 3–4)
+- Flag gaps: criteria where no interview answer provides relevant evidence
+
+Present the gap summary: "Based on your answers, I have enough material for [N] of [M] criteria. I need more information about: [list]. Can we go back to these?"
+
+Fill gaps before proceeding to output generation.
+
+### Step 4 — Generate the artifact YAML
+
+Read `references/output-guide.md` before this step.
+
+Transform the interview answers into a structured YAML document conforming to `standard/schemas/artifact.schema.json`.
+
+Key principles:
+- Every section that maps to a rubric criterion must contain enough detail to evidence a score of 3 (the "clearly addressed" level).
+- Use structured sub-elements (tables, lists, scenarios) rather than freeform prose where the schema supports it. These are easier for EAROS evaluation.
+- Preserve the architect's language for names and terminology — do not substitute generic labels.
+- For every design decision, include: the driver, the alternatives considered (at least one), the rejection rationale, and the selected option.
+- Quality attribute targets must be measurable: "99.9% availability" not "high availability".
+
+### Step 5 — Validate and offer assessment
+
+After generating the artifact YAML:
+
+1. Check it against `standard/schemas/artifact.schema.json` — verify all required fields are present.
+2. Cross-check each rubric criterion: does the artifact contain the `required_evidence` items listed in the rubric?
+3. Flag any remaining gaps: "Criterion [id] requires [evidence] which is not present."
+4. Ask: "Would you like me to run `earos-assess` on this artifact to get a preliminary score before you finalize it?"
+
+If gaps remain and the architect cannot fill them, mark them as `[TBD: <what is needed>]` in the YAML so they are visible during review.
+
+---
+
+## Operating Principles
+
+- **Schema-first.** The artifact YAML must conform to `artifact.schema.json`. Do not generate free-form documents — the schema is the contract between artifact authors and EAROS evaluators.
+- **Rubric-aware.** Every field in the artifact schema maps to a rubric criterion's `required_evidence`. Filling the schema correctly means satisfying the evidence requirements.
+- **Interview before output.** Never generate a template with placeholder text and ask the architect to fill it in. Gather the information through conversation, then generate the artifact. Templates produce generic output; interviews produce specific, defensible artifacts.
+- **Decisions need rationale.** The most common reason artifacts score 1–2 is missing decision rationale. Probe every design choice: Why this? What else was considered? What was rejected and why?
+- **Measurable targets only.** Push back on aspirational quality attributes. "Fast" is not scoreable. "p99 < 200ms under 500 TPS load" is.
+- **Gap transparency.** Unknown information is better represented as `[TBD: <description>]` than as an omission. Unknown items that are marked as TBD are visible; silent omissions create surprises in EAROS review.

package/assets/init/.agents/skills/earos-artifact-gen/references/interview-guide.md

@@ -0,0 +1,313 @@
+# Interview Guide — EAROS Artifact Generation
+
+This reference contains question templates per section, guidance on adapting to artifact type and platform, examples of good vs. bad interview answers, probing techniques, and N/A handling. Read this before Step 2 (interview) in SKILL.md.
+
+---
+
+## Core Interviewing Principles
+
+### Ask about the world, not the document
+
+The architect knows their system. They do not know EAROS. Every question must be phrased in terms of the system, not the rubric.
+
+| Rubric language (never use) | Natural language (use this) |
+|----------------------------|----------------------------|
+| "Describe your STK-01 stakeholders" | "Who are the main groups that will use or be affected by this system?" |
+| "What are your TRC-01 business drivers?" | "What problem is this system solving — what would go wrong if it didn't exist?" |
+| "Provide RA-VIEW-01 architectural views" | "Can you describe what the system looks like — what are the main pieces and how do they connect?" |
+| "Document your CMP-01 compliance controls" | "Are there any regulatory or policy requirements this system has to meet?" |
+
+### Probe for specifics
+
+Vague answers produce vague artifacts that score 1. Use these probing patterns:
+
+| Vague answer | Probing question |
+|-------------|-----------------|
+| "We need high availability" | "What does that mean in practice — how long can the system be unavailable before it becomes a business problem? Do you have a number?" |
+| "It integrates with the main systems" | "Which specific systems — what are their names? What does each integration do?" |
+| "We considered a few options" | "What were the options? What made you choose this one over the others?" |
+| "Security is important" | "What specific security requirements does this need to meet? Any compliance frameworks like ISO 27001 or PCI DSS? Who owns security sign-off?" |
+| "It's a microservices architecture" | "How many services? Who owns each one? What do the service boundaries map to?" |
+| "We'll monitor it with standard tooling" | "What tooling specifically? What are the key metrics you'll alert on? What does an on-call engineer do when they get paged?" |
+
+### When to push back
+
+Push back when:
+- A quality attribute target is not measurable ("fast", "reliable", "secure")
+- A decision is stated without rationale ("we chose Kafka")
+- A stakeholder is listed without concerns ("IT Operations")
+- A compliance requirement is mentioned without a control mechanism ("we follow GDPR")
+
+Don't accept aspirational answers. The EAROS scoring guide requires evidence. If the artifact says "high performance", an evaluator will score it 1. If it says "p99 < 100ms at 1,000 TPS, validated by load test on date", it scores 3 or 4.
+
+---
+
+## Block-by-Block Question Templates
+
+### Block 1 — Context and Purpose
+*Rubric mapping: STK-01 (stakeholder identification), SCP-01 (scope and boundaries)*
+
+**Opening:**
+> "Before we get into the architecture, let's make sure we capture the context. I'll ask a few questions about who this is for and what it's supposed to do."
+
+**Questions:**
+1. "What is this system? Give me the one-sentence version — what does it do and why does it exist?"
+2. "Who are the main groups that will use or be affected by this system? Think broadly — not just developers, but business users, operations teams, compliance reviewers, customers."
+3. "For each of those groups, what is their primary concern about this system? What would they most want to know when reviewing this document?"
+4. "Where does this system start and stop? What is in scope for this architecture, and what are you explicitly not covering? Are there elements you're deferring to a later phase?"
+5. "Who authored this document and who is responsible for keeping it up to date?"
+
+**What good answers look like:**
+- Stakeholder: "The payments team (will build it), Finance (approves transactions), Fraud (monitors for anomalies) — each with a one-sentence concern"
+- Scope: Clear in/out-of-scope list, not "everything related to payments"
+
+**What to probe:**
+- If stakeholders are all technical roles: "Are there business stakeholders — people who will use the system or be accountable for it?"
+- If scope is stated in terms of goals rather than boundaries: "Can you describe the technical boundary — what external systems does this interact with? Where does your system hand off to another?"
+
+---
+
+### Block 2 — Business Drivers and Constraints
+*Rubric mapping: TRC-01 (traceability), RAT-01 (rationale and decisions)*
+
+**Opening:**
+> "Let's talk about why this architecture looks the way it does — what were the key requirements and constraints driving the design?"
+
+**Questions:**
+1. "What business problem is this architecture solving? What would happen if it didn't exist or if you built it a different way?"
+2. "Are there specific business drivers — events, regulations, strategic goals, or pain points — that led to this project?"
+3. "What are the hard constraints? Things that are non-negotiable — budget, timeline, technology stack, integration with existing systems, regulatory requirements?"
+4. "Who are the key business stakeholders for this project, and what does success look like from their perspective?"
+5. "Are there known risks or assumptions that could affect the design?"
+
+**What good answers look like:**
+- "The regulation requires us to store transaction records for 7 years — that drove the data retention architecture in Section 4"
+- "We're constrained to Azure because of our enterprise agreement — that ruled out AWS-native services"
+
+**What to probe:**
+- If drivers are vague ("digital transformation"): "What specifically needs to change? What are users or the business unable to do today?"
+- If constraints are vague ("limited budget"): "What does 'limited' mean — are we talking about annual cloud spend target, headcount, or license costs?"
+
+---
+
+### Block 3 — Architecture Views and Components
+*Rubric mapping: RA-VIEW-01 (views), CVP-01 (component value proposition) — or equivalent per profile*
+
+**Opening:**
+> "Now let's get into the architecture itself. I'll ask you to describe it at a few different levels — the big picture, the main components, and how data moves through the system."
+
+**Questions:**
+1. "At the highest level — what does this system look like? If you drew a box labeled '[system name]' in the middle of a whiteboard, what external actors and systems would you draw connecting to it? What does each connection represent?"
+2. "Inside that box, what are the main components or services? What is each one responsible for?"
+3. "How do the components talk to each other? Are there any important data flows or sequences worth describing — like a key transaction or use case?"
+4. "Where does this run? Describe the deployment — cloud, on-prem, hybrid? What infrastructure or platform components are involved?"
+5. "Where does data live? What are the key data stores, and what does each one hold?"
+
+**What good answers look like:**
+- "The API gateway receives all inbound requests, routes them to three microservices, and calls the legacy mainframe via an adapter for settlement"
+- "We have three data stores: Postgres for transactional data, Redis for session state, and S3 for document storage"
+
+**What to probe:**
+- If the description is still high-level: "Can you name the main components? Even a list of service names helps"
+- If deployment is vague ("it runs on AWS"): "Which AWS services specifically? Are you on ECS, EKS, Lambda? Is there a multi-region setup?"
+- If data flows are missing: "Walk me through a typical request — what happens from the moment a user hits the API to when they get a response?"
+
+**Platform-specific probing:**
+
+*AWS:* "EC2 or managed services? ECS/EKS/Lambda? RDS or DynamoDB? Are you using VPC peering or Transit Gateway for network isolation?"
+
+*Azure:* "AKS or App Service? Cosmos DB or Azure SQL? Are you using Azure AD for identity, and how does that integrate with your existing directory?"
+
+*On-prem / hybrid:* "What hypervisor or container platform? How does this connect to your cloud footprint, if any? Who manages the physical infrastructure?"
+
+---
+
+### Block 4 — Key Decisions and Rationale
+*Rubric mapping: RAT-01 (decision rationale), RA-DEC-01 (key architectural decisions)*
+
+**Opening:**
+> "Architecture is shaped by choices. Let's capture the major decisions that define why this design looks the way it does."
+
+**Questions:**
+1. "What were the 3–5 most important design decisions you made? The ones that, if you'd chosen differently, would have produced a fundamentally different architecture?"
+2. For each decision: "What were the main options you considered?"
+3. For each decision: "What led you to choose this option over the others? Was it a technical constraint, a business requirement, a risk, or a preference?"
+4. "Are there any decisions that are still open — where you haven't settled on an approach yet?"
+5. "Were there any decisions that were controversial or where people on the team disagreed? How was it resolved?"
+
+**What good answers look like:**
+- "We chose event streaming over REST callbacks for inter-service communication. We considered webhooks (simpler but unreliable) and polling (too much load). We went with Kafka because it's already in our platform and gives us replay capability for the audit requirement"
+- "The choice of PostgreSQL over MongoDB was driven by the need for strong consistency on financial records — we couldn't accept eventual consistency"
+
+**What to probe:**
+- If a decision is stated without alternatives: "What else did you consider before choosing [X]?"
+- If a decision lacks a business driver: "What requirement or constraint made [X] the right choice? What would have been different if you'd chosen [Y]?"
+- If the team "always uses" something: "Is there a specific reason that technology was the right fit here, or was it familiarity? Were there any tradeoffs you accepted?"
+
+---
+
+### Block 5 — Quality Attributes
+*Rubric mapping: RA-QA-01 (quality attributes and NFRs)*
+
+**Opening:**
+> "Let's talk about the non-functional requirements — the '-ilities'. These are often what makes or breaks an architecture."
+
+**Questions:**
+1. "What are the performance requirements? Think about response time, throughput, and concurrent users."
+2. "What are the availability and reliability requirements? What's the acceptable downtime? What happens during a failure?"
+3. "What are the scalability requirements? What's the current scale, and what does growth look like? Is there a seasonal peak?"
+4. "What are the security requirements? Authentication, authorization, encryption at rest and in transit?"
+5. "What observability do you need? What metrics, logs, and traces are required?"
+
+**What good answers look like:**
+- "API response time < 200ms at the 99th percentile under 500 concurrent users"
+- "We need 99.9% monthly uptime — that's roughly 8 hours/year"
+- "Data at rest encrypted with AES-256, all connections TLS 1.2 or higher, OAuth 2.0 for external API auth"
+
+**What to probe:**
+- If targets are not measurable: "Can you put a number on that? What's the threshold where performance becomes a problem?"
+- If availability is stated without a failure scenario: "What happens when a component fails? Is there failover? What's the recovery time objective?"
+- If observability is vague: "What would an on-call engineer look at first when something goes wrong?"
+
+---
+
+### Block 6 — Operations
+*Rubric mapping: RA-OPS-01 (operational concerns), MNT-01 (maintainability)*
+
+**Opening:**
+> "Good architectures are built to run, not just to deploy. Let's cover how this system will operate in production."
+
+**Questions:**
+1. "How will this be deployed? Is there a CI/CD pipeline? Who owns the deployment process?"
+2. "How will it be monitored? What are the key health indicators?"
+3. "What does a degraded state look like, and what happens to traffic when a component is down?"
+4. "What is the disaster recovery plan? If the whole system went down right now, what would you do, and how long would it take to restore?"
+5. "Are there any ongoing operational costs or concerns — data retention, storage growth, licensing?"
+
+**What good answers look like:**
+- "We use ArgoCD for continuous deployment from main. RTO is 4 hours based on snapshot recovery. We alert on p95 > 500ms and error rate > 0.1%"
+
+**What to probe:**
+- If DR is vague: "Walk me through what you'd actually do — who gets called, what gets restored first, what's the recovery time in the worst case?"
+- If monitoring is vague: "What's the dashboard that the on-call person opens first? What's the first alert they'd see?"
+
+---
+
+### Block 7 — Compliance and Governance
+*Rubric mapping: CMP-01 (compliance and governance fit)*
+
+**Opening:**
+> "Let's make sure we capture the regulatory and policy context. This is important for governance review."
+
+**Questions:**
+1. "Does this system process personal data, financial data, or any regulated data types?"
+2. "What compliance frameworks or regulations apply — GDPR, PCI DSS, ISO 27001, internal policy?"
+3. "For each applicable framework, what specific requirements does it impose on this architecture? How does the design address those requirements?"
+4. "Are there any compliance gaps — controls that are required but not yet implemented?"
+5. "Who is responsible for compliance sign-off? Has legal or compliance reviewed this design?"
+
+**What good answers look like:**
+- "We're in scope for PCI DSS SAQ D because we handle cardholder data. The key requirements addressed are: network segmentation (shown in Section 4.2), encryption in transit and at rest (Section 5.1), and access logging (Section 6.3). The pen test requirement is deferred to Q3"
+
+**What to probe:**
+- If "it's not in scope": "Are you certain? Does it process any customer identifiers, financial transactions, or health data?"
+- If compliance is asserted without evidence: "How specifically does the architecture address that requirement? Which component or control implements it?"
+
+---
+
+### Block 8 — Implementation Guidance
+*Rubric mapping: RA-IMP-01 (implementation guidance), ACT-01 (actionability)*
+
+**Opening:**
+> "Finally, let's make sure the document gives implementers what they need to act."
+
+**Questions:**
+1. "What are the key next steps? What needs to happen for this architecture to be implemented?"
+2. "Are there any decisions still outstanding that need to be made before implementation can start?"
+3. "What are the main dependencies on other teams, systems, or external approvals?"
+4. "Are there any known risks that could affect the implementation timeline or approach?"
+5. "Who should read this document? What do you want them to do with it?"
+
+---
+
+## Artifact-Type Specific Guidance
+
+### Solution Architecture
+
+Focus on: implementation specifics, integration points, phasing, team ownership.
+
+Additional questions:
+- "What is the delivery timeline? Is this being built in phases?"
+- "Which team or vendor is building each component?"
+- "What are the integration contracts with existing systems — APIs, events, data formats?"
+
+Probe deeper on: deployment topology, team boundaries, handover points.
+
+### Reference Architecture
+
+Focus on: reusability, pattern documentation, variation points.
+
+Additional questions:
+- "Who are the intended consumers of this reference architecture? What systems or teams would use it as a blueprint?"
+- "What are the 'slots' where users can substitute their own choices? What's fixed vs. flexible?"
+- "What are the known patterns or anti-patterns for systems in this category?"
+
+Probe deeper on: applicability conditions, variance mechanism, governance for deviation.
+
+### Architecture Decision Record (ADR)
+
+Focus on: one decision only. Interview is shorter — 5–8 questions.
+
+Structure: Context → Decision → Alternatives → Rationale → Consequences.
+
+Questions:
+1. "What decision are you documenting?"
+2. "What context led to this decision — what constraints or requirements made it necessary?"
+3. "What options did you consider? Why were the alternatives rejected?"
+4. "What are the consequences — positive and negative — of this decision?"
+5. "Who made this decision, and is it final or revisable?"
+
+### Capability Map
+
+Focus on: capability definitions, business ownership, maturity levels.
+
+Additional questions:
+- "How are capabilities defined — what makes something a distinct capability vs. a sub-capability?"
+- "For each capability, who owns it and what business process does it support?"
+- "Is there a current maturity assessment for each capability?"
+
+Probe deeper on: gaps between current and target maturity, investment priorities.
+
+### Roadmap
+
+Focus on: timeline, sequencing rationale, dependencies.
+
+Additional questions:
+- "What is the planning horizon? 1 year, 3 years?"
+- "What drives the sequencing — business priority, technical dependency, funding?"
+- "What are the key milestones and what does each one deliver?"
+
+Probe deeper on: risks to the timeline, dependencies on external decisions or teams.
+
+---
+
+## When to Skip a Section
+
+If a block clearly doesn't apply, state it explicitly and move on:
+
+- "You mentioned this is a capability map with no deployment concerns — I'll skip the operations block."
+- "For an ADR, compliance details belong in the decision context rather than a separate block. Let me ask about that as part of the rationale."
+
+Never skip silently. Every skipped block should be noted as either N/A or deferred, so an evaluator knows the author considered it.
+
+---
+
+## Handling "I Don't Know" Answers
+
+If the architect can't answer a question:
+
+1. Record it as an open question or assumption: `[TBD: who owns DR for this system?]`
+2. Note the impact: "This will likely score low on the operational concerns criterion — it's worth finding out before the review"
+3. Offer to proceed and return: "We can come back to this — let's keep going and circle back"
+
+Do not generate placeholder content that sounds complete. A visible TBD is better than a fabricated answer that scores 0 when the evaluator checks.