gh-cskiro-claudex/skills/planning/ascii-diagram-creator/workflow/phase-4-output-integration.md

# Phase 4: Output & Integration

**Purpose**: Provide multiple output formats and integrate diagrams into the user's workflow for maximum value.

**Execute after diagram refinement is complete.**

## 1. Output Format Options

After generating the ASCII diagram, offer these output options:

### ASCII (Default)
The standard terminal-compatible format already generated.

### Mermaid Export

Convert the ASCII diagram to Mermaid syntax for graphical rendering:

```javascript
// Example conversion for Architecture diagram
graph TD
    subgraph "Application Layer"
        A[app/routes] --> B[features/domains]
        B --> C[shared/common]
    end

    subgraph "Feature Layer"
        B --> D[components]
        B --> E[hooks]
        B --> F[api]
    end
```

**Conversion rules**:
| ASCII Element | Mermaid Equivalent |
|---------------|-------------------|
| `┌─────┐` Box | `[Label]` node |
| `──►` Arrow | `-->` connection |
| `◄─►` Bidirectional | `<-->` connection |
| Nested boxes | `subgraph` |
| `✓` Status | `:::done` class |
| `⏳` Pending | `:::pending` class |

**Ask user**: "Would you like me to also generate a Mermaid version for graphical rendering?"

---

## 2. Git-Aware Staleness Detection

Check if existing diagrams in the project are stale based on git history:

### Detection Logic

```bash
# Find diagram files with metadata
grep -r "diagram-meta" docs/architecture/ --include="*.md" -l

# For each diagram, extract source-patterns and check git log
git log --since="30 days ago" --name-only -- "src/features/*"
```

### Staleness Report

```markdown
## Diagram Staleness Report

| Diagram | Last Verified | Source Changes | Status |
|---------|---------------|----------------|--------|
| `docs/architecture/auth-flow.md` | 2025-10-15 | 12 files changed | ⚠️ STALE |
| `docs/architecture/api-layer.md` | 2025-11-20 | 0 files changed | ✓ Current |
| `docs/architecture/features.md` | 2025-09-01 | 45 files changed | 🔴 OUTDATED |

### Recommended Actions
1. Re-verify `auth-flow.md` - auth module had significant changes
2. Update `features.md` - multiple new features added since last update
```

**Proactive check**: Run this detection when user asks about architecture or before major changes.

---

## 3. PR Template Integration

Automatically suggest or insert diagrams into PR descriptions:

### Detection

Check for existing PR templates:
```bash
# Common PR template locations
ls -la .github/PULL_REQUEST_TEMPLATE.md
ls -la .github/pull_request_template.md
ls -la docs/PULL_REQUEST_TEMPLATE.md
```

### Integration Options

**Option A: Suggest inclusion in PR body**
```markdown
## Architecture Impact

<!-- Generated by ascii-diagram-creator -->
```
[Insert generated diagram here]
```

This change affects the following components:
- Feature: auth
- Routes: /login, /logout, /refresh
```

**Option B: Auto-append to PR template**

If user agrees, add a section to their PR template:

```markdown
## Architecture Diagram (if applicable)

<!--
If this PR changes architecture, include a diagram:
- Use ascii-diagram-creator skill
- Show before/after for refactoring
- Show data flow for new features
-->
```

**Ask user**: "Would you like me to add this diagram to your PR description or update your PR template?"

---

## 4. CLAUDE.md Directive Setup

**IMPORTANT**: After completing the diagram, ask the user if they want to set up proactive diagram suggestions.

### Offer Prompt

> "Would you like me to add a directive to your CLAUDE.md so I proactively offer architecture diagrams when you're planning features, migrations, or refactoring?"

### If User Accepts

Add this directive to their project or global CLAUDE.md:

```markdown
## Proactive Skill Directives

### ASCII Diagram Creator

**Proactively offer architecture diagrams** when the user:
- Creates a feature branch (`feature/*`)
- Asks "how should I structure...", "what's the architecture for...", or "show me how X connects"
- Plans a migration, refactoring, or major restructuring
- Needs to communicate system changes in a PR description
- Mentions "visualize", "diagram", "show the flow", or "illustrate"

**Auto-trigger phrases**:
- "new feature", "planning", "architecture", "how should I structure"
- "before and after", "migration plan", "refactoring"
- "PR description", "explain to the team"

**Response pattern**:
1. Use auto-discovery to scan codebase (features, routes, dependencies)
2. Select appropriate template (Bulletproof React, Next.js, Express, Monorepo)
3. Generate diagram with versioning metadata
4. Offer Mermaid export and PR integration
5. Suggest placement: `docs/architecture/` or PR description

**Example proactive offer**:
> "I notice you're planning a new feature. Would you like me to create an architecture diagram showing the current system structure and where this feature will integrate? This can help with planning and serve as documentation in your PR."
```

### Placement Options

Ask user where to add the directive:

1. **Project CLAUDE.md** (`./CLAUDE.md`) - For project-specific behavior
2. **Global CLAUDE.md** (`~/.claude/CLAUDE.md`) - For all projects

**Implementation**:
```bash
# Check if directive already exists
grep -q "ASCII Diagram Creator" ~/.claude/CLAUDE.md && echo "Already configured"

# If not, append to file
cat >> ~/.claude/CLAUDE.md << 'EOF'
[directive content]
EOF
```

---

## 5. Output Summary

After completing all options, provide a summary:

```markdown
## Diagram Generation Complete

**Outputs Created**:
- ✓ ASCII diagram (80-char width, terminal-compatible)
- ✓ Mermaid export (for graphical rendering)
- ✓ Diagram metadata (staleness tracking enabled)

**Integration**:
- ✓ Added to PR description
- ✓ CLAUDE.md directive configured (global)

**Staleness Tracking**:
- Source patterns: `src/features/auth/*`, `src/app/routes/auth/*`
- Stale after: 30 days
- Next verification: 2025-12-23

**Recommended Location**:
Save to: `docs/architecture/auth-flow.md`
```

---

## Quick Reference

### User Prompts for This Phase

| User Says | Action |
|-----------|--------|
| "export to mermaid" | Generate Mermaid syntax |
| "check for stale diagrams" | Run staleness detection |
| "add to PR" | Insert in PR description |
| "set up auto-suggestions" | Configure CLAUDE.md directive |
| "save this diagram" | Write to docs/architecture/ |

### Output Format Decision Tree

```
Is user creating PR?
├─ Yes → Offer PR integration
└─ No → Is user planning feature?
         ├─ Yes → Offer CLAUDE.md directive
         └─ No → Offer Mermaid export for docs
```