| name | ea-artifact-templates |
| description | This skill should be used when the user asks to "create an artifact", "generate the architecture vision", "start a new artifact from a template", "what template should I use", "populate this artifact", or when any TOGAF artifact needs to be created or populated. Provides template selection, placeholder conventions, and guidance text marking standards for all EA artifacts. |
| version | 0.9.55 |
EA Artifact Templates
All EA artifacts are created from templates stored in the plugin's templates/ directory. Templates use a consistent structure with clearly marked guidance, placeholder tokens, and answer state markers.
Artifact Taxonomy
Every artifact template includes a taxonomy: block in its YAML frontmatter. Use references/taxonomy.md as the canonical reference for all valid values and assignment rules.
taxonomy:
domain: Cross-cutting
category: Strategy
audience: Executive
layer: Motivation
sensitivity: Internal
tags: [vision, goals, phase-a]
When creating a non-standard artifact, assign taxonomy values using references/taxonomy.md. The taxonomy block is a T1-10 compliance requirement — all artifacts must have it.
Template Conventions
Placeholder Tokens
All unfilled fields use double-brace tokens:
{{field_name}} — simple value
{{stakeholder_name}} — named entity
{{YYYY-MM-DD}} — date-only field (startDate, decisionDate, file names)
{{YYYY-MM-DDTHH:MM:SSZ}} — timestamp field (lastModified, createdAt, lastUpdated)
{{artifact_ref}} — reference to another artifact
Guidance Text
Guidance explaining what a section means is marked with HTML comments so it is invisible in rendered output but visible in source:
<!-- GUIDANCE:
Describe the high-level intent and scope of this section.
This text is for the author and should NOT appear in the final deliverable.
Remove or leave as-is — it will not render in Word or HTML exports.
-->
Answer State Markers
| State | Marker |
|---|
| Answered | Value written directly |
| Not answered | ⚠️ Not answered |
| Not applicable | ➖ Not applicable |
| Opted out | ⊘ Opted out or ⊘ Opted out — {reason} |
| AI-suggested draft | > 🤖 **AI Draft — Review Required** blockquote |
| Default accepted | value + ✓ Default accepted |
| Source document | value + 📎 Source: uploads/{filename} |
Opted out vs. Not answered: ⊘ Opted out is an explicit, deliberate choice — the user decided this question or artifact is out of scope for their needs. The reason is recorded in engagement.json under optOuts[] and surfaced in status reports. ⚠️ Not answered is a temporary skip — the field may still be filled in later.
Governance State Markers (Appendix A3 — Decision Log)
Used exclusively in Appendix A3 decision rows to track the governance state of each decision:
| State | Marker | Meaning |
|---|
| Provisional | 🔄 Provisional | Recorded but not yet reviewed or owned |
| Awaiting Verification | ⏳ Awaiting Verification | Assigned to an owner; pending their confirmation |
| Verified | ✓ Verified | Owner has confirmed the decision is correct |
| Under Vote | 🗳️ Under Vote | Submitted to stakeholders for a formal vote |
| Voted | ✅ Voted | Decision carried by stakeholder vote |
| Fiat | 👑 Fiat | Decided by a senior decision maker without vote |
| Returned | ↩️ Returned | Sent back for rework by approver or facilitator |
Appendix Schema — A3 Decision Log
Every artifact that supports a Decision Log uses this standard table in ## Appendix A3 — Decision Log:
### Appendix A3 — Decision Log
| Item | Value | State | Captured By | Owner | Authority | Domain | Cost | Impact | Risk | Subject | Date |
|---|---|---|---|---|---|---|---|---|---|---|---|
| {{item}} | {{value}} | 🔄 Provisional | {{facilitator}} | {{owner}} | Strategic / Tactical / Operational | Business / Data / Application / Technology / Cross | High / Med / Low / TBD | High / Med / Low / TBD | High / Med / Low / TBD | {{subject_tag}} | {{date}} |
Field definitions:
| Field | Values | Meaning |
|---|
| Authority | Strategic / Tactical / Operational | Strategic = enterprise-wide long-term commitment; Tactical = engagement-scoped medium-term; Operational = implementation detail short-term |
| Domain | Business / Data / Application / Technology / Cross | Which architecture domain this decision primarily affects |
| Cost | High / Med / Low / TBD | Resource or time commitment required to execute this decision |
| Impact | High / Med / Low / TBD | Business or architecture impact if this decision stands or changes |
| Risk | High / Med / Low / TBD | Risk of making this decision incorrectly or reversing it later |
| Subject | Free text | Short tag (e.g. "Cloud strategy", "Data governance", "API design") for topic-based filtering |
A3 rows are the source data for /ea-decisions.
A3.N Decision Rationale Blocks
Each A3 decision row may have an accompanying rationale block written directly below the A3 table. These blocks capture the reasoning behind a decision and are expected for all Strategic-authority decisions.
Format: One block per decision, anchored by the Item field value (case-insensitive match):
#### A3.N — {Item value}
- **Rationale:** Why this decision was made
- **Alternatives:** Other options considered and why they were rejected
- **Tradeoffs accepted:** What was sacrificed by choosing this option
- **Implications:** Downstream effects to monitor or act on
Rules:
Created by: /ea-interview (immediately after a: {text} capture); /ea-decisions rationale (catch-up pass for existing A3 entries)
Consumed by: /ea-decisions generate (Decision Detail section); compliance rule T3-RATIONALE
Appendix Schema — A4 Stakeholder Concerns & Objections
Every primary artifact (Architecture Vision, all domain architectures, Gap Analysis, Architecture Roadmap, Statement of Architecture Work, and Migration Plan) includes this appendix in ## Appendix A4 — Stakeholder Concerns & Objections:
### Appendix A4 — Stakeholder Concerns & Objections
| ID | Concern | Raised By | Category | Status | Response | Action / Owner |
|---|---|---|---|---|---|---|
| *(no concerns recorded)* | — | — | — | — | — | — |
Field definitions:
| Field | Values | Meaning |
|---|
| ID | CON-NNN | Concern identifier — sequential within the engagement across all artifacts |
| Concern | Free text | The objection, question, or challenge as it was raised — verbatim where possible |
| Raised By | Free text | Source: stakeholder name/role (e.g. "CIO"), "grill-me-boardroom", "Architecture Review Board", "Sponsor workshop", etc. |
| Category | Scope / Goal / Approach / Feasibility / Risk / Stakeholder / Other | The type of concern |
| Status | Addressed / Partially Addressed / Requires Attention | Whether the concern has been resolved |
| Response | Free text or artifact/section reference | Where in this artifact (or another) the concern is answered (e.g. "§3 Goals — G-001 scoped to exclude retail domain"). Leave blank if Requires Attention |
| Action / Owner | Free text | What needs to happen and who is responsible — only for Requires Attention items. Leave — for Addressed items |
Status rules:
- Addressed — a clear, documented response exists; record where. Set
Action / Owner to —
- Partially Addressed — a response exists but with acknowledged gaps; note both the response and remaining gap
- Requires Attention — no adequate response exists; must have an Action and Owner. These rows are flagged by
/ea-concerns and may be escalated to the Risk Register as RIS-NNN entries
A4 rows are the source data for /ea-concerns.
Review State Header
Every artifact includes a status block at the top:
---
artifact: Architecture Vision
engagement: {{engagement_name}}
phase: A
status: Draft
reviewStatus: Not Reviewed
version: 0.1
lastModified: {{YYYY-MM-DDTHH:MM:SSZ}}
---
Artifact Catalogue
Artifact depth (section detail, length, governance formality) is calibrated to the engagement's architectureLevel. At the start of any artifact creation or population session, load skills/ea-engagement-lifecycle/references/landscape-levels.md and apply the Depth Expectation Matrix:
- Strategic — full population of all sections; all governance appendices (A3, A4, A5) required; all A3 Strategic-authority decisions require A3.N rationale blocks
- Segment — full population; same governance requirements as Strategic
- Capability — key sections; A3/A4/A5 required; abbreviated sections noted in the matrix
- Solution — key sections; A3/A4/A5 required; may abbreviate governance appendices as noted
All TOGAF artifacts are in scope. Templates are stored in the plugin's templates/ directory:
| Template File | Artifact | ADM Phase |
|---|
engagement-charter.md | Engagement Charter | Prelim |
governance-framework.md | Governance Framework | Prelim |
architecture-principles.md | Architecture Principles | Prelim / A |
stakeholder-map.md | Stakeholder Map | Prelim / A |
architecture-vision.md | Architecture Vision | A |
statement-of-architecture-work.md | Statement of Architecture Work | A |
target-state-declaration.md | Target State Declaration | A |
communications-plan.md | Communications Plan | A |
architecture-definition-document.md | Architecture Definition Document | A (skeleton) → F (final) |
business-model-canvas.md | Business Model Canvas | B |
business-architecture.md | Business Architecture | B |
data-architecture.md | Data/Information Architecture | C |
application-architecture.md | Application Architecture | C |
technology-architecture.md | Technology Architecture | D |
gap-analysis.md | Gap Analysis (domain) | B, C-Data, C-App, D |
consolidated-gap-analysis.md | Consolidated Gap Analysis | E |
transition-architectures.md | Transition Architectures | E / F |
architecture-roadmap.md | Architecture Roadmap | E / F |
migration-plan.md | Migration Plan | F |
implementation-governance-plan.md | Implementation Governance Plan | G |
architecture-contract.md | Architecture Contract | G |
compliance-assessment.md | Compliance Assessment | G |
change-request.md | Architecture Change Request | H |
change-register.md | Change Register | H (generated by /ea-changes) |
requirements-register.md | Architecture Requirements Register | Requirements |
traceability-matrix.md | Requirements Traceability Matrix | Requirements |
architecture-decision-record.md | Architecture Decision Record | All phases |
stakeholder-action-plan.md | Stakeholder Action Plan | cross-cutting/governance/ (generated by /ea-actions) |
adr-register.md | ADR Register | cross-cutting/governance/ (generated by /ea-adrs) |
abb-register.md | ABB Register | C / D (generated by /ea-abbs) |
sbb-register.md | SBB Register | D (generated by /ea-sbbs) |
story-register.md | Story Register | E / F (generated by /ea-stories) |
risk-register.md | Risk Register | cross-cutting/operations/ (generated by /ea-risks) |
zachman-diagram.md | Zachman Diagram | cross-cutting/context/ (generated by /ea-zachman) |
decision-register.md | Decision Register | cross-cutting/governance/ (generated by /ea-decisions) |
consolidated-report.md | Consolidated Architecture Report | All phases |
workshop-minutes.md | Workshop Minutes | All phases (generated by /ea-workshop) |
arb-minutes.md | ARB Meeting Minutes | All phases (generated by /ea-arb) |
cross-cutting-index.md | Cross-cutting Index | artifacts/cross-cutting/ (navigation hub, auto-updated) |
Creating an Artifact
- Identify the artifact type and its template file
- Copy the template to
EA-projects/{slug}/artifacts/{phase-folder}/{artifact-id}.md — derive {phase-folder} from the Phase Folder Mapping table in ea-artifact.md
- Pre-populate fields with any available data from:
engagement.json (name, sponsor, organisation)- Requirements register (relevant requirements)
- Uploaded documents (via
ea-document-ingestion)
- Previous interview notes
- Leave unpopulated fields as
{{field_name}} placeholders
- Add the artifact entry to
engagement.json under artifacts[]
- Do NOT fill placeholder sections with AI-generated content unless clearly marked as a draft
Interview-Driven Population
When populating an artifact via interview:
- Extract the questions from the template (fields marked
{{...}})
- Load them into the
ea-interviewer agent
- For each question, offer:
- A default answer where one is reasonable (clearly marked)
- Option to skip (
⚠️ Not answered)
- Option to mark N/A (
➖ Not applicable)
- Write confirmed answers directly into the artifact
- Save dated interview notes to
interviews/
Guidance Text Policy
Guidance text in templates serves two purposes:
- Authoring guide — explains what the section should contain
- Quality check — reminds the author of TOGAF standards
Guidance text is ALWAYS wrapped in <!-- GUIDANCE: ... --> HTML comments.
It must NEVER be removed automatically — the author decides whether to keep or remove it.
It does NOT appear in Word or HTML exports (HTML comments are not rendered).
Readability Guidelines
Apply these rules when creating, populating, or reviewing artifact content:
- Tables are for summary/index only. Keep tables to ≤ 8 columns. If a table would need more than 8 columns to capture all relevant fields, move the overflow to a detail file (see below).
- Narrative before tables. Every table-heavy section should be preceded by 1–3 sentences of prose that summarise what the reader is about to see — the top finding, the dominant pattern, or the key implication. Avoid leading with a table and no context.
- Split large tables. For sections with more than 10 rows, split by a natural dimension (e.g. High / Medium / Low priority, In Scope / Out of Scope, Business / Technical) to aid scanning.
- Avoid redundant columns. Do not repeat information that is already expressed by the ID, the section heading, or the row label. Each column should add unique information.
- Detail on demand. For items that require extended narrative, rationale, risks, costs, issues, concerns, impact, or alternatives, link to a detail file rather than expanding the table inline.
Item Detail Files
Table rows in EA artifacts may optionally link to a companion detail file containing extended content. This keeps tables scannable while providing depth on demand.
Convention:
- Detail files live at
artifacts/details/{ID}.md — one engagement-wide directory
- Link from table: add a
Details column with [→](../details/{ID}.md) when a detail file exists, or — when it does not
- Create with:
/ea-detail new {ID} [{artifact-id}]
- Full convention:
references/detail-file-convention.md
When to create a detail file:
- Item was contested, challenged in a grill, or raised stakeholder concerns
- Item has non-trivial cost, risk, or dependency implications
- Stakeholder asks "why?" or "what about X?" about a specific row
- Item has alternatives that were considered but rejected
Context loading: Skills that use Scope A (ea-grill, ea-review, ea-interview) automatically load linked detail files and cite them as [detail: {ID}]. See skills/ea-engagement-lifecycle/references/context-loading.md.
Additional Resources
references/artifact-descriptions.md — Purpose, audience, and contents of each TOGAF artifactreferences/template-authoring-guide.md — How to write and extend templatesreferences/ea-concepts.md — Canonical definitions and TOGAF/ArchiMate alignment for Principle, Goal, Objective, Strategy, Plan, and Risk. Load this when concept confusion is detected during interviews or artifact population.references/compliance-check.md — Compliance rules (Tier 1/2/3), check procedure, remediation actions for Option 1 (achieve compliance) and Option 2 (accept as-is with defaults). Load this whenever an artifact is opened for interview, review, or viewing.references/detail-file-convention.md — Detail file pattern: location, frontmatter, sections, linking rules, and how skills load and cite detail files.
