Initial commit

2025-11-30 08:38:26 +08:00
commit 41d9f6b189
304 changed files with 98322 additions and 0 deletions
--- a/skills/mapping-visualization-scaffolds/resources/evaluators/rubric_mapping_visualization_scaffolds.json
+++ b/skills/mapping-visualization-scaffolds/resources/evaluators/rubric_mapping_visualization_scaffolds.json
@@ -0,0 +1,128 @@
+{
+  "criteria": [
+    {
+      "name": "Completeness",
+      "description": "All critical nodes and relationships are identified and documented",
+      "levels": {
+        "5": "All critical nodes present, all significant relationships documented, appropriate groupings/layers defined, legend provided if needed, metadata complete",
+        "4": "Most critical nodes and relationships present, minor gaps in groupings or metadata, legend present if needed",
+        "3": "Key nodes and relationships present but some secondary elements missing, groupings incomplete, metadata partially complete",
+        "2": "Several critical nodes or relationships missing, groupings absent or unclear, metadata sparse",
+        "1": "Major gaps in nodes/relationships, no groupings, minimal or no metadata"
+      }
+    },
+    {
+      "name": "Clarity",
+      "description": "The visualization is understandable, well-organized, and uses consistent notation",
+      "levels": {
+        "5": "Crystal clear visualization, consistent naming/notation throughout, logical organization, no ambiguity in relationships, directionality explicit",
+        "4": "Clear visualization with minor inconsistencies, mostly logical organization, directionality usually clear",
+        "3": "Generally clear but some confusing elements, some notation inconsistencies, directionality sometimes ambiguous",
+        "2": "Difficult to follow in places, inconsistent notation, unclear directionality, poor organization",
+        "1": "Confusing or incomprehensible, no clear notation system, directionality absent"
+      }
+    },
+    {
+      "name": "Accuracy",
+      "description": "Relationships and dependencies are correctly identified and represented",
+      "levels": {
+        "5": "All relationships accurately represent reality, correct directionality, relationship types properly labeled, no errors",
+        "4": "Relationships mostly accurate, minor errors in directionality or labeling, types generally correct",
+        "3": "Some inaccurate relationships, occasional errors in directionality, relationship types sometimes incorrect",
+        "2": "Multiple inaccurate relationships, frequent errors, relationship types often wrong",
+        "1": "Many inaccurate or incorrect relationships, unreliable representation"
+      }
+    },
+    {
+      "name": "Format Appropriateness",
+      "description": "The chosen visualization format matches the complexity and nature of the system",
+      "levels": {
+        "5": "Perfect format choice for the relationship patterns, complexity level appropriate, scalable structure, right level of detail",
+        "4": "Good format choice with minor suboptimal aspects, generally appropriate complexity and detail",
+        "3": "Acceptable format but could be better, some mismatch between format and content, detail level inconsistent",
+        "2": "Poor format choice for the content, significant mismatch, wrong complexity level, inappropriate detail",
+        "1": "Completely inappropriate format, impossible to follow, wrong complexity level"
+      }
+    },
+    {
+      "name": "Scoping",
+      "description": "Clear boundaries defined, appropriate level of detail, purpose explicitly stated",
+      "levels": {
+        "5": "Clear purpose statement, explicit scope boundaries (what's in/out), appropriate detail level for audience, constraints stated",
+        "4": "Purpose stated, scope mostly clear, generally appropriate detail level, most constraints noted",
+        "3": "Purpose vague or implicit, scope somewhat unclear, detail level sometimes inappropriate, few constraints stated",
+        "2": "Purpose unclear, scope poorly defined, detail level often wrong, constraints not stated",
+        "1": "No clear purpose, undefined scope, inappropriate detail level, no constraints"
+      }
+    },
+    {
+      "name": "Visual Organization",
+      "description": "Layout facilitates understanding, uses grouping effectively, avoids visual clutter",
+      "levels": {
+        "5": "Excellent layout, effective use of grouping/layering, clean visual hierarchy, no 'hairball' effect, scannable at a glance",
+        "4": "Good layout with minor issues, grouping mostly effective, generally scannable, minimal clutter",
+        "3": "Acceptable layout but could improve, grouping present but weak, somewhat cluttered, harder to scan",
+        "2": "Poor layout, ineffective grouping, cluttered visualization, difficult to scan, confusing structure",
+        "1": "Chaotic layout, no effective grouping, severe clutter, impossible to scan, no structure"
+      }
+    },
+    {
+      "name": "Actionability",
+      "description": "The map enables decisions, understanding, or actions based on insights",
+      "levels": {
+        "5": "Clearly enables specific decisions/actions, insights explicitly highlighted, critical paths/bottlenecks identified, recommendations provided",
+        "4": "Enables decisions with some interpretation, key insights noted, some critical elements highlighted",
+        "3": "Somewhat useful for decisions but requires significant interpretation, few insights noted, limited highlighting",
+        "2": "Difficult to derive actions from the map, insights not highlighted, unclear what to do with it",
+        "1": "Provides no actionable value, no insights, unclear purpose or application"
+      }
+    },
+    {
+      "name": "Documentation Quality",
+      "description": "Adequate descriptions, legend provided if needed, assumptions/limitations stated",
+      "levels": {
+        "5": "Comprehensive node/relationship descriptions, legend present if >3 types, assumptions stated, limitations noted, insights documented",
+        "4": "Good descriptions, legend present if needed, most assumptions stated, some limitations noted",
+        "3": "Basic descriptions, legend missing when needed, few assumptions stated, limitations not noted",
+        "2": "Sparse descriptions, no legend when needed, assumptions not stated, no limitations noted",
+        "1": "Minimal or no descriptions, no legend, no documentation of assumptions or limitations"
+      }
+    }
+  ],
+  "scale": 5,
+  "passing_threshold": 3.5,
+  "scoring_guidance": {
+    "overall_minimum": "Average score must be ≥ 3.5 across all criteria",
+    "critical_criteria": [
+      "Completeness",
+      "Accuracy",
+      "Clarity"
+    ],
+    "critical_threshold": "Critical criteria must each be ≥ 3.0 (even if average is ≥ 3.5)",
+    "improvement_priority": "If below threshold, prioritize improvements in order: Completeness → Accuracy → Clarity → Format Appropriateness → others"
+  },
+  "common_failure_modes": [
+    "Too many nodes (>50) without splitting into multiple focused maps",
+    "Hairball diagram with crossing lines and unclear relationships",
+    "Inconsistent notation or naming conventions",
+    "Missing critical dependencies or relationships",
+    "Wrong format choice (e.g., tree diagram for network, list for complex graph)",
+    "No grouping/layering for complex systems (>20 nodes)",
+    "Ambiguous directionality (unclear which way relationships flow)",
+    "No legend when multiple relationship types present",
+    "Mixing abstraction levels in single map",
+    "Undefined scope or purpose"
+  ],
+  "excellence_indicators": [
+    "Target audience can understand without explanation",
+    "Critical paths or bottlenecks visually highlighted",
+    "Appropriate grouping reduces visual complexity",
+    "Consistent notation throughout",
+    "Clear purpose and scope stated upfront",
+    "Insights section highlights key findings",
+    "Multiple visualization formats considered, best one chosen",
+    "Scalable structure (can add nodes without breaking layout)",
+    "Validation with stakeholders or SMEs completed",
+    "Legend present when needed, absent when not"
+  ]
+}
--- a/skills/mapping-visualization-scaffolds/resources/methodology.md
+++ b/skills/mapping-visualization-scaffolds/resources/methodology.md
@@ -0,0 +1,491 @@
+# Advanced Mapping & Visualization Methodology
+
+## Workflow
+
+Copy this checklist and track your progress:
+
+```
+Advanced Mapping Progress:
+- [ ] Step 1: Assess complexity and scope
+- [ ] Step 2: Choose mapping strategy
+- [ ] Step 3: Select tools and formats
+- [ ] Step 4: Execute mapping process
+- [ ] Step 5: Validate with stakeholders
+- [ ] Step 6: Iterate and refine
+```
+
+**Step 1: Assess complexity and scope**
+
+Evaluate system size (nodes/relationships), stakeholder diversity, and update frequency. See [1. Complexity Assessment](#1-complexity-assessment) for decision criteria on when advanced techniques are needed.
+
+**Step 2: Choose mapping strategy**
+
+Select from single comprehensive map, multi-map hierarchy, or modular view-based approach based on complexity. See [2. Mapping Strategies for Scale](#2-mapping-strategies-for-scale) for guidance.
+
+**Step 3: Select tools and formats**
+
+Choose between manual (text/markdown), semi-automated (Mermaid), or visual tools (draw.io, GraphViz) based on collaboration needs and update frequency. See [3. Tool Selection](#3-tool-selection) for criteria.
+
+**Step 4: Execute mapping process**
+
+Apply chosen strategy using collaborative or individual workflows. See [4. Execution Patterns](#4-execution-patterns) for facilitation techniques and [5. Advanced Layout Techniques](#5-advanced-layout-techniques) for optimization.
+
+**Step 5: Validate with stakeholders**
+
+Conduct structured review sessions using [6. Validation Approaches](#6-validation-approaches) to ensure accuracy and completeness.
+
+**Step 6: Iterate and refine**
+
+Incorporate feedback and maintain maps over time using [7. Maintenance and Evolution](#7-maintenance-and-evolution) patterns.
+
+---
+
+## 1. Complexity Assessment
+
+Use this framework to determine if advanced methodology is needed:
+
+### Simple Case (Use template.md)
+- **Nodes**: < 20
+- **Relationships**: Mostly one type
+- **Stakeholders**: 1-2 people
+- **Change frequency**: One-time or rare
+- **Structure**: Clear hierarchy or simple network
+→ **Action**: Follow [template.md](template.md), use Simple List or Tree format
+
+### Moderate Case (Consider this methodology)
+- **Nodes**: 20-50
+- **Relationships**: 2-4 types
+- **Stakeholders**: 3-8 people
+- **Change frequency**: Quarterly updates
+- **Structure**: Some cross-dependencies, multiple layers
+→ **Action**: Use this methodology, focus on [Multi-Map Hierarchy](#multi-map-hierarchy)
+
+### Complex Case (Definitely use this methodology)
+- **Nodes**: 50-200+
+- **Relationships**: 5+ types, bidirectional
+- **Stakeholders**: 10+ people across teams/orgs
+- **Change frequency**: Continuous evolution
+- **Structure**: Dense interconnections, emergent properties
+→ **Action**: Use this methodology, apply [Modular View-Based](#modular-view-based-approach) approach
+
+### Signals You Need Advanced Techniques
+- Creating "hairball" diagrams with crossing edges everywhere
+- Stakeholders can't find relevant information in map
+- Map becomes outdated within weeks
+- Multiple teams need different views of same system
+- Need to show evolution over time
+- System has 100+ nodes that can't be easily decomposed
+
+---
+
+## 2. Mapping Strategies for Scale
+
+### Single Comprehensive Map
+
+**When to use:**
+- 20-50 nodes maximum
+- Single primary use case
+- Stable system (low change rate)
+- Uniform stakeholder audience
+
+**Techniques:**
+- Use aggressive grouping/layering to reduce visual complexity
+- Apply color coding consistently (by type, criticality, ownership)
+- Maximize whitespace between groups
+- Create clear visual hierarchy (size, position, color)
+
+**Example structure:**
+```
+┌─── Frontend Layer ────────────────────┐
+│  UI Components (N1-N5)                │
+│  State Management (N6-N8)             │
+└───────────────────────────────────────┘
+            ↓ API calls
+┌─── Backend Layer ─────────────────────┐
+│  Services (N9-N15)                    │
+│  Business Logic (N16-N20)             │
+└───────────────────────────────────────┘
+            ↓ queries
+┌─── Data Layer ────────────────────────┐
+│  Databases (N21-N25)                  │
+└───────────────────────────────────────┘
+```
+
+### Multi-Map Hierarchy
+
+**When to use:**
+- 50-150 nodes
+- Multiple abstraction levels needed
+- Different audiences need different detail
+- System has natural subsystem boundaries
+
+**Structure:**
+1. **L0 Overview Map** (5-15 nodes): High-level components only
+2. **L1 Subsystem Maps** (10-30 nodes each): Detail within each component
+3. **L2 Detail Maps** (optional): Deep dive into complex subsystems
+
+**Linking approach:**
+- Each L0 node links to its L1 detail map
+- Use consistent naming: `system-overview.md`, `system-auth-subsystem.md`, `system-payment-subsystem.md`
+- Include navigation breadcrumbs in each map
+
+**Example hierarchy:**
+```
+L0: E-commerce Platform Overview
+├─ Frontend (5 nodes) → L1: frontend-detail.md
+├─ API Gateway (3 nodes) → L1: api-gateway-detail.md
+├─ Auth Service (4 nodes) → L1: auth-service-detail.md
+│  └─ JWT Module → L2: auth-jwt-detail.md
+├─ Product Service (8 nodes) → L1: product-service-detail.md
+├─ Payment Service (6 nodes) → L1: payment-service-detail.md
+└─ Data Layer (4 nodes) → L1: data-layer-detail.md
+```
+
+### Modular View-Based Approach
+
+**When to use:**
+- 100+ nodes
+- Multiple stakeholder groups with different concerns
+- Need to show different perspectives of same system
+- High change frequency
+
+**View types:**
+- **Structural view**: What components exist and how they're organized
+- **Dependency view**: What depends on what (for deployment planning)
+- **Data flow view**: How data moves through system
+- **Security view**: Trust boundaries, authentication flows
+- **Operational view**: Monitoring, alerting, ownership
+
+**Approach:**
+1. Maintain single **master node/relationship database** (spreadsheet or JSON)
+2. Generate **filtered views** for specific audiences/purposes
+3. Each view shows subset of nodes/relationships relevant to that concern
+4. Cross-reference between views using node IDs
+
+**Example - same system, different views:**
+
+**View 1: Engineering Deployment Dependencies**
+```
+Shows: All services, databases, external APIs
+Relationships: depends-on, requires, blocks
+Purpose: Determine deployment order, identify risks
+```
+
+**View 2: Product Manager Feature Map**
+```
+Shows: User-facing features, backend services supporting them
+Relationships: enables, requires, affects
+Purpose: Understand feature scope, plan releases
+```
+
+**View 3: Security Boundaries**
+```
+Shows: Services, trust zones, auth components
+Relationships: trusts, authenticates, authorizes
+Purpose: Threat modeling, compliance review
+```
+
+---
+
+## 3. Tool Selection
+
+### Tool Selection Guide
+
+**Text/Markdown:** Quick docs, frequent updates, < 20 nodes, version control critical
+**Mermaid:** 20-40 nodes, markdown integration, flowcharts, version control
+**Draw.io:** 40+ nodes, visual quality matters, presentations, collaborative editing
+**GraphViz:** Automatic layout, 100+ nodes, programmatic generation
+**Specialized (Lucidchart, etc):** Enterprise collaboration, executive presentations, branded templates
+
+---
+
+## 4. Execution Patterns
+
+### Solo Mapping Workflow
+
+**5-step process for 30-50 node maps (70-120 min total):**
+
+1. **Brain dump** (15-30 min): List all nodes without structure, aim for exhaustiveness
+2. **Cluster** (10-15 min): Group related nodes, identify subsystems/themes
+3. **Structure** (20-40 min): Choose format, define relationships, create layers
+4. **Refine** (15-20 min): Add missing nodes, remove redundancy, clarify relationships
+5. **Validate** (10-15 min): Self-check with [rubric](evaluators/rubric_mapping_visualization_scaffolds.json), test understanding
+
+### Collaborative Mapping Workshop
+
+**5-phase process for 2-8 participants (80 min total):**
+
+1. **Setup** (5 min): State purpose/scope, show example, assign roles (Facilitator, Scribe, Timekeeper)
+2. **Individual brainstorm** (10 min): Each person lists 15-20 nodes on sticky notes, no discussion
+3. **Share and cluster** (20 min): Share nodes (2 min each), group similar, merge duplicates, name clusters
+4. **Relationship mapping** (20 min): Draw key relationships, use colors for types, vote on disputed connections
+5. **Structure and refine** (15 min): Choose format together, assign digital creation, document parking lot
+6. **Review and validate** (10 min): Walk through map, identify gaps, assign follow-up owners
+
+**Facilitation tips:** Round-robin participation, park tangents, enforce timeboxes, capture dissent explicitly
+
+---
+
+## 5. Advanced Layout Techniques
+
+### Minimizing Edge Crossings
+
+**Problem:** Complex graphs become "hairballs" with edges crossing everywhere.
+
+**Solutions:**
+
+1. **Layered approach** (works for hierarchies)
+   - Assign nodes to horizontal layers (L1, L2, L3)
+   - Minimize crossings between adjacent layers
+   - Use dummy nodes for long-distance edges
+
+2. **Force-directed layout** (works for networks)
+   - Related nodes pull together
+   - Unrelated nodes push apart
+   - Let GraphViz or similar tool calculate
+
+3. **Manual optimization**
+   - Place highly-connected nodes centrally
+   - Group tightly-coupled nodes
+   - Use orthogonal routing (edges follow grid)
+
+4. **Split the map**
+   - If > 30 edge crossings, split into multiple maps
+   - One map per subsystem
+   - Create overview map showing subsystem relationships
+
+### Handling Bidirectional Relationships
+
+**Problem:** A ↔ B creates visual clutter with two arrows.
+
+**Solutions:**
+
+1. **Single line with double arrow**: `A ←→ B`
+2. **Annotate relationship**: `A ←[reads/writes]→ B`
+3. **Split by type**:
+   - Show `A → B` for "calls"
+   - Show `B → A` for "sends events"
+4. **Separate views**: One for each direction
+
+### Visual Hierarchy Patterns
+
+**Use visual weight to show importance:**
+
+```
+Size:
+  ┌────────────┐     ← Critical component (large)
+  │  Database  │
+  └────────────┘
+
+  ┌────────┐         ← Standard component (medium)
+  │ Service │
+  └────────┘
+
+  ┌────┐             ← Utility (small)
+  │Util│
+  └────┘
+
+Color/Style:
+  ██████ Core system (solid, dark)
+  ▓▓▓▓▓▓ Standard (solid, medium)
+  ░░░░░░ Optional (light/dotted)
+
+Position:
+  Top → High-level/strategic
+  Middle → Tactical
+  Bottom → Implementation details
+```
+
+---
+
+## 6. Validation Approaches
+
+### Structured Review Process
+
+**Step 1: Completeness check (5-10 min)**
+Ask reviewers:
+- "What critical components are missing?"
+- "What relationships are incorrect or missing?"
+- "What groupings don't make sense?"
+
+**Step 2: Accuracy verification (10-15 min)**
+For each subsystem:
+- Assign subject matter expert
+- Verify node descriptions
+- Validate relationship types and directionality
+- Confirm groupings
+
+**Step 3: Usability test (5 min)**
+Give map to someone unfamiliar:
+- Can they answer basic questions from the map?
+- "Which components depend on X?"
+- "What happens if Y fails?"
+- "Who owns component Z?"
+
+**Step 4: Scenario walkthrough (10-15 min)**
+Pick 3-5 scenarios:
+- "A user logs in" - trace through the map
+- "We deploy service X" - identify impacts
+- "Database Y goes down" - find affected components
+
+### Validation Metrics
+
+Track these across iterations:
+
+- **Coverage**: % of known components included
+- **Accuracy**: % of relationships verified by SMEs
+- **Usability**: # of correct answers in usability test
+- **Completeness**: # of gaps identified in reviews
+- **Consensus**: % of stakeholders agreeing on structure
+
+**Target thresholds:**
+- Coverage ≥ 95% (all critical + most secondary)
+- Accuracy ≥ 90% (verified by SMEs)
+- Usability ≥ 70% (most questions answered correctly)
+
+---
+
+## 7. Maintenance and Evolution
+
+### Update Strategies
+
+**Reactive (as-needed):**
+- Update when someone reports inaccuracy
+- Quarterly review cycle
+- Works for stable systems
+- **Risk**: Map becomes stale, people stop trusting it
+
+**Proactive (systematic):**
+- Assign ownership to specific people/teams
+- Integrate into change processes (new service → update map)
+- Automated checks (compare with service registry, org chart)
+- **Benefit**: Map stays current, becomes trusted resource
+
+### Version Control Patterns
+
+**For text-based maps (Markdown, Mermaid):**
+- Store in Git alongside code
+- Include map updates in PRs that change architecture
+- Use conventional commits: `docs(map): add new payment service`
+- Tag versions: `v1.0-system-map-2024Q4`
+
+**For visual tools (Draw.io, Lucidchart):**
+- Export to version control (XML, JSON) regularly
+- Maintain changelog in separate document
+- Create dated snapshots: `architecture-2024-11-12.drawio`
+
+### Dealing with Drift
+
+**Symptoms of map drift:**
+- Stakeholders reference outdated information
+- Multiple competing maps exist
+- Last update > 6 months ago
+- New team members don't use it
+
+**Recovery process:**
+1. **Audit current state** (1-2 days): Compare map to reality
+2. **Triage errors**: Critical fix (wrong), update (outdated), remove (obsolete)
+3. **Batch update session**: Fix all at once, not incrementally
+4. **Re-validate**: Get stakeholder sign-off
+5. **Establish maintenance**: Assign owners, set review cadence
+6. **Sunset old maps**: Archive competing/outdated versions
+
+---
+
+## 8. Domain-Specific Patterns
+
+### Software Architecture
+**Focus:** Service boundaries, data flows, deployment dependencies, scalability bottlenecks
+**Relationships:** `calls`, `publishes/subscribes`, `reads/writes`, `depends-on`
+**Layers:** Presentation (web/mobile/API), Application (services/logic), Data (databases/caches/queues)
+
+### Organizational Structure
+**Focus:** Reporting relationships, communication patterns, decision authority, ownership
+**Relationships:** `reports-to`, `collaborates-with`, `escalates-to`, `consults`
+**Groupings:** By function, product line, or location
+
+### Process/Workflow
+**Focus:** Step sequence, decision points, handoffs, bottlenecks
+**Relationships:** `leads-to`, `branches-on`, `requires-approval`, `escalates`
+**Formats:** Swimlane (multiple actors), decision tree (conditionals), linear flow
+
+---
+
+## 9. Troubleshooting Common Issues
+
+### Issue: Map is too cluttered
+
+**Symptoms:** Can't see structure, edges cross everywhere, hard to scan
+
+**Fixes:**
+1. Increase grouping - combine nodes into subsystems
+2. Split into multiple maps (overview + detail)
+3. Remove transitive relationships (if A→B→C, remove A→C)
+4. Use different views for different audiences
+
+### Issue: Stakeholders disagree on structure
+
+**Symptoms:** Debates about groupings, relationship directions, what's included
+
+**Fixes:**
+1. Document perspectives explicitly: "Engineering view shows X, Product view shows Y"
+2. Create view-specific maps rather than one "true" map
+3. Focus on agreed-upon core, mark disputed areas
+4. Use validation scenarios - test both structures
+
+### Issue: Map becomes outdated quickly
+
+**Symptoms:** Weekly corrections needed, people stop using it
+
+**Fixes:**
+1. Reduce scope - map stable core only
+2. Assign clear ownership and update process
+3. Automate where possible (generate from config files)
+4. Accept "directionally correct" vs "perfectly accurate"
+
+### Issue: Can't decide on visualization format
+
+**Symptoms:** Trying multiple formats, none feels right
+
+**Fixes:**
+1. Match format to relationship pattern:
+   - Hierarchy → Tree
+   - Network → Graph
+   - Sequence → Swimlane/Flow
+2. Create small prototype in each format (10 nodes)
+3. Test with stakeholder: "Which helps you understand better?"
+4. It's okay to use different formats for different subsystems
+
+---
+
+## 10. Success Patterns from Practice
+
+1. **Start messy, refine clean** - Brain dump first, organize later
+2. **Version with system** - Map updates = part of change process
+3. **Multiple maps > mega-map** - 5 focused maps beat 1 hairball
+4. **Show evolution** - Include roadmap/changelog views
+5. **Make navigable** - Links between maps, collapsible sections, filters
+6. **Visual conventions matter** - Document notation, consistency > perfection
+7. **Involve stakeholders early** - Collaborative mapping = shared understanding + buy-in
+8. **Test usability continuously** - If people can't answer questions, it's not useful
+
+---
+
+## When to Apply This Methodology
+
+Use this methodology if you're:
+
+✓ Mapping systems with 50+ nodes
+✓ Managing multiple stakeholder perspectives
+✓ Needing to maintain maps over time (not one-off)
+✓ Creating maps for diverse audiences (technical + non-technical)
+✓ Dealing with high system complexity or frequent change
+✓ Facilitating group mapping sessions
+✓ Generating maps programmatically from data
+✓ Building a "living documentation" practice
+
+Go back to [template.md](template.md) if you're:
+✗ Mapping simple systems (< 20 nodes)
+✗ Creating one-off documentation
+✗ Working alone with single audience
+✗ Time-constrained (need map in < 1 hour)
--- a/skills/mapping-visualization-scaffolds/resources/template.md
+++ b/skills/mapping-visualization-scaffolds/resources/template.md
@@ -0,0 +1,407 @@
+# Mapping & Visualization Scaffolds Template
+
+## Workflow
+
+Copy this checklist and track your progress:
+
+```
+Template Progress:
+- [ ] Step 1: Define map metadata
+- [ ] Step 2: List all nodes
+- [ ] Step 3: Define relationships
+- [ ] Step 4: Choose visualization format
+- [ ] Step 5: Create the visualization
+- [ ] Step 6: Add legend and insights
+```
+
+**Step 1: Define map metadata**
+
+Fill out the Map Metadata section in the Quick Template with title, purpose, audience, and scope. This ensures the map serves the right goal. See [Section Guidance - Map Metadata](#1-map-metadata) for details.
+
+**Step 2: List all nodes**
+
+Complete the Nodes section in the Quick Template with all key elements (components, concepts, entities). Include brief descriptions. See [Section Guidance - Nodes](#2-nodes) for what to include.
+
+**Step 3: Define relationships**
+
+Document the Relationships section in the Quick Template with connections between nodes. Specify type and directionality. See [Section Guidance - Relationships](#3-relationships) for relationship types.
+
+**Step 4: Choose visualization format**
+
+Select from [Visualization Formats](#visualization-formats): List, Tree, Graph, or Layered based on complexity and relationship patterns. See [Format Selection Guide](#format-selection-guide).
+
+**Step 5: Create the visualization**
+
+Build the Visualization section in the Quick Template using your chosen format. Start with high-level structure, then add details. See [Visualization Formats](#visualization-formats) for examples.
+
+**Step 6: Add legend and insights**
+
+Complete the Legend and Insights sections in the Quick Template if needed, documenting discoveries from mapping. See [Quality Checklist](#quality-checklist) before finalizing.
+
+---
+
+## Quick Template
+
+Copy this structure to `mapping-visualization-scaffolds.md`:
+
+```markdown
+# [Map Title]
+
+## Map Metadata
+
+**Purpose:** [Why this map exists, what decisions it informs]
+**Audience:** [Who will use this map]
+**Scope:** [What's included/excluded]
+**Date:** [YYYY-MM-DD]
+**Author:** [Name or team]
+
+## Nodes
+
+List all key elements:
+
+| Node ID | Name | Type | Description |
+|---------|------|------|-------------|
+| N1 | [Node name] | [Component/Concept/Person/Step] | [Brief description] |
+| N2 | [Node name] | [Type] | [Brief description] |
+| N3 | [Node name] | [Type] | [Brief description] |
+
+## Relationships
+
+Define connections between nodes:
+
+| From | To | Relationship Type | Description |
+|------|-----|-------------------|-------------|
+| N1 | N2 | [depends-on/calls/contains/leads-to] | [Details about this connection] |
+| N2 | N3 | [Type] | [Details] |
+
+## Groupings/Layers
+
+Organize nodes into logical groups:
+
+- **[Group 1 Name]:** N1, N2
+- **[Group 2 Name]:** N3, N4
+- **[Group 3 Name]:** N5, N6
+
+## Visualization
+
+[Insert your map using chosen format - see options below]
+
+## Legend
+
+**Node Types:**
+- [Symbol/Color] = [Type]
+
+**Relationship Types:**
+- → = [Meaning]
+- ⇒ = [Meaning]
+- ↔ = [Meaning]
+
+## Insights and Observations
+
+**Key Findings:**
+- [Important discovery from mapping]
+- [Unexpected dependency or pattern]
+- [Critical path or bottleneck]
+
+**Recommendations:**
+- [Action based on map insights]
+
+**Limitations:**
+- [What's not captured in this map]
+- [Known gaps or uncertainties]
+```
+
+---
+
+## Visualization Formats
+
+### Format 1: Simple List (< 10 nodes, simple relationships)
+
+```
+API Gateway
+├─→ Auth Service
+│   └─→ User Database
+├─→ Product Service
+│   ├─→ Product Database
+│   └─→ Cache Layer
+└─→ Payment Service
+    └─→ Payment Database
+```
+
+**When to use:** Linear flows, simple hierarchies, few cross-dependencies
+
+### Format 2: Tree Diagram (hierarchical relationships)
+
+```
+                    Application
+                        |
+        ┌──────────────┼──────────────┐
+        |              |              |
+    Frontend       Backend         Data
+        |              |              |
+    ┌───┴───┐      ┌───┴───┐      ┌───┴───┐
+   UI  Auth     API  Logic    DB  Cache
+```
+
+**When to use:** Org charts, taxonomies, clear parent-child relationships
+
+### Format 3: Network Graph (complex interconnections)
+
+```
+    ┌─────────┐
+    │  User   │
+    └────┬────┘
+         │
+    ┌────▼────┐     ┌──────────┐
+    │  Auth   │────→│  Logs    │
+    └────┬────┘     └──────────┘
+         │
+    ┌────▼────┐     ┌──────────┐
+    │ Service │────→│ Database │
+    └────┬────┘     └──────────┘
+         │              ▲
+         │              │
+    ┌────▼────┐         │
+    │  Cache  │─────────┘
+    └─────────┘
+```
+
+**When to use:** Microservices, complex dependencies, bi-directional relationships
+
+### Format 4: Layered Diagram (system architecture)
+
+```
+┌─────────────────────────────────────────────┐
+│  Presentation Layer                         │
+│  [Web UI]  [Mobile App]  [API Docs]        │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│  Business Logic Layer                       │
+│  [Auth] [Users] [Products] [Payments]      │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│  Data Layer                                 │
+│  [PostgreSQL]  [Redis]  [S3]               │
+└─────────────────────────────────────────────┘
+```
+
+**When to use:** System architectures, layered designs, clear abstraction levels
+
+### Format 5: Swimlane/Matrix (responsibilities, workflows)
+
+```
+| Step | Frontend | Backend | Database | External |
+|------|----------|---------|----------|----------|
+| 1. Request | Send login | - | - | - |
+| 2. Validate | - | Check credentials | Query users | - |
+| 3. Token | - | Generate JWT | - | - |
+| 4. Store | Receive token | - | Update session | Log event |
+| 5. Redirect | Show dashboard | - | - | - |
+```
+
+**When to use:** Process flows with multiple actors, workflow documentation
+
+---
+
+## Format Selection Guide
+
+**Choose based on:**
+
+| Characteristic | Recommended Format |
+|----------------|-------------------|
+| < 10 nodes, linear flow | Simple List |
+| Clear hierarchy, one parent per child | Tree Diagram |
+| Many cross-dependencies, cycles | Network Graph |
+| Multiple abstraction layers | Layered Diagram |
+| Multiple actors/systems in process | Swimlane/Matrix |
+| Time-based sequence | Swimlane or Simple List |
+| Spatial/geographic relationships | Custom diagram with coordinates |
+
+**Complexity thresholds:**
+- **10-20 nodes:** Use grouping and colors
+- **20-50 nodes:** Create multiple focused maps or use layered approach
+- **50+ nodes:** Definitely split into multiple maps
+
+---
+
+## Section Guidance
+
+### 1. Map Metadata
+
+**Purpose:** Be specific about the map's goal
+- ✓ "Understand microservices dependencies to identify deployment risks"
+- ✗ "Show system architecture"
+
+**Audience:** Tailor detail level to reader
+- Technical team: Include implementation details
+- Executives: Focus on high-level components and costs
+- New team members: Add more context and explanations
+
+**Scope:** Explicitly state boundaries
+- "Includes all production services; excludes development tools"
+- "Shows user-facing journey; excludes backend processing"
+- "Maps current state as of 2024-Q4; does not include planned features"
+
+### 2. Nodes
+
+**What to include:**
+- **ID**: Short identifier (N1, N2, or descriptive like "AUTH")
+- **Name**: Clear, consistent naming (same conventions throughout)
+- **Type**: Component, Concept, Person, Step, System, etc.
+- **Description**: Brief (< 20 words) explanation of purpose or role
+
+**Naming conventions:**
+- Use consistent casing (PascalCase, snake_case, or kebab-case)
+- Be specific: "User Authentication Service" not just "Auth"
+- Avoid acronyms unless universally understood
+
+**Examples:**
+```
+N1 | API Gateway | Service | Routes external requests to internal services
+N2 | Auth Service | Service | Validates user credentials and generates JWTs
+N3 | User DB | Data Store | PostgreSQL database storing user profiles
+```
+
+### 3. Relationships
+
+**Common relationship types:**
+
+**Dependency relationships:**
+- `depends-on` - A needs B to function
+- `requires` - A cannot start without B
+- `blocks` - A prevents B from proceeding
+- `enables` - A makes B possible
+
+**Data relationships:**
+- `reads-from` - A consumes data from B
+- `writes-to` - A modifies data in B
+- `sends-to` - A transmits messages/events to B
+- `receives-from` - A gets messages/events from B
+
+**Structural relationships:**
+- `contains` / `part-of` - Hierarchical containment
+- `is-a` / `extends` - Type relationships
+- `implements` - Interface implementation
+- `uses` / `calls` - Service invocation
+
+**Process relationships:**
+- `leads-to` / `follows` - Sequential steps
+- `triggers` - Event causation
+- `approves` / `rejects` - Decision flows
+- `escalates-to` - Authority chain
+
+**Specify directionality:**
+- Use clear arrows: A → B (A to B)
+- Note bi-directional: A ↔ B
+- Include cardinality if relevant: A →[1:N]→ B
+
+### 4. Groupings/Layers
+
+**When to group:**
+- Logical subsystems (Frontend, Backend, Data)
+- Organizational boundaries (Team A, Team B)
+- Phases or stages (Planning, Execution, Review)
+- Environments (Dev, Staging, Production)
+- Abstraction levels (Strategic, Tactical, Operational)
+
+**Grouping strategies:**
+- **By function**: All authentication-related nodes
+- **By owner**: All nodes maintained by Team X
+- **By layer**: All presentation-layer nodes
+- **By lifecycle**: All legacy vs. new nodes
+- **By criticality**: Core vs. optional nodes
+
+## Quality Checklist
+
+Before finalizing your map, verify:
+
+**Completeness:**
+- [ ] All critical nodes identified
+- [ ] All significant relationships documented
+- [ ] Groupings clearly labeled
+- [ ] Legend provided if > 3 relationship types
+
+**Clarity:**
+- [ ] Consistent naming conventions
+- [ ] Clear directionality on relationships
+- [ ] Appropriate level of detail for audience
+- [ ] No overlapping or ambiguous connections
+
+**Accuracy:**
+- [ ] Relationships verified with SMEs or documentation
+- [ ] Current state (not outdated)
+- [ ] No missing critical dependencies
+- [ ] Scope boundaries clearly stated
+
+**Usability:**
+- [ ] Can target audience understand without explanation?
+- [ ] Is the visualization scannable (not a "hairball")?
+- [ ] Are insights or key findings highlighted?
+- [ ] Is next action or decision clear?
+
+**Technical:**
+- [ ] File saved as `mapping-visualization-scaffolds.md`
+- [ ] Markdown formatting correct
+- [ ] Links and references work
+- [ ] Version/date included
+
+---
+
+## Common Patterns by Domain
+
+**Software Architecture:**
+- Nodes: Services, databases, message queues, APIs
+- Relationships: Calls, reads/writes, publishes/subscribes
+- Groupings: Layers (presentation, business, data)
+
+**Knowledge/Concept Mapping:**
+- Nodes: Concepts, theories, terms, examples
+- Relationships: Is-a, has-a, leads-to, contradicts
+- Groupings: Themes, disciplines, abstraction levels
+
+**Project Planning:**
+- Nodes: Tasks, milestones, deliverables
+- Relationships: Depends-on, blocks, follows
+- Groupings: Phases, sprints, teams
+
+**Organizational:**
+- Nodes: People, teams, roles, functions
+- Relationships: Reports-to, collaborates-with, approves
+- Groupings: Departments, locations, levels
+
+**Process/Workflow:**
+- Nodes: Steps, decisions, handoffs
+- Relationships: Leads-to, triggers, approves/rejects
+- Groupings: Swimlanes (actors), phases
+
+---
+
+## Tips for Effective Maps
+
+**Start Simple:**
+1. Begin with 5-10 most important nodes
+2. Add critical relationships only
+3. Expand if needed, but resist over-complication
+
+**Use Visual Hierarchy:**
+- Size: Larger nodes = more important
+- Position: Top = start, Bottom = end (for flows)
+- Grouping: Visual proximity = logical grouping
+
+**Iterate:**
+- Create draft, get feedback, refine
+- Test understanding with someone unfamiliar
+- Simplify based on confusion points
+
+**Know When to Split:**
+- If map has > 30 nodes, consider multiple maps
+- Create one high-level overview + detailed sub-maps
+- Link related maps together
+
+**Common Improvements:**
+- Add color coding for node types
+- Use different line styles for relationship types
+- Include metrics or attributes on nodes (e.g., latency, importance)
+- Highlight critical paths or bottlenecks