ADR Graph-Easy Architect

Create comprehensive ASCII architecture diagrams for Architecture Decision Records (ADRs) using graph-easy. Pure text output with automatic layout - no image rendering required.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• Writing new ADR that involves architectural changes
• ADR describes migration, integration, or system changes
• User asks for visual representation of a decision
• Existing ADR diagram needs review or update

Preflight Check

Ensure graph-easy is installed and functional before rendering diagrams.

Full setup instructions: Preflight Setup

Quick verify:

echo "[Test] -> [OK]" | graph-easy --as=boxart &>/dev/null && echo "✓ graph-easy ready"

DSL Quick Reference

Full syntax with examples, node styling, edge styles, and emoji rules: DSL Syntax Reference

Essential Syntax

[Node]                          # Node
[A] -> [B]                      # Edge
[A] -- label --> [B]            # Labeled edge
[A] <-> [B]                     # Bidirectional
( Group: [Node A] [Node B] )    # Group/container
[id] { label: "Display"; }     # Custom label

Flow Direction (MANDATORY)

graph { flow: south; }   # Top-to-bottom (architecture, decisions)
graph { flow: east; }    # Left-to-right (pipelines, sequences)

Graph Label (MANDATORY: EVERY diagram MUST have emoji + title)

WARNING: This is the most commonly forgotten requirement. Diagrams without labels are invalid.

Correct:

graph { label: "🔄 Database Migration"; flow: south; }
[Old DB] -> [New DB]

Anti-Pattern (INVALID):

graph { flow: south; }
[Old DB] -> [New DB]

Missing

label:

graph { label: "emoji ..."; }

Emoji Selection (for graph labels ONLY - never inside nodes)

Node & Edge Styling Summary

{ shape: rounded; }

{ border: double; }

{ border: bold; }

{ border: dotted; }

->

..>

==>

-- label -->

Character Safety

• Graphical emojis INSIDE nodes: NEVER (breaks box alignment)
• Unicode symbols inside nodes (checkmark, cross, warning): OK (single-width)
• ASCII markers inside nodes ([x] [+] [!]): ALWAYS safe
• Graphical emojis in

  graph { label: }

  : OK

Full symbol reference: Monospace-Safe Symbols

Common Diagram Patterns

Migration (Before -> After)

graph { flow: south; }
[Before] -- migrate --> [After]

Multi-Component System

graph { flow: south; }
[A] -> [B] -> [C]
[B] -> [D]

Pipeline (Left-to-Right)

graph { flow: east; }
[Input] -> [Process] -> [Output]

Decision with Options

graph { flow: south; }
[Decision] -> [Option A]
[Decision] -> [Option B]

Grouped Components

( Group:
  [Component 1]
  [Component 2]
)
[External] -> [Component 1]

Bidirectional Flow

[Client] <-> [Server]
[Server] -> [Database]

More patterns by ADR type: Diagram Examples

Rendering

Command (MANDATORY: Always use boxart)

graph-easy --as=boxart << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

Never use

--as=ascii

+--+

┌──┐

Validation Workflow

# 1. Write DSL to heredoc
# 2. Render with boxart
# 3. Review output
# 4. Iterate if needed
# 5. Copy final ASCII to ADR

Embedding in ADR

Every rendered diagram MUST include a collapsible

<details>

Required format:

```
┌───────┐     ┌──────┐
│ Build │ --> │ Test │
└───────┘     └──────┘
```

<details>
<summary>graph-easy source</summary>

```
graph { label: "🚀 Pipeline"; flow: east; }
[Build] -> [Test]
```

</details>

The

<details>

Mandatory Checklist (Before Rendering)

Graph-Level (MUST have)

• graph { label: "🚀 Title"; }

  - semantic emoji + title (MOST FORGOTTEN - check first!)

• graph { flow: south; }

  or

  graph { flow: east; }

  - explicit direction
• Command uses

  --as=boxart

  - NEVER

  --as=ascii

Embedding (MUST have - non-negotiable)

• <details>

  block with source - EVERY diagram MUST have collapsible source code block
• Format: rendered diagram in

  ```

  block, followed by

  <details><summary>graph-easy source</summary>

  with source
• Never commit a diagram without its reproducible source

Node Styling (Visual hierarchy)

• Start/end nodes:

  { shape: rounded; }

  - entry/exit points
• Critical/important nodes:

  { border: double; }

  or

  { border: bold; }

• Optional/skippable nodes:

  { border: dotted; }

• Long labels use

  \n

  for multiline - max ~15 chars per line

Edge Styling (Semantic meaning)

• Main/happy path:

  ->

  solid arrow
• Conditional/alternate:

  ..>

  dotted arrow
• Emphasized/critical:

  ==>

  bold arrow
• Edge labels are SHORT (1-3 words):

  -- YES -->

  ,

  -- error -->

Character Safety (Alignment)

• NO graphical emojis inside nodes (break alignment)
• Unicode symbols OK inside nodes (single-width)
• ASCII markers ALWAYS safe ([x] [+] [!] [OK])
• Graphical emojis ONLY in

  graph { label: "..."; }

  title

Structure (Organization)

• Groups

  ( Name: ... )

  used for logical clustering when 4+ related nodes
• Node IDs short, labels descriptive:

  [db] { label: "PostgreSQL"; }

• No more than 7-10 nodes per diagram (split if larger)

Success Criteria

Correctness

1. Parses without error - graph-easy accepts the DSL
2. Renders cleanly - no misaligned boxes or broken lines
3. Matches content - all key elements from description represented
4. Source preserved (MANDATORY) - EVERY diagram has

   <details>

   block with source

Aesthetics

1. Uses boxart - clean Unicode lines, not ASCII

   +--+

2. Visual hierarchy - start/end rounded, important bold/double, optional dotted
3. Consistent styling - same border style = same semantic meaning throughout
4. Readable labels - multiline with

   \n

   , no truncation
5. Clear flow - direction matches natural reading (top-down or left-right)

Comprehensiveness

1. Semantic emoji in title - emoji chosen to match diagram purpose
2. Legend if needed - multiline title with

   \n

   for complex diagrams
3. Edge semantics - solid=normal, dotted=conditional, bold=critical
4. Logical grouping - related nodes in

   ( Group: ... )

   containers

Troubleshooting

command not found

--as=ascii

--as=boxart

graph { label: "Title"; flow: south; }

graph { flow: south; }

flow: east

Resources

• Graph::Easy on CPAN
• Graph::Easy Manual
• Graph::Easy GitHub

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.