Compound Diagram

---
description: "Audit and fix draw.io diagram quality — detects edge routing issues, overlapping shapes, missing anchors"
argument-hint: "[path-or-glob] [instructions] — e.g. docs/diagrams/checkout-flow.drawio fix edge routing"
allowed-tools:
  - Bash(python3:*)
  - Bash(drawio:*)
  - Bash(ls:*)
  - Bash(wc:*)
  - Bash(mkdir:*)
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

# Compound Diagram

Audit and fix draw.io diagram quality. Detects edge routing issues (missing anchors, edges crossing through shapes), overlapping shapes, and text overflow. Applies mechanical fixes first, then spawns agents for remaining judgment calls.

<progress>
- [ ] Step 1: Discover diagrams
- [ ] Step 2: Programmatic XML audit
- [ ] Step 2b: Logic verification (skip if user only asked to fix routing)
- [ ] Step 3: User decides scope (skip if user already said what to do)
- [ ] Step 4: Mechanical fixes (skip if user only asked to verify)
- [ ] Step 5: Agent fixes for remaining issues (skip if user only asked to verify)
- [ ] Step 6: Re-audit + visual verification (skip if user only asked to verify)
- [ ] Step 7: Present results
</progress>

<purpose>
You are the diagram quality orchestrator. You run programmatic audits on draw.io XML to detect issues that visual inspection misses, apply mechanical fixes via Python scripts, spawn agents for the harder fixes, and verify everything before declaring done.
</purpose>

<constraints>
**Hard rules:**
- Never delete or regenerate diagrams — only fix routing and layout
- Default: only fix geometry and edge routing
- If logic verification finds drift from source, update shape content to match
- If user instructions explicitly request content/style changes, follow them
- When adding/removing shapes, maintain the diagram's existing color palette and style
- Always re-audit after fixes to verify improvement
- Always re-export PNGs after XML changes
- Visual verification with Read tool is mandatory before declaring any diagram fixed
- Maximum 3 fix iterations per diagram — if not clean after 3, flag for manual review
</constraints>

<antipatterns>
**Avoid:**
- Widening shapes for text overflow — draw.io wraps text, widening causes overlaps
- Trusting auto-routing — `edgeStyle=none` with no anchors = straight line through shapes
- Fixing anchors without checking if the fix creates new crossings
- Rubber-stamping PNGs at thumbnail resolution — zoom into edge routing areas
- Spawning agents for issues a Python script can fix mechanically
</antipatterns>

<knowledge>
## Draw.io XML Format

**Shapes:** `<mxCell vertex="1">` with `<mxGeometry x y width height>`
**Edges:** `<mxCell edge="1" source="id" target="id">` with style string
**Style format:** semicolon-separated `key=value` pairs, e.g. `edgeStyle=orthogonalEdgeStyle;exitX=0.5;exitY=1`

## Anchor Coordinate System

`exitX/exitY` and `entryX/entryY` are normalized 0-1:
- `(0, 0.5)` = left center
- `(1, 0.5)` = right center
- `(0.5, 0)` = top center
- `(0.5, 1)` = bottom center

**Anchor calculation from geometry:**
- Target below source → `exitX=0.5, exitY=1, entryX=0.5, entryY=0`
- Target right of source → `exitX=1, exitY=0.5, entryX=0, entryY=0.5`
- Use dominant axis (vertical vs horizontal displacement) to choose

## Waypoint Format

```xml
<mxGeometry relative="1" as="geometry">
  <Array as="points">
    <mxPoint x="N" y="N" />
  </Array>
</mxGeometry>
```

## CLI Limitation

`cli-anything-drawio connect add` doesn't expose anchor parameters. Must use either:
1. `cli-anything-drawio connect style EDGE_ID exitX VALUE` after creation
2. Direct XML editing of the style string

## Common Issues and Fixes

| Issue | Cause | Fix |
|-------|-------|-----|
| Edge through shape | `edgeStyle=none` + no anchors | Change to `orthogonalEdgeStyle` + add anchors |
| Bidirectional overlap | Two edges same pair, default anchors | Offset: `exitY=0.25` forward, `exitY=0.75` return |
| Self-loop invisible | source == target, no curve | Add `curved=1` + explicit exit/entry on same side |
| Text overflow | Long text in narrow shape | Do NOT widen — draw.io wraps text. Only flag as info. |
| Shape overlap | Adjacent shapes pushed together | Push apart along shortest overlap axis + 20px gap |
| Container false positive | Large shape containing children | Skip if area ratio >4x and overlap >50% of smaller |
</knowledge>

## Input

