6.5 KiB
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:
// 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
# 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
## 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:
# 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
## 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:
## 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:
## 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:
- Project CLAUDE.md (
./CLAUDE.md) - For project-specific behavior - Global CLAUDE.md (
~/.claude/CLAUDE.md) - For all projects
Implementation:
# 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:
## 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