Read `$ARGUMENTS` as a natural-language message. Understand what the user wants:

- **Which diagrams?** A specific file, a directory, a name reference ("the auth diagram"), or all of them. Default: `docs/diagrams/` (all diagrams).
- **What to do?** The user is asking to verify, fix, or both. If blank, run the full pipeline (audit + verify + ask).

The user's words drive the flow:
- Asking to **check, verify, or review** → run audit + logic verification, present findings, ask before fixing
- Asking to **fix, clean up, or compound** → run audit, apply fixes, verify results
- Asking for **both** → verify first, then fix
- **Blank** → same as "compound all diagrams" — full pipeline

## Process

### Step 1: Discover Diagrams

```bash
ls $TARGET 2>/dev/null | wc -l
```

List all matching `.drawio` files. Report count to user.

### Step 2: Programmatic XML Audit

Run the audit script:

```bash
python3 skills/compound-diagram/scripts/audit-diagrams.py $TARGET 2>&1
```

If `skills/compound-diagram/scripts/audit-diagrams.py` does not exist, create it using the reference implementation (see Knowledge section for XML format details). The script must check:

1. **Unanchored edges** — missing `exitX/exitY` or `entryX/entryY` in style
2. **Edge-through-shape** — straight-line path (source center → target center) intersects unrelated shape bounding box. Only for `edgeStyle=none` or missing edgeStyle.
3. **Overlapping shapes** — bounding box intersection >0px², excluding: text labels, full containment, container heuristic (area ratio >4x + overlap >50% of smaller shape)
4. **Bidirectional edge overlap** — same source↔target pair in both directions, both unanchored
5. **Self-loops without curve** — source == target but no `curved` in style
6. **Text overflow** — estimated text width > shape width (warn only, do not fix)

**Severity classification:**
- **Critical:** >5 errors
- **Moderate:** 1-5 errors or >5 warnings
- **Clean:** 0 errors and ≤5 warnings

Present the audit table to the user.

### Step 2b: Logic Verification

Skip this step if the user only asked to fix routing/layout (not checking logic).

Spawn one Agent **per diagram, in parallel** (all Agent calls in a single turn). Each agent handles its own source identification — the orchestrator does not read XML or search for sources inline.

```
Agent(
  subagent_type="orc:drawio",
  description="Verify {diagram_name} logic",
  prompt="
    TASK: Verify diagram accuracy (read-only — do NOT modify the diagram).

    Verify that the draw.io diagram at {file_path} accurately represents
    the code or process it documents.

    1. IDENTIFY THE SOURCE: Read the .drawio XML. Look at:
       - The title/header shape (usually largest text-only shape near top)
       - The filename (e.g., 'checkout-flow.drawio' likely documents a checkout process)
       - Shape labels that reference specific files, functions, or commands
       Then search the codebase with Grep/Glob to find the source file(s)
       this diagram is supposed to represent.

    2. If no source found: report { source: null, reason: 'could not identify' }
       and stop.

    3. COMPARE: Read both the source file(s) and the diagram XML. Check:
       - Are all steps/states/decisions in the source represented as shapes?
       - Are connections (edges) correct — does the flow match the actual logic?
       - Are there shapes in the diagram for steps that no longer exist in the source?
       - Do labels match the actual names/descriptions in the source?

    4. REPORT (output this exactly):
       Source: {path(s) identified}
       Matches: {list of correctly represented elements}
       Missing: {steps/states in source but not in diagram}
       Stale: {shapes in diagram for things removed from source}
       Wrong flow: {edges that don't match actual control flow}
  ",
  run_in_background=true
)
```

Wait for all agents to complete. Collect results into `$LOGIC_FINDINGS`.

**Always present logic findings to the user** before any fixes. Format as a table:

| Diagram | Source | Missing | Stale | Wrong Flow |
|---------|--------|---------|-------|------------|
| name | path | count | count | count |

If the user only asked to verify/check: present findings and ask if they want to proceed to fixes.
Otherwise: present findings, then continue to Step 3.

### Step 3: User Decides Scope

Skip if the user already told us what to fix.

AskUserQuestion:
- "How should I proceed?" (show XML audit + logic findings summary above)
- Options:
  - "Fix all (routing + logic)" — fix every diagram with any issues
  - "Fix routing only" — fix XML issues (anchors, overlaps) but don't change diagram content
  - "Fix logic only" — update shapes/edges to match source, don't touch routing
  - "Pick diagrams" — let user select specific diagrams
  - "Report only" — stop here, no fixes

If "Report only": present the full audit + logic report and stop.

### Step 4: Mechanical Fixes

Run the fix scripts in sequence:

**Pass 1 — Anchoring and rerouting:**
```bash
python3 skills/compound-diagram/scripts/fix-diagrams.py $TARGET
```

This script:
- Adds `exitX/exitY/entryX/entryY` to all unanchored edges (computed from source/target geometry)
- Converts straight-line edges that cross shapes to `edgeStyle=orthogonalEdgeStyle`
- Does NOT widen shapes (text overflow is cosmetic only)

**Pass 2 — Overlap resolution:**
```bash
python3 skills/compound-diagram/scripts/fix-overlaps.py $TARGET
```

This script:
- Pushes overlapping shapes apart (minimum 20px gap)
- Reroutes any remaining straight-line edges through shapes
- Runs up to 3 cascade iterations to resolve chain reactions

If either script does not exist, create it following the patterns in the Knowledge section.

**Re-audit after mechanical fixes:**
```bash
python3 skills/compound-diagram/scripts/audit-diagrams.py $TARGET 2>&1
```

Report improvement (before vs after error counts).

### Step 5: Agent Fixes for Remaining Issues

If any diagrams still have errors after mechanical fixes:

For each diagram with remaining errors, spawn an Agent:

```
Agent(
  subagent_type="orc:drawio",
  description="Fix {diagram_name} routing",
  prompt="
    Fix remaining draw.io diagram issues in {file_path}.

    Remaining issues:
    {list of specific issues from audit: edge IDs, shape IDs, issue type}

    User instructions: {what the user asked for, or "None — fix audit findings only"}
    Logic drift: {findings from Step 2b for this diagram, or "None — diagram matches source"}

    Fix approach:
    1. Read the .drawio XML
    2. For edge crossings: add waypoints (<Array as='points'><mxPoint x='N' y='N'/></Array>)
       inside the edge's <mxGeometry> to route around the blocking shape
    3. For shape overlaps: move the right/bottom shape further away (adjust mxGeometry x or y)
    4. Maintain 30px minimum clearance from unrelated shapes
    5. If logic findings indicate missing steps or wrong flow:
       - Add new shapes for missing steps (matching the diagram's existing color scheme)
       - Remove shapes for steps that no longer exist in the source
       - Fix edge connections to match the actual process flow
       - Re-anchor and re-route after content changes
    6. Write the fixed XML back
    7. Re-export PNG: drawio --export --format png --scale 2 --output {png_path} {drawio_path}
    8. Read the PNG to verify the fix visually
    9. If issues remain, iterate (max 3 attempts)

    Default: only fix geometry and edge routing.
    If logic drift found: update shape content to match source.
    If user instructions request content/style changes: follow them.
    When adding/removing shapes: maintain the diagram's existing color palette and style.
  ",
  run_in_background=true
)
```

Batch agents in groups of 4-5 to avoid overwhelming the system.

### Step 6: Re-audit + Visual Verification

After all fixes (mechanical + agent):

```bash
python3 skills/compound-diagram/scripts/audit-diagrams.py $TARGET 2>&1
```

All diagrams should show 0 errors. If any remain, flag for manual review.

Re-export any diagrams that were fixed by agents:
```bash
drawio --export --format png --scale 2 --output {png_path} {drawio_path}
```

Visual spot-check: Read 3-5 PNGs of previously-critical diagrams to verify edge routing looks correct.

### Step 7: Present Results

Summary table:

| Diagram | Before | After | Status |
|---------|--------|-------|--------|
| name | 11E 47W | 0E 0W | Fixed |

Report:
- Total diagrams audited
- Total fixes applied (anchored, rerouted, overlaps resolved)
- Any diagrams flagged for manual review
- Paths to re-exported PNGs

## File Ownership

| File | Access | Purpose |
|------|--------|---------|
| `skills/compound-diagram/scripts/audit-diagrams.py` | Read/Create | Programmatic audit script |
| `skills/compound-diagram/scripts/fix-diagrams.py` | Read/Create | Mechanical fix script (anchors + rerouting) |
| `skills/compound-diagram/scripts/fix-overlaps.py` | Read/Create | Overlap resolution script |
| `docs/diagrams/*.drawio` | Read/Write | Diagram source files |
| `docs/diagrams/*.png` | Write | Re-exported diagram images |

## Completion Criteria

- [ ] All diagrams audited with programmatic checks
- [ ] Mechanical fixes applied (anchoring, rerouting)
- [ ] Overlap resolution applied
- [ ] Re-audit shows 0 critical issues
- [ ] PNGs re-exported at 2x scale
- [ ] Visual spot-check passed on ≥3 diagrams
- [ ] Summary table presented to